Authoring - Working with resource IDs

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.

Resource IDs have the same functionality as pointers. Resources IDs are just a handy addition to support the access to the HelpServer objects over the Internet in C/C++ programs.

 

If you export the project, the resource IDs will be included in the exported content.

 

You can also import header files that contain your C/C++ program’s resource IDs.

 
Next is an example of using resource IDs for HTML Help

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

Authoring

 About HelpServer
 Starting up and logging on
 The basic working principles
 Using the content in help and documentation systems
 Working with aliases
 Working with pointers
 Building a context sensitive, web based help system
 Including the HelpServer content in your website
 Working with resource IDs
 Formatting the content
 Searching and replacing text
 Reusing content with shares
 Navigating with hyperlinks
 Navigating with pointerpaths
 Using bookmarks and jumps
 Duplicating content with clones
 Using tables
 Including media files
 Navigating to web pages
 Using embedded chunks
 Including html code
 Navigating with menus
 Using snippets
 Spelling checking
 Using the view mode
 Creating an index
 Creating a FAQ
 Creating a glossary
 Team authoring
 Working with projects
 Setting up structured authoring
 Generating file based output
 Creating printed output
 Importing files and folders
 Loading files in the project gallery
 Converting legacy content
 Including legacy content in real time
 Transferring objects between installations
 Smartcontent
 Notification
 Feedback
 Translating
 Customizing the look and feel
 User accounts
 Security
 Working with templates
 Working with metadata
 Versioning
 Auditing
 Workflow management
 Annotations
 Using event exits
 Appendix A: The URL parameters
 Appendix B: The object indicators
 Appendix C: Play Javascript