Understand the benefits of the JavaHelp framework

JavaHelp is an application help technology that can run on any platform and browser that supports Java. Peter Mikhalenko details the features and benefits of this easy-to-use framework.

Sun Microsystem's JavaHelp system is an application help technology that can run on any platform and browser that supports Java—as long as it is a pure Java product. It's ideal for use in a heterogeneous environment, such as the Web and corporate intranet, and through applets and Java apps. In this article, I review the main benefits of JavaHelp, and demonstrate how simple it is to use.


JavaHelp is implemented using Java Foundation Classes (JFC) software components, which provide flexibility and ease in developing custom user interfaces and functionality. You can easily embed help information for your application into an application itself, or into a separate window. JFC also provides an ability to extend help functionality with customized navigational controls.

JavaHelp makes it easy to dynamically update help data or store it in a convenient place, either on the client side or the server side. The content pane uses HTML 3.2 as its format for displaying topics, making it simple to design the content. The standard navigation provides a table of contents (TOC), index, and a full-text search. (Both the TOC and the index follow the W3C standards.)

The JavaHelp Data Sheet provides this information: The TOC supports a collapsible and expandable display of topics, an unlimited number of hierarchical levels, and a merging of multiple TOCs. The TOC display is synchronized with the content viewer, which means that the topic being displayed is highlighted in the TOC. The index supports the merging of multiple indexes. Full-text search is designed to be flexible and configurable. The search engine also can reside on either the client or server side.

Get developer tips in your inbox
Delivered each Thursday, our free Java newsletter provides insight and hands-on tips you need to unlock the full potential of this programming language.
Automatically sign up today!

The help content and search engine are compressed into a single file using the standard JAR format. You can also store all files in an expanded format in a directory, although compressing the files into a single file is recommended for better storage and access flexibility. You can view and navigate the content in a custom-written navigator, search engine, standard JavaHelp viewers, or in any HTML viewers, including standard Web browsers.

The JavaHelp API provides a mechanism for context sensitive help and for ID mapping. You can also merge multiple components' help information with the JavaHelp API, so a user sees the single monolithic document. The merging mechanism applies to the TOC, indices, and search databases.


There are two major releases of JavaHelp: 1.1.3 and 2.0. The earliest version of Java that supports JavaHelp 2.0 is J2SE 1.2.2, so you don't have to worry about JavaHelp supportability in your code. The JavaHelp system consists of a fully featured, extensible specification and API, and a reference implementation.

The standard JavaHelp system main window: has three panes, is not destroyed when you exit the window, and is configurable. By default, a main window has the following three panes: toolbar, navigation pane, and content pane. See Figure 1.

Users invoke online help from within applications in a number of ways, e.g., when a user chooses an item from a Help menu or clicks on a Help button in an application GUI. The JavaHelp system provides a simple interface by which an application requests that a topic ID be displayed. The JavaHelp system then associates the topic ID with the appropriate URL and displays it. IDs are mapped to URLs in a JavaHelp system metadata file called the map file. For example, when coding a file chooser dialog box, a developer requests that the topic ID fc_help be displayed when the Help button at the bottom of the dialog box is clicked. In the map file, the ID fc_help is defined to be a file named FileChooser.html using the following XML syntax:

<mapID target="fc_help" url="html/help/FileChooser.html" />

Separating the specification of file names (or URLs) from the program code provides content authors the freedom to control the information that is associated with the topic ID.

A tooltip is a brief message presented to the user when the cursor remains over a button for an interval longer than a given threshold. You can also include a tooltip information in the JavaHelp system data.

The JavaHelp system provides the ability to invoke online help that describes graphical components in an application GUI. The user makes gestures that activate context-sensitive help and then specifies the component in question. The ID associated with the component is displayed. You can display help topics from a TOC, an index navigator, or from the content pane of the main window.

Lightweight components

Lightweight components can add functionality to help topics. These components are similar to Java applets, but they load and execute more quickly. A help author can use a lightweight component that is already implemented in the JavaHelp system; this component implements pop-up windows and secondary windows. To use this lightweight component in an HTML topic file, you use the HTML <object> tag, as the example in Listing A demonstrates.

In the example: the pop-up object contains the file ../topicB/glossary_def.html, the object that the user clicks (viewerActivator) is a link, the type of window is a pop-up, the size of the window is 300x400, and the text that the user sees in the link is "Click here."

A Java developer can also create new lightweight components. For example, such a component might add functionality like animation and multimedia to help topics.

Lightweight components that require information about the View abstraction must implement javax.javahelp.impl.ViewAwareComponent. These components implement the method setViewData(). The component can determine information from the View abstraction about the environment in which it is executing. (Note: You should use the JavaHelp API for accessing a View abstraction.) In Listing B, the code snippet below the Document object is derived from the View abstraction.

For more information about creating Java lightweight components, please read the relevant documentation.

JavaHelp authoring tools

There are plenty of commercially available authoring tools to help you write and maintain a perfect help system for your application. Three of the most well-known are Software 7 Gmbh's Helen 1.5, Solutionsoft's HelpBreeze, and Pivotonic's JawaHelpAuthor. All of these third-party products support Java 2 and Java 1.1 standards. For more information on authoring tools, please look at Sun's Help Authoring Tools page.

Try it out

If JavaHelp sounds like a system that you think your users and fellow developers would like, then download it today from Sun Microsystems. The site provides all the necessary information you'll need for the installation process.

Peter V. Mikhalenko is a Sun certified professional who works for Deutsche Bank as a business consultant.

Editor's Picks