Quite some applications on Windows platforms use HTML Help (.chm files). The HTML Help system can jump to a specific topic in the help file to support contextual help. The mechanism behind this is based on resource ids. Resource ids are used by programming languages such as C/C++ to identify fields on the windows.
The resource ids are numeric strings and you can use these as pointer for the HelpServer objects. However, numeric strings are hard to recognize. Therefore the Workbench allows you to assign both a pointer and the resource id to an object. The pointer can then be used as an eye catcher to recognize the object while the resource ID can be used by your windows applications to compile the URL.
The next example demonstrate how you can assign resources IDs to individual content objects. As with pointers you can define a path of resources IDs.
Showing more properties in the table editor
Select the 'Book: Birds' and on the table editor on the right popup the menu and select 'Properties >Show'. This will show more columns in the table. Amongst these is the 'Resource ID' column.
Assigning a resource ID to a chapter
If you double under the 'Resource ID' column of the 'The eagle chapter' item you can edit the cell and enter the pointer. Click outside the cell or press enter to end the editing.
Assigning a resource ID to a topic
Select the 'Chapter: The eagle' in the tree and use the same working principle to enter the resource ID for the 'About the eagle' topic. Resource IDs are not controlled by any Workbench mechanism. This means a resource ID does need to be unique within a project or a structure. Just make sure you use unique resource IDs per folder.
Copying a URL containing a resource id
If you now popup the menu of the 'Topic: About the eagle' you will see the resource ID path in the 'Copy URL' submenu item. As with pointers multiple levels of resource IDs are separated by dots in the URL.
|
|
|
Next, we demonstrate the usage of resource IDs in an HTML Help file in an example you can download in
After downloading and extracting the .ZIP file you can open the file 'excel_help.xls' file (allow macros to run) This is the Excel sample worksheet and it looks like this.
The Excel sample worksheet
The worksheet is equipped with two help buttons to jump to a specific topic in the help file.
Building the help project
You build this help system according to the following steps.
| • | You first create a new project. |
| • | Next, you can add a book and assign an alias. |
| • | Add a chapter. |
| • | Add topics with contents to the chapters, one for each help button. Assign a pointer AND assign the resource ID to each topic. Your application does not need to use the pointer, but the HelpServer export function requires the presence of a pointer in association with a resource ID. |
| • | Preview and verify the result. |
| • | Publish when ready. |
| • | Export the book to an HTML Help file. In this example the output file is 'samplehelp.chm'. This file should be shipped with the application. |
Implementing the help calls in the application
You can add the procedure behind the help buttons by opening the worksheet's VBA editor. The procedures specify two parameters to invoke the help.
| • | The (relative) file path, in this example '\samplehelp.chm'. |
| • | The resource id. |
The Excel sample worksheet in the VBA editor
If people click on for example the first button in the worksheet the help file opens and the associated help topic is preselected.
Contextual help in a HTML Help file
