JavaHelp: Creating online documentation the easy way

JavaHelp, an optional package of the Java platform, is a great tool for implementing online documentation for your applications. It's both an engine that displays documentation and an API that drives that engine. JavaHelp's appearance is highly customizable. In its standard form, it consists of a content pane capable of displaying any HTML 3.2 page and a navigation pane for browsing the online documentation, as shown in Figure A. In this article, I'll explain how to implement JavaHelp in your applications.

Figure A

Javahelp appearance

Nuts and bolts
Writing online documentation to be used with JavaHelp is extremely straightforward. To demonstrate the process, I will develop documentation for a preferences dialog box for a hypothetical application, shown in Figure B.

Figure B

Example preferences dialog box

The first step is to organize the documentation into topics. Each topic is a separate HTML 3.2 page contained in its own file. Topics are the units of JavaHelp online documentation and are displayed one at a time in the content pane.
The organization of the documentation into topics is entirely up to you. In this example, I decided to create a topic for the dialog box as a whole and one topic for each field and button. Table A shows these topics.

Table A

Each setting and button corresponds to a topic stored in a separate file. There is also one topic for the dialog box itself. Control Topic file Tab stop width help/tab_stop.html Use wordwrap help/wordwrap.html Autosave minutes help/autosave.html Write backup file help/write_backup.html Backup directory help/backup_folder.html Backup suffix help/backup_suffix.html Ok help/ok.html Cancel help/cancel.html Help help/help.html Dialog box help/preferences.html

Topics for preferences dialog box
The next step is to create a map file that associates IDs with URLs (paths to HTML topic files). The IDs are used as a portable way to refer to topic files without the need to hard-code the path to the file.
As you can see in Listing A, the map file format is simple. It's just an XML file with one tag (mapID) for each ID. The target attribute defines the ID and the url attribute defines the topic file's path. As a rule of thumb, there should be one ID for each topic file.

Finally, you need to create a table of contents for your documentation. The table of contents is an XML file that describes the organization of your documentation, used by JavaHelp to create a tree view of your documentation's layout.
As Listing B shows, the table of contents file format is straightforward. The tocitem tag defines an entry, which can be nested to show the hierarchy between them. The text attribute defines the text to be displayed in the tree view and the target attribute defines the ID of the topic to be displayed when the entry is selected.

If the target attribute is omitted, the entry is just a placeholder and does not display any topic when selected. This is especially useful for entries that do not correspond to any topic but contain other entries.

The set of all files that make up the online documentation (topic files, map file, table of contents file, etc.) is called a helpset. To tie everything together, you must create a helpset file so that JavaHelp can find all the pieces of your documentation. Listing C shows a sample helpset file.

The helpset file is an XML file that contains several tags that describe your helpset. The title tag defines a title to be displayed by JavaHelp. The maps tag defines the URL that points to your map file (tag mapref, attribute location), as well as the ID of the topic to display when the documentation is first displayed and no topic is selected (tag homeID).

The tag view defines how you want to browse the documentation. You can use several different views, called navigators, to do that. The tag name defines a name for the navigator (for use in the application), and the tag label defines text to be displayed by JavaHelp for the navigator. The tag type is the fully qualified name of the navigator class (javax.help.TOCView for the table of contents navigator) and the tag data specifies the data to be used by the navigator (the URL to the table of contents file, in the case of the table of contents navigator).

Figure C shows how the several files relate to each other.

Figure C

Help file relation

Adding JavaHelp to your application
The process of integrating the online documentation with your application is incredibly simple. JavaHelp already provides the bulk of the code, so the amount of effort required is minimal.
The first step is to construct a javax.help.HelpSet object to encapsulate your helpset. To do that, use the HelpSet(ClassLoader,URL) constructor, passing null as the first parameter (to use the default class loader) and the URL to your helpset file as the second.
You can use the static method findHelpSet(ClassLoader,String) of the class HelpSet to get a URL to your helpset given its pathname. The advantage is that the method applies localization rules and searches through the application classpath, jar files, etc.
Next, you need to create a HelpBroker object. The HelpBroker drives the several classes that compose the JavaHelp system to display the online documentation when requested.
Finally, you must set up your application to display the documentation when requested by the user. The most common way to do that is to set up a button or a menu item that, when pressed (in the case of the button) or selected (in the case of the menu item), displays a particular topic.
For each button or menu item, just call the method HelpBroker.enableHelpOnButton. This method accepts three parameters. The first is the button or menu item object that will activate the help. The second is the ID of the topic to be displayed when the button/menu item is pressed/selected. And the third is the HelpSet object. The HelpBroker class takes care of all the hard work for you.

Setting context-sensitive help
Another way to add online documentation to your application is to use context-sensitive help. In this case, the user requests help about a specific component by pressing a key, or clicking on it.
JavaHelp provides all the support needed to create context-sensitive. First, you associate an ID with each component for which you want to provide context-sensitive help. This determines the topic to display when context-sensitive help is requested for that component.

This is accomplished by the method HelpBroker.enableHelp. Much like the enableHelpOnButton method, it receives as parameters the component or menu item, the ID of the topic corresponding to the component, and the helpset.
If you want to set up a help key that displays the topic of the component that has the focus, call the method HelpBroker.enableHelpKey. As parameters, pass the root pane of the dialog box/application, the ID of the topic to display if no component has the focus, and the helpset. Notice that the help key is platform-dependent; usually it is the [F1] key.

If you want to display the topic when the user clicks on the component, create an instance of the class CSH.DisplayHelpAfterTracking (pass the HelpBroker object as the parameter to its constructor), and add it as an event listener to a button or a menu item (by using the addActionListener method of the component).
When the user presses the button or selects the menu item, JavaHelp changes the cursor to a custom help cursor to indicate that context-sensitive help is active. Then, when the user clicks on a component, JavaHelp displays its associated topic, if any, and changes the cursor back to normal, deactivating the context-sensitive help.
Listing D shows the complete code for the preferences dialog box of the Figure B. It uses a help button to display help about the dialog box and the help key to display context-sensitive help about each component.

Conclusion
Online documentation is an essential component of any application today. Using JavaHelp, you can add a professional-looking help system to your application with no effort.
JavaHelp does all the hard work for you so that you can concentrate on the application itself. Its clear separation of help contents and the code that drives it makes it easy to develop the documentation in parallel with the application.