Implementing context help

<< Click to Display Table of Contents >>

Navigation:  Reference > Modules, Conditional Output & Variables > Context-Sensitive Help & Popups >

Implementing context help

Generally, implementing context-sensitive help called from the application is the job of the programmers. They must write the calls that access specific topics in your help, and the syntax of these calls depends both on the help format and the programming language they are using.

HTML Help (CHM) supports both context-sensitive calls to specific help topics and field-level popups displayed within your application. WebHelp only supports calls to specific topics (see Context calls to WebHelp for details).

Free tutorials and context-sensitive help tools for programmers:

How the context-sensitive help calls to your help are made varies depending on the programming language you are using. A collection of free tutorials for programmers is available on the weblink tutorials page at the EC Software website. These tutorials cover implementing context-sensitive help and interfacing with the help files generated by Help+Manual in most common programming languages.

You may also be interested in EC Software Help Suite (EHS), a free package of tools for interfacing with help for Borland Delphi and Borland C++ programmers. EHS is particularly useful for implementing all kinds of context-sensitive help and ships with the full source code. It is available on the weblink Delphi resources page at the EC Software website, where you can also download a comprehensive free tutorial on integrating help in Delphi applications.

Resources for .NET programmers:

You can find an excellent guide to interfacing with help files in .NET programming languages on Rob Chandler's Helpware site:

weblink Working with HH 1.x CHM Files in .NET Applications

Rob's site also offers a wealth of information on working with help files in other applications and languages, including plenty of information on Visual Studio Help for programmers.

Your job as the help author

There are a number of things that you need to do as the help author to help make context-sensitive help work:

Topic IDs and context numbers for the programmers

Your programmers need a way to access the topics in the help. This applies equally to topics in the main help that bring up the entire help and popup topics that are accessed individually.

Programs access the topics in HTML Help with the topic IDs and/or the help context numbers, both of which are stored in the Topic Options tab of each topic. When you are planning your help project you need to talk to the programmers and find out which they want to use, and if they need to use special formats. (Some programming languages require special formats for topic IDs or specific number ranges for help context numbers.)

Topic ID prefixes:

If your programmers require special topic ID prefixes you can apply these to the IDs of new topics automatically. Just go to Configuration > Common Properties > Miscellaneous and insert the prefix you want to use in the Topic ID Prefix field.

If you have the Professional or Server version of Help+Manual you can also use an external editor to add ID prefixes to existing topics globally throughout your entire project (advanced users only).

Auto-generating help context numbers:

Help+Manual can generate and apply help context numbers to new topics automatically. Go to Project Explorer > Configuration > Common Properties > Miscellaneous to set up this feature.

Applying help context numbers to existing topics:

You can apply help context numbers to existing topics and import "help context map files" with lists of context numbers provided by your programmers. See The Help Context Tool for details.

Changing topic IDs:

Don't despair if you discover that you've been using the wrong topic ID format! You can edit your topic IDs at any time, Help+Manual updates all internal links automatically.  See Topic IDs and context numbers for details.

Planning your structure for context-sensitive help

Before you start writing you also need to plan the kind of context-sensitive help you are going to use. For example, if the dialogs in the application are going to have a Help button you need to have appropriate topics for those buttons to link to from all the relevant dialogs. This may sound trivial but it's quite easy to forget!

Planning the use of field-level popup topics

Field-level popup topics are exactly the same as popup topics used within your help. The only difference is that they are accessed directly by the application instead of with a link from a help topic.

When they are used in this way they are displayed in their own little window that is closed after the user has read the contents, without displaying the entire help. They are most commonly used for What's This? help, but they can also be accessed by buttons etc.

If you are going to use field-level popup topics these require some careful planning. Among other things, you need a full list of all the controls and other program elements for which you need field-level popups, along with all the topic IDs and/or help context numbers that are going to be used to access them.

Auto-generating your field-level popup topics

Since there are generally a lot of these topics creating them manually can be time-consuming, and you will probably start to wish that you could generate them automatically. Well, you can!

All you need to do is get a "help context map file" from the programmer with a list of the topic IDs and help context numbers (if applicable). Once you have this you can automatically generate all the popup topics in Help+Manual together with the matching IDs and help context numbers. See Auto-generating field-level popups for details.

See also:

Using Context-Sensitive Help

The Help Context Tool

Creating popup topics

Topic IDs and context numbers

Auto-generating field-level popups