The InstaFox Wizard

In this section of the appendix, we demonstrate the use of the InstaFox Wizard to create a basic installation setup for the DeployFox Demo App. In a later section we examine the resulting setup table and show how to make changes to it.

The InstaFox Wizard walks you through a sequence of steps prompting you for the information necessary to create your application setup. You need to make some decisions along the way. If you are unsure what to choose, accept the defaults. The InstaFox Wizard is reentrant so you can run the Wizard as many times as you need to make required changes. All changes are kept as long as you click the ‚“Finish ‚½ button. Clicking ‚“Cancel ‚½ at any time throws away any changes made. You may also make changes directly in the InstaFox FoxPro table (WZ_INS.DBF) where the data you just entered is stored.

To start the InstaFox Wizard, double click the IFWIZARD.EXE file in the WIZDIR folder under your setup installation folder. The wizard opens with the screen for Step 1 ‚ General Installation ‚ Page 1 as shown in Figure 4 . The wizard fields with pink backgrounds are required fields. You will also notice there are buttons to the left of certain fields with a ‚“? ‚½ button on them. Click this button for more information about that field.

Figure 4. Step 1 of InstaFox Wizard prompts you for the basic information about your application.

In Step 1, Page 1 of the InstaFox Wizard you provide the basic information about your application. The name of the application is the name the developer and end users have given to the application. ‚“DeployFox Sample Application ‚½ and ‚“Acme Marketing Application ‚½ are examples of application names .

The name of the main EXE for the application box is the name of the program that runs when the user clicks on one of the icons (shortcuts) for the application. This field is optional because there may be times when a developer only wants to install (copy) files into a particular folder. There is no main EXE. InstaFox itself is an example of this. It does not have a ‚“main executable, ‚½ it only copies files to folders. If you choose to fill out this optional information, the file must be in the root of the APPDIR folder. DEPLOYFOXDEMO.EXE and ACMEMKT.EXE are examples of main EXE names.

Note ‚  

You can use the Ellipses ( ‚ ) button as a convenience to take you directly to your main executable in the APPDIR folder. Clicking on the Ellipses button displays the open /find file dialog box giving you the false impression that you can choose a file from any folder. If you choose a file outside the APPDIR folder, the name of the main executable textbox is left blank. That is, the selected file is not placed in the textbox. This is the product ‚ s way of letting you know the file you chose is not in the APPDIR folder, there is no message displayed that indicates the file selected is an invalid choice. Another ‚“gotcha ‚½ is you can type in a path and main executable name like C:\TEST\MYAPP.EXE, but there is no validation done or message displayed to indicate the file entered won ‚ t be included in the installation.

We would like to see an error message displayed if a file is chosen outside of the APPDIR folder or if an invalid path is typed in. We could have contacted Fowler Software about this, but InstaFox comes with the source code so we can customize the wizard to operate to our individual needs and tastes.

InstaFox has two modes of installation ‚ installing an application for the first time and upgrading an installation. The mode selected by the InstaFox Installer depends partly on the default installation path, whether an EXE already exists there or not, and whether the ‚“search for application ‚½ option was checked.

The default installation path box is where you enter a fully qualified path including drive letter of where you want the InstaFox Installer to install your application. The default behavior of the InstaFox Installer is to search for an existing application in the specified default install path. If an existing EXE is at this location, it processes the install as an upgrade. The user does not get an option of specifying an install path. If the EXE is not found in the specified install path, it is treated as a first time installation.

But what happens if the EXE is not in the default installation path? Some users are known to install applications in other locations rather than the suggested default. This is where the ‚“search for application ‚½ option comes into play. If the EXE is not found in the default installation path and the ‚“search for application ‚½ option was checked, InstaFox Installer searches the C drive and if the EXE is found but in a different path other than the specified default, that EXE and that path are used to upgrade the existing application and the user is not even given an option of specifying a path. If the EXE is not found on the C drive at all, the install is treated as a new installation and the user may specify an installation path.

There are also times when you or your users may require you to create an installation that requires the application to be installed at a specific path. If this is the case, this modification must be made to the InstaFox source code. Modifying the source code is discussed in more detail in the section ‚“Customizing InstaFox ‚½ later in this appendix.

