Appendix A: Assigning a custom help file

4D allows you to associate a custom on-line help file with each database. 

The on-line help system provided with 4D is compatible with each 4D work environment (stand-alone database or client-server, interpreted or compiled, run using 4D Desktop Interpreted, or integrated into a 4D Desktop Volume, etc.).

4D supports two help files formats: CHM and HTML. These formats correspond to the industry standards.

Moreover, you can associate a specific section of this help file with each of the database’s forms, which allows you to provide contextual on-line help.

You must use one of the following formats:

• Compiled HTML format (“.CHM” extension): This is the standard on-line help format for Windows. CHM files are opened by the Microsoft® HTML Help Executable (HH.EXE) application, integrated into the operating system. These files are compatible with Windows XP and Windows Vista.
  Microsoft® provides the HTML Help Workshop application free of charge, which is needed for preparing and compiling the .CHM files.
• HTML format (“.HTM” extension): This is the HTML format. With this format you can create an identical on-line help on all platforms. The on-line help is then displayed in a Web browser.

Once the Help file generated, you need to associate it with a database so that it is opened when users call the on-line help (see Calling the on-line help from a database below) To assign a help file to a database, make sure:

• The name of the help file is identical to the name of the database’s structure file. It must also have the “.CHM” or “.HTM” extension, depending on its format and platform. 
• The help file is placed next to the structure file or in the Resources folder located at the same level as the database structure file.

4D Server: If you want the help file to be accessible to all the client workstations, place it in the Resources folder. It will then be transferred to the client workstations automatically. 

Plug-ins can have a help file, which must be placed in the PlugIns folder both in a single-user application or in a client/server. The help file of the plug-in must have the same name as the plug-in with the extension .CHM or .HTM. For plug-ins provided as a folder, the help file must be placed:
- next to the plug-in executable, so either in /Contents/MacOS or /Contents/Windows
- or in the /Contents/Resources folder of the plug-in.

Components can also include a custom help file, placed next to the structure file of the component. For more information, refer to the On-line help for components.

Creating contextual on-line help is done by associating a section number with each of your forms. When you call the on-line help from a form, the corresponding help page is displayed. When the user calls the on-line help, the help topic that has the same ID as the form is displayed.

Contextual on-line help is available:

• Under Windows, if the on-line help is in CHM format.
• Under Windows and Mac OS, if the on-line help is in HTML format.

Assigning an ID number to a form is done in the form properties; for more information, refer to the Help section.

Once you have assigned the ID number to the form, you need to assign the same ID number to the help file. This operation varies according to the format you are using:

• For CHM files, refer to the documentation of the HTML Help Workshop application.
• For HTML files, you must declare each section using an anchor and assign a number.
  A section is declared by using a marker of the type:
  

  <A NAME="Section">

  
  For example:
  

   <A NAME="21">

  
  The URL of the section has the following form:
  

  <A HREF="#Section">...</A>

  
  For example:
  

  <A HREF="#21">...</A>

If the section number passed in the form is 0 or if it does not exist in the file, 4D displays the first page of the help file.

In 4D, you can call a database’s custom on-line help in two ways:

• By choosing DatabaseName Help in the Help menu. In this case, the first page of the help file is displayed.
• By pressing the F1 key (Mac OS and Windows) or the Help key (Mac OS only) when a form is displayed in Application mode. In this case, if a help topic number has been associated with the form, the corresponding page is displayed (contextual help); otherwise the first page of the help file is displayed.

Note: Under Mac OS, the functioning of the F1 key can be customized. In Application mode, when the user presses the F1 key:

• If a “DatabaseName.HTM” file exists next to the database structure file, the standard mechanism for managing 4D on-line help files is implemented. The help file is opened in a default browser window.
• Otherwise, 4D does nothing and the developer must process the event as desired. This means it is possible to set up completely customized help systems or to assign another function to the F1 key.