Stonefield Query includes an extensive HTML Help (CHM) file that describes all the dialogs and provides tutorials and a "how to" section. However, it's likely you'll need to customize this help file, especially if you change the Application Name or other configuration settings. Fortunately, the Configuration Utility can do much of the work for you.

Creating a Help Project

To create a customized help project for your Stonefield Query project, choose Create Help Files from the File menu or the shortcut menu or click the Create Help Files button in the toolbar. This creates a subdirectory of the current Stonefield Query project directory called HTMLHelp and places the help project files into this subdirectory. The project files are customized according to the current configuration settings. For example, all references to "Stonefield Query" are changed to the value you specify for the Application Name configuration setting.

Two types of help projects are created. The first is a Microsoft HTML Help Workshop project. HTML Help Workshop comes with many Microsoft development environments, but you can also download it from Microsoft's Web site (http://msdn.microsoft.com; search for "html and help" and choose the download link from the results). The main file for this project type is SFQuery.HHP.

The other type of project is a West Wind HTML Help Builder project. HTML Help Builder, from West Wind Technologies (http://www.west-wind.com) is a great, inexpensive utility for creating HTML Help files. It was used to create the help files for both Stonefield Query and the Configuration Utility. The main file for this project type is SFQuery.HBP.

Customizing a Help Project

Although the Create Help Files function does much of the customization work for you, you will likely have to customize additional things in the generated help project. Here are the most common topics to customize:

• Customize the two topics under the Tutorial heading to match your specific application's data.

• The Example topic under Using Stonefield Query, Creating a Quick Report, Step 2: Data Selection, Advanced Report Designer describes using the Advanced Report Designer on the report created in Lesson 1 of the tutorial, so customize it accordingly as well.

• Although it isn't required, you may wish to change the fields used in the Creating a PivotTable Report Using Microsoft Excel and Creating Labels or Formletters Using Microsoft Word topics.

• The Technical Support topic under the Stonefield Query (or whatever you change the Application Name property to) heading should have your company's contact information rather than Stonefield's.

• If you set the User Can Manage Data Sources configuration setting to True, you may want to customize the information in the Creating an ODBC Data Source topic (under the Managing Database topic, which is in the How To section), depending on the ODBC drivers the application uses.

• Recreate images in the help file showing screen shots of the product name and logo. You can use any tool you wish to create these screen shots; we use and recommend SnagIt from TechSmith Software (www.techsmith.com). The topics and images affected are (all images are located in the HTMLHelp\Images subdirectory of your Stonefield Query project directory):
  • Your application name (the topmost section), Running your application name: the welcome dialog (WELCOME.GIF) and the login dialog, either with a database selection (LOGIN.GIF) if the Allow Multiple Data Sources configuration setting is set to True or without a database selection (LOGIN2.GIF) if that setting is False. (LOGIN.GIF is also listed below because it shows the Description for Data Sources setting.)

  • Menu Functions, Help Menu: the About function in the Help menu (ABOUT.GIF). (This screen shot is also listed below if you create an About.Settings script.) You may wish to remove the version number from the screen shot so you don't have to recreate it for every release.

  • How To, Activating your application name: the Registration form displayed when you activate Stonefield Query (REGISTRATION.GIF). You may wish to remove the version number from the screen shot so you don't have to recreate it for every release. Note: the simplest way to display this dialog is to temporarily rename your license file (SFQuery.LIC in the Data subdirectory of the Stonefield Query program directory), run Stonefield Query, and when prompted to activate it, choose Yes. You can then rename the license file back to SFQuery.LIC.

  • How To, Setting up your application name: the Setup dialog, displayed the first time Stonefield Query is run (SETUP.GIF if the Need Target Application Directory setting is False or SETUPTARGETAPP.GIF if that setting is True. You may wish to remove the version number from the screen shot so you don't have to recreate it for every release. Note: the simplest way to display this dialog so you can take a screen shot of it is to run Stonefield Query with "ACTION=SETUP" added to the command line or add an Other section to SFQuery.INI and create an Action entry under that section with a value of Setup. For example:

    [Other]
    Action=Setup

• If you create an About.Settings script, create a screen shot of the About dialog called ABOUT.GIF (displayed in the Menu Functions, Help Menu topic). (This screen list is also listed above because it shows the product name and logo.)

• If you turn off the Support online updates or Support maintenance reminder configuration settings or create an Options.Settings script, create a screen shot of the Tools, Options dialog called OPTIONS1.GIF if you have the Support Multi-Languages configuration setting turned on or OPTIONS1NOLANG.GIF if you have that setting turned off, and describe any additional options you defined in the Options.Settings script in the Configuring Stonefield Query help topic under the How To section.

• If you change the Description for Data Sources setting, create the following screen shots:
  • If you set the User Can Manage Data Sources setting to True, the Tools, Manage Databases dialog: DBMANAGER.GIF (displayed in the How To, Managing Databases topic).

  • Open Database dialog: OPENDATASOURCE.GIF (displayed in the How To, Selecting the (your description for database).

  • If the Allow Multiple Data Sources setting is set to True, the login dialog: LOGIN.GIF (displayed in the Running your application name topic under the topmost heading). (This screen list is also listed above because it shows the product name.)

  • The options page of the Reports Explorer: SFRWIZARD4.GIF (displayed in the Report Options topic under the Using your application name heading).

  • Step 5 of the Quick Report Wizard: SFRWIZARDNEW5.GIF (displayed in the Step 5: Formatting Options (Quick Report) topic under the Creating a Quick Report heading).

  • Step 5 of the Cross-Tab Report Wizard: XTABWIZARD5.GIF (displayed in the Step 5: Formatting Options (Cross-Tab Report) topic under the Creating a Cross-Tab Report heading).
    

  Also, if you set the Allow Queries on Multiple Data Sources setting to True, create the following screen shots as these images all show the word "Databases":

  • The Filter page of the Reports Explorer: SFRWIZARD2MULTIPLE.GIF (displayed in the Using your application name, Selecting Which Records to Include topic)

  • The dialog that displays when you click the Databases button on the Filter page: SELECTDATABASES.GIF (displayed in the same help topic)

  • The filter step of the Quick Report Wizard: SFRWIZARDNEW3MULTIPLE.GIF (displayed in the Step 3: Standard Filter Options topic under the Creating a Quick Report topic)

  • The filter step of the Cross-Tabulation Wizard: XTABWIZARD4MULTIPLE.GIF (displayed in the Step 4: Standard Filter Options topic under the Creating a Cross-Tab Report topic)

  • The filter step of the Label Wizard: LABELWIZARDNEW3MULTIPLE.GIF (displayed in the Step 3: Standard Filter Options topic under the Creating a Label Report topic)

  • The filter step of the Chart Wizard: CHARTWIZARD5MULTIPLE.GIF (displayed in the Step 5: Standard Filter Options topic under the Creating a Chart Report topic).
    

• If you change the Description for Data Groups setting, create the following screen shots:
  • Step 1 of the Quick Report Wizard: SFRWIZARDNEW1DG.GIF (displayed in the Creating a Quick Report topic)

  • Step 1 of the Cross-Tabulation Wizard: XTABWIZARD1DG.GIF (displayed in the Creating a Cross-Tab Report topic)

  • Step 1 of the Label Wizard: LABELWIZARDNEW1DG.GIF (displayed in the Creating a Label Report topic)

  • Step 1 of the Chart Wizard: CHARTWIZARD1DG.GIF (displayed in the Creating a Chart Report topic)

  • The Groups page of the Maintain Users and Groups dialog: USERGROUPSDG.GIF (displayed in the How To, Maintaining Users and Groups topic).
    

• If you set the Need Target Application Directory setting to True, create a screen shot of the Locations page of the Tools, Options dialog (either OPTIONS5TARGETAPP.GIF if the Support online updates configuration setting is turned on or OPTIONS5NOUPDATETARGETAPP.GIF if that setting is turned off) since it displays the name of the target application.

• If you provide some link action scripts, create a screen shot called SFFIELDPROP5.GIF of the Link page of the Field Properties dialog in the Quick Report Wizard because it will display an Action drop-down list. You should also add some text to the Field Properties (Quick Report) topic (under Step 2: Data Selection (Quick Report), which is under Creating a Quick Report, which is in the Using Stonefield Query section) that describes what link actions you provide. Do the same thing for the Cross-Tabulation Report Wizard, with an image named XTABWIZARDPROPERTIES4.GIF.

• You must not remove the Copyright topic under the Stonefield Query heading. Although you may change other text in this topic, you must not remove Stonefield's copyright from this topic. In other words, the following text must remain in this topic:

  © 1996-2008 Stonefield Software Inc. All rights reserved.

  You may add additional copyright marks of your own.
  

Here's a summary list of the screen shots that should be customized and under what conditions:

Dialog/How to Display	Image Name	Help Topic	Only Needed If
Welcome Temporarily rename your license file (SFQuery.LIC in the Data subdirectory of the Stonefield Query program directory) and run Stonefield Query	WELCOME.GIF	Your application name (the topmost section), Running your application name	Always (Shows application name and logo)
Login Run Stonefield Query	LOGIN.GIF if the Allow Multiple Data Sources setting is set to True LOGIN2.GIF if that setting is False	Your application name (the topmost section), Running your application name	Always (Shows application name and data source description of you change the Description for Data Sources setting)
About Select About from the Help menu	ABOUT.GIF You may wish to remove the version number from the screen shot so you don't have to recreate it for every release.	Menu Functions, Help Menu	Always (Shows application name and logo and any custom settings if you create an About.Settings script)
Registration Temporarily rename your license file, run Stonefield Query, and when prompted to activate it, choose Yes	REGISTRATION.GIF You may wish to remove the version number from the screen shot so you don't have to recreate it for every release.	How To, Activating your application name	Always (Shows application name and logo)
Setup Run Stonefield Query with "ACTION=SETUP" added to the command line or add an Other section to SFQuery.INI and create an Action entry under that section with a value of Setup. For example: [Other] Action=Setup	SETUP.GIF if the Need Target Application Directory setting is False SETUPTARGETAPP.GIF if that setting is True You may wish to remove the version number from the screen shot so you don't have to recreate it for every release.	How To, Setting up your application name	Always (Shows application name and logo and the name of the target application if the Need Target Application Directory setting is True)
Options Select Options from the Tools menu	OPTIONS1.GIF if the Support Multi-Languages setting is True OPTIONS1NOLANG.GIF if that setting is False	How To, Configuring your application name	The Support Online Updates or Support Maintenance Reminder settings are False or you create an Options.Settings script (in the latter case, describe any additional options you defined in the script in the topic)
Manage Databases Select Manage Databases from the Tools menu	DBMANAGER.GIF	How To, Managing data source description	You change the Description for Data Sources setting and the User Can Manage Data Sources setting is True
Open Database Select Open data source description from the File menu	OPENDATASOURCE.GIF	How To, Selecting the data source description	You change the Description for Data Sources setting
Reports Explorer Options page Select that page in the Reports Explorer	SFRWIZARD4.GIF	Using <>your application name<>, Report Options	You change the Description for Data Sources setting
Quick Report Wizard Step 5 Create a new quick report and select that step in the Quick Report Wizard	SFRWIZARDNEW5.GIF	Creating a Quick Report, Step 5: Formatting Options (Quick Report)	You change the Description for Data Sources setting
Cross-Tab Wizard Step 5 Create a new cross-tab report and select that step in the Cross-Tab Wizard	XTABWIZARD5.GIF	Creating a Cross-Tab Report, Step 5: Formatting Options (Cross-Tab Report)	You change the Description for Data Sources setting
Reports Explorer Filter page Select that page in the Reports Explorer	SFRWIZARD2MULTIPLE.GIF	Using your application name, Selecting Which Records to Include	You change the Description for Data Sources setting and the Allow Queries on Multiple Data Sources setting is True (this image shows the word "Databases")
Select Databases Click the data source description button on the Filter page in the Reports Explorer	SELECTDATABASES.GIF	Using your application name, Selecting Which Records to Include	You change the Description for Data Sources setting and the Allow Queries on Multiple Data Sources setting is True (this image shows the word "Databases")
Quick Report Wizard Step 3 Create a new quick report and select Step 3	SFRWIZARDNEW3MULTIPLE.GIF	Creating a Quick Report, Step 3: Standard Filter Options	You change the Description for Data Sources setting and the Allow Queries on Multiple Data Sources setting is True (this image shows the word "Databases")
Cross-Tab Wizard Step 4 Create a new cross-tab report and select Step 4	XTABWIZARD4MULTIPLE.GIF	Creating a Cross-Tab Report, Step 4: Standard Filter Options	You change the Description for Data Sources setting and the Allow Queries on Multiple Data Sources setting is True (this image shows the word "Databases")
Label Wizard Step 3 Create a new label report and select Step 3	LABELWIZARDNEW3MULTIPLE.GIF	Creating a Label Report, Step 3: Standard Filter Options	You change the Description for Data Sources setting and the Allow Queries on Multiple Data Sources setting is True (this image shows the word "Databases")
Chart Wizard Step 5 Create a new chart report and select Step 5	CHARTWIZARD5MULTIPLE.GIF	Creating a Chart Report, Step 5: Standard Filter Options	You change the Description for Data Sources setting and the Allow Queries on Multiple Data Sources setting is True (this image shows the word "Databases")
Quick Report Wizard Step 1 Create a new quick report	SFRWIZARDNEW1DG.GIF	Creating a Quick Report	You change the Description for Data Groups setting
Cross-Tab Wizard Step 1 Create a new cross-tab report	XTABWIZARD1DG.GIF	Creating a Cross-Tab Report	You change the Description for Data Groups setting
Label Wizard Step 1 Create a new label report	LABELWIZARDNEW1DG.GIF	Creating a Label Report	You change the Description for Data Groups setting
Chart Wizard Step 1 Create a new chart report	CHARTWIZARD1DG.GIF	Creating a Chart Report	You change the Description for Data Groups setting
Maintain Users and Groups, Groups page Select Maintain Users and Groups from the Tools menu and select the Groups page	USERGROUPSDG.GIF	Creating a Chart Report	You change the Description for Data Groups setting
Options, Locations page Select Options from the Tools menu and select the Locations page	OPTIONS5TARGETAPP.GIF if the Support Online Updates setting is True OPTIONS5NOUPDATETARGETAPP.GIF if that setting is False	How To, Configuring your application name	The Need Target Application Directory setting is True (it displays the name of the target application)
Field Properties, Link page Edit a quick report, double-click a field in the Selected list in Step 2, and choose the Link page	SFFIELDPROP5.GIF	Creating a Quick Report, Step 2: Data Selection (Quick Report), Field Properties (Quick Report)	You provide some link action scripts (also add some text to the topic describing the link action)
Field Properties, Link page Edit a cross-tab report, double-click a field in the Selected list in Step 2, and choose the Link page	XTABWIZARDPROPERTIES4.GIF	Creating a Cross-Tab Report, Step 3: Cross-Tabulation Options (Cross-Tab Report), Field Properties (Cross-Tab Report)	You provide some link action scripts (also add some text to the topic describing the link action)

How you customize the help project depends on which type of help project you want to work with. The easiest one is a West Wind HTML Help Builder project. Open SFQuery.HBP, select the appropriate topic from the TreeView in the left pane, and edit the text as necessary in the edit region in the right pane.

If you want to edit the HTML Help Workshop project, open SFQuery.HHP, choose the Contents page, and double-click the appropriate topic in the list. The text for the topic is displayed with HTML tags, so editing it is much more cumbersome than using West Wind HTML Help Builder. You can use a different HTML editor if you wish, but note that the names of the HTML files are system-generated names like _0QX0T1ZEU.htm. To find the file to edit for a topic you want to change, select the topic in the Contents page of the HTML Help Workshop, click the Edit Selection button in the toolbar, and note the name of the file shown in the General page of the dialog that appears.

Building the Help File

Building the help file is simple. In HTML Help Workshop, click the Compile HTML File button in the toolbar. In West Wind HTML Help Builder, click the Build Help button in the toolbar. In either case, follow the prompts in the dialogs that appear. After the SFQuery.CHM file has been created, move it to the Stonefield Query project directory.

Stonefield Query generates the project files for your custom help file in a particular directory. If you move the files to a different directory and you want to use HTML Help Workshop to generate the CHM file, you must edit the #INCLUDE statement in the [MAP] section of the SFQuery.HHP file to specify the correct path for the SFQuery_Help.H file.

Placing the help source files in a very deeply nested directory structure may cause the help file to compile incorrectly. If this happens, try using a different, less deep directory structure.