Figure 5 shows Step 2 - General Installation - Page 2. In step 2 of the InstaFox Wizard you specify some additional optional information about your application. This page is mostly self-explanatory. You can include an optional image to display on the screen during installation. This image must be a BMP, JPG, or GIF file, and must be in the root of the APPDIR folder.

Figure 5. Step 2 of the InstaFox wizard asks for the optional files.

The name of the folder where the database container and tables reside can be included here. This folder must be in the root of the APPDIR folder. If you want to display a license agreement during installation the name of the license file must be included here. The license file itself must reside in the root of the APPDIR folder and be in RTF format. If this field is left blank, the installer will skip the License Agreement screen.

The only required field in this step is the version number. Enter the application ‚ s version number (3.0 or 3.2.10, etc.)

If you want to run a program after the installation is complete, enter the name of that program here. UPDATETHEDATA.EXE is an example of a post-installation program. This example program would run immediately after installation to update any structure changes or additional data requirements for one or more tables in a customer ‚ s database. This might only apply to developers using a non-VFP database or those not using a tool like Stonefield Database Toolkit (SDT). SDT allows developers to add functionality directly to the application that ‚“automatically ‚½ updates the changes to the database. In the case of a fresh install, a post-installation program could actually create the initial database, CREATETHEDATA.EXE.

Step 3 of the InstaFox Wizard ( Figure 6 ) is where you enter the information for registry updates. This step is very self-explanatory. Checking the ‚“notify user if existing application is found ‚½ option tells the InstaFox Installer to notify the user of the location of the existing installation and give the user the option of installing a new version in the same folder.

Figure 6. Step 3 of the InstaFox wizard asks for the base registry information.

If there is an icon associated with the application, enter the name of the ICO file in the icon text box. If there is a registry key associated with the application enter the name to look for in the registry application name text box. If there is a registry value for the path to the application, enter it in the last text box. An example of this would be, ‚“HKEY_LOCAL_MACHINE\Software\DeployFoxDemoApp. ‚½

In addition to specifying where your main registry entry should go, Step 4 of the InstaFox Wizard allows you to make as many registry entries as you want. For example, you may want to add a registry entry for the version being installed. In this case put ‚“Version ‚½ in the Registry Key Name column and ‚“3.0 ‚½ in the Registry Key column as shown in Figure 7.

Figure 7. Step 4 of the InstaFox wizard asks for additional registry entries.

In Step 5 of the InstaFox Wizard you identify your contact information. This information is displayed if the user cancels the installation or encounters a problem during installation. Figure 8 shows a filled out Step 5 form.

Figure 8. Step 5 of the InstaFox Wizard ‚ Contact Information.

In Step 6 of the InstaFox Wizard you set up one of the main features of the InstaFox Installer ‚ automatically updating the table structures for an existing installation while maintaining existing data. You have the option of letting the installation procedure overwrite the data, if the existing data should not be preserved. Select the overwrite column to turn on this option. Figure 9 shows a sample of updating the CUSTOMERS.DBF included in the DeployFoxDemoApp installation.

Figure 9. Step 6 of the InstaFox Wizard ‚ Tables to Update.

You can enter in each table one at a time by clicking the Add Line button and making the entry or click the Load Data button to have the wizard automatically load all the data from the data folder specified in Step 2. If you do not have a folder specified in Step 2, clicking Load Data only loads DBF type files from the APPDIR folder.

Step 7 of the InstaFox Wizard is where you set up for the removal of any existing installation files no longer needed. Click the Add Line button to add a new line and enter a file name with the relative path if the file is not in the root directory. Figure 10 shows a sample of removing files from the DeployFoxDemoApp folder.

Figure 10. Step 7 of the InstaFox Wizard ‚ Files to Remove.

Step 8 of the InstaFox Wizard is where you provide the list of files to install. You can easily populate this list by clicking the Load Files button. After clicking the Load Files button, you will see a list of all of the files included in the APPDIR folder. These are the files to be placed on the target computer. The first thing you need to do is review this list. If you notice there are files required, but not listed, add them to the APPDIR folder and run the Wizard again. Delete any files not to be installed. Figure 11 shows the result of clicking the Load Files button.

Figure 11. Step 8 of the InstaFox Wizard ‚ Files to Install. Results immediately after clicking Load Files.

As you can see from Figure 11, Load Files automatically includes files from the WIZDIR folder. These tables tell the InstaFox Installer how to do the installation. These files must be included in the distribution. They do not have to be installed on the target computer and should be removed from this list of files to install. You should delete all files that begin with ‚“WIZ ‚½ or ‚“WZ ‚½. Figure 12 shows the resultant set of files to be installed after removing the WIZDIR folder files. We felt this behavior was slightly annoying. Any time we needed to add a file to be installed all of this other ‚“baggage ‚½ came along and we had to delete it. We mentioned our frustration to the developers at Fowler Software here ‚ s what they had to say:

Figure 12. Step 8 of the InstaFox Wizard ‚ Files to Install. Results after removing the WIZDIR folder files.

‚“Automatically including the WIZDIR files in the list of distribution files was an issue we debated a lot. There are pros and cons. The pros are that if these are included in the installation, then the installed application can look at these files to determine what was installed and where. This may be something the application would want to know. Also, if the application has some sort of uninstall feature, then it will need to know what files were installed and where. It can get this information from the files in the WIZDIR. Of course, the con side is that if you don ‚ t want to install these, then you have to delete them from the list.

The thinking went something like this: It ‚ s a lot easier to delete these than it is to add them, if they are not automatically included. You probably only automatically load the files once, then just adjust the list (with add and delete buttons) later if needed. ‚½

What the Load Files method does ‚“behind the scenes ‚½ is parse the APPDIR folder examining each file and folder. When a folder is found, the files and folders in it are examined. For every file found, the InstaFox Wizard decides whether to include it in the list of files to install. If the file is included, a record is created in the WZ_INS.DBF table with the information about the file.

There are certain files excluded during the Load process. A file is excluded if it is in the data folder, it is a FoxPro file (DBC, DBF, CDX, etc.), and the table has already been listed in the Step 6 ‚ Tables to Update. It must meet all three criteria to be excluded.

Note ‚  

Most VFP developers who use VFP tables also use database container files. Our sample application does not use a database container file. The database container files are also excluded during the load process.

To delete an entry, select the row you want to delete by clicking it, and then click the Delete Line button.

Next, you identify where the files are to be installed by using the drop-down list in the Location column and choosing one of its three options:

1. (blank) ‚ Install the file under the application folder selected by the user when the InstaFox Installer is run. For instance, if the user specifies the application be installed in C:\DeployFoxDemo and the listed file name is IMAGES\COVER_IMAGE.BMP, the COVER_IMAGE.BMP is placed in C:\DeployFoxDemo\Images.

2. {windir} ‚ Install the file in the Windows folder. On a Windows 95/98/Me system, this is commonly named ‚“WINDOWS ‚½ and on a Windows NT/2000/XP system, this is commonly named ‚“WINNT ‚½. The InstaFox Installer will ask the Windows system for the name and location of the ‚“Windows ‚½ folder and make sure the file goes in the correct folder.

3. {winsysdir} ‚ Install the file in the ‚“Windows System ‚½ folder. This is normally the ‚“System ‚½ or ‚“System32 ‚½ folder under the ‚“Windows ‚½ folder, but it can be named differently. The InstaFox Installer will ask the Windows system for the name and location of the ‚“Windows System ‚½ folder and make sure the file goes into the correct folder.

The ‚“Register ‚½ column of the grid contains a checkbox that, if checked, tells the InstaFox Installer to register the file by running the RegSrv32 program. Normally, only files like DLLs and OCXs are registered. You are not limited to the files you can register as the Wizard lets you check this box on any file.

The ‚“Ver Check ‚½ column of the grid also contains a checkbox that, if checked, tells the InstaFox Installer to look for an existing copy of the file in the specified target folder. If no copies of the file exist in the target folder, the file is copied as usual. If an existing copy is found the installer checks the version of the existing file. If it is an older version of the file you are distributing, it is overwritten. If the existing file version is newer , it is not overwritten.