Oracle Help for Java: Full-Featured Help for Java Applications

Oracle Help for Java (OHJ) is a set of Java components and an API for developing and displaying HTML-based help content in a Java environment. The Oracle Help for Java Developer's Kit (OHJDK) includes the OHJ technology plus tools and documentation for developing context-sensitive help for Java applets and applications. The OHJDK is available for free from this Web site. You may redistribute OHJ as the help system for your application at no cost.

Why Java-based Help?

OHJ is designed primarily for displaying help for Java applications, although it can also be implemented as a stand-alone document viewer for use in a Java environment.

One of they key reasons for developing applications in Java is that they must run on multiple platforms. If you want a single implementation of your help system for a cross-platform application, you need a cross-platform help system. That is why you can't use a help system such as Microsoft's HTML Help, which is built into Windows and is not available on other operating systems. Oracle Help for Java runs on any system with a Java Virtual Machine (JVM) (we recommend JDK 1.1.7 or higher). All Java applications run in a JVM, so you can use OHJ with your Java application, without worrying about special support from any native platform in which it runs.

Why not use a help system that runs in a Web browser? It is possible to implement a help system that is displayed directly in a Web browser; in fact several authoring tool vendors provide such systems. However, with this approach, you must be certain that your users have a supported browser installed, which may not be appropriate for the environments where your applications are installed. OHJ does not require the presence of a Web browser. It uses a built-in Java component for displaying HTML content. Also, OHJ has an API that makes it easy to integrate a help system into an application, including context-sensitive help. OHJ also has many additional features that are not available in Web browser-based help systems. Many of these features are discussed later in this document.

Why Oracle?

Development on OHJ began at Oracle in 1996. Oracle had begun a company-wide initiative to convert existing technology to Java and to develop new technology in Java. These products were not small Java applets running in Web browsers; they were complex applications that had to run in a JVM in a variety of environments, including Windows, UNIX, and network computers (that is, Web appliances). At that time, no complete, full-featured Java help system was available, so we had to build it ourselves.

OHJ is proven technology that is now used by over 40 Oracle products and by a diverse array of other organizations, including software companies, financial institutions, communications and networking providers, and government agencies. We continue to actively develop and improve OHJ, based on input from within and outside Oracle and on our review and analysis of trends in the field.

OHJ is developed and maintained at Oracle by the same team that provides core technology for building graphical user interfaces (GUIs) for Oracle's Java and Web applications. That means it is based on the same technology that is used for building dozens of products within Oracle and many products outside Oracle. This team is also closely affiliated with the Oracle Interface Design and Usability group, which provides considerable input into our designs. These affiliations ensure that OHJ benefits from all the work that is done to make Oracle's GUIs localizable, accessible, and usable.

What You Get

When you download OHJ from our Web site, you get the following:

  • Java components: OHJ includes a set of default Java user interface components that together comprise a complete help system, including table of contents, index, full-text search, and topic windows.
  • API: The OHJ API includes features for implementing context-sensitive help, for programmatically controlling how help is displayed (size, position, etc.), and for customizing and extending the help system. For example, you can replace a default component with your own, create custom controls, or embed selected components in an application.
  • Documentation: Documentation includes API reference, a File Formats specification, and a Programmer's Guide.
  • HelpSet Authoring wizard: The OHJ HelpSet Authoring Wizard helps you create OHJ control files without requiring an authoring tool that directly creates OHJ systems.
  • Redistribution License: You are free to use OHJ and to redistribute OHJ free of charge, subject to the conditions of the license.

The User Interface

The OHJ user interface has two main components: a Navigator window, which includes controls for finding topics, and a topic display. With a single click, a user can "dock" or "undock" them so they appear in separate windows (Figure 1) or together as panes in a single window (Figure 2).

Figure 1: Oracle Help for Java Undocked

Picture of undocked OHJ, with Navigator window and topic window.

Figure 2: Oracle Help for Java Docked

Picture of docked OHJ, with Navigator pane and topic pane in single window.

Topic Windows

OHJ topic windows (or topic panes, when docked) display HTML content (see Figure 3).

Figure 3: Topic Windows

Picture of three topic windows with different sizes and background colors.

The default HTML display component included in the OHJDK is a special implementation of the ICE Browser from Wind River Systems (www.windriver.com). You may use and redistribute this component free of charge as long as it is used as part of a help system using OHJ. This HTML display component supports the following:

  • HTML 4.0
  • Cascading Style Sheets (CSS) 1 and most of CSS 2
  • Java applets
  • Limited multimedia (requires Java Media Framework (JMF) 2.0)
  • Single topic and multiple topic printing
  • GIF animation
  • Popups with limited HTML support
  • Associative links, where a single index word or phrase can be associated with multiple topics. When the user selects one of these links, a list of all topics associated with the link is presented, and the user can choose a topic from the list.
  • Author-defined window types, where authors can specify colors (background, text, and links), window size and position, window title, and toolbar buttons.
  • Topic ID linking (that is, hyperlink targets are specified by ID rather than URL)
  • Synchronization with items in the table of contents
  • (JavaScript coming soon)

You do not have to use the default HTML display. You can replace it with a different HTML display component. Or, if your application and the help system are running as an applet in a Web browser, you can use a browser window as the topic window. Consequently, the display capabilities for your implementation of OHJ rely on the HTML display you chose to embed in the system.

Navigator Window

The Navigator window is a tabbed control for navigating and finding topics in the help system. By default, the Navigator window contains tabs for a table of contents, a keyword index, and a full-text search. Authors can control several characteristics of the Navigator window simply by setting parameters for the help system. For example, you can change the labels on the tabs and add icons. You could also display multiple tables of contents, for example, one for product help and one for a tutorial. For a more complex system, a Java programmer can create custom tabs, and the author can add them to the Navigator window.

Table of Contents

Figure 4 shows the Navigator window with the Contents tab selected. The topics are displayed in a hierarchical tree. The contents and structure of the tree are specified by the author. Multiple file formats are supported for defining the tree (See "File Formats," below, for more information).

When a user double-clicks a topic title in the table of contents, that topic is displayed in the topic window. The user may also open a topic in a new (additional) topic window, by selecting a button on the toolbar or by selecting a command from the right-click menu.

The table of contents has the following features:

Index

Figure 5 shows the Navigator window with the Index tab selected. The index is an alphabetical list of keywords associated with topics. The keywords are defined by the help author, and, like the table of contents, multiple file formats are supported for specifying the list (See "File Formats," below, for more information).

Figure 5: Index Tab in the Navigator Window

Picture of Index tab in the Navigator window.

The process for using the index is described below. The numbers in the list correspond to the numbers called out in Figure 5.

  1. Text entry field. The user types a word or words in this field that he or she hopes to find in the index.
  2. Keyword list. As the user types, the first keyword in the list that matches the typed letters is selected. As more letters are typed, a more accurate selection is made. Alternatively, the user can simply select a keyword from this list.
  3. Topic list.The titles of any topics that are associated with the keyword selected in step 2 are displayed in this list. When the user double-clicks one of these titles, the topic is displayed in the topic window.

The index has the following features:

  • One keyword can be associated with many topics, and many keywords can be associated with a single topic.
  • Two levels of indenting are supported.
  • When merging helpsets, one unified index is created with proper alphabetization for the entire index. (In other words, the entries are merged and resorted; they are not concatenated.)
  • Indexes are properly alphabetized when translated into languages other than that used to create the index.
  • Identical entries are collapsed to show only one.

Full-Text Search

Figure 6 shows the Navigator window with the full-text Search tab selected. When a user types a word or phrase into the text field and selects "Search," the titles of topics whose content contains that word or phrase are listed in the Results list at the bottom of the tab. When the user double-clicks a title, that topic appears in the topic window.

Figure 6: Search Tab in the Navigator Window

Picture of full-text Search tab.

Users can set the following options when performing a full-text search:

  • Respect or ignore the case of letters in the search words (that is, turn case-sensitivity on or off).
  • Only list topics that contain all the search words or at least one of the search words.
  • Search based on a Boolean expression (AND, OR).

Full-text search also has the following features:

  • Results are ranked according to how well they match the search criteria.
  • Previously entered search criteria are saved and can be displayed in a drop-down list.
  • Results list the title of the topic and its source.
  • Users can sort results by rank, topic title, or topic source.

The search database is generated when authoring the help system. The OHJDK (as well as authoring tools that support OHJ) includes a utility for generating this database, which uses an Oracle-defined file format. This search database is always used when you implement it on the client. You can also implement your own search on a server. For example, if you store your topics in an Oracle database, you can use the database's text processing capabilities to perform the search. (Note: You do not have to have an Oracle database to use OHJ.)

Custom "Navigators"

Among other features, the OHJ API allows you to customize the default OHJ user interface. For example, you can program custom tabs (called "navigators") in Java and add them to the Navigator window. For example, you could provide a custom tab for Product Education, as shown in Figure 7.

Figure 7: Custom Navigator Tab in the Navigator Window

Picture of custom tab with buttons for launching "cue cards" and "quick tours." and for navigating to an Education Web site.

Merging Helpsets

A collection of help topics, with their associated control files, is called a "helpset." In OHJ, helpsets can be merged at runtime. That means that multiple authors can create multiple helpsets which will be seamlessly merged after authoring has been completed. Similarly, new components can be added to a user's help system without having to rework the entire system.

Several features support merged helpsets:

  • Tables of contents can be concatenated, so the Contents tab in the Navigator window displays one tree with all the contents from all the merged helpsets. The index shows all the index entries from all helpsets, properly sorted. The full text search searches through all the merged helpsets.
  • Alternatively, authors can specify that selected helpsets are displayed in a drop down list in the toolbar. This can simplify the presentation of a complex help system to the user. See Figure 8.

    Figure 8: Merged Helpsets in a Choice List

    Picture of drop down list with titles of three helpset.

    When this implementation is selected, the table of contents and the index show only items from the helpset selected from the list. The full text search searches only for items in the selected helpset.
  • When an author provides associative links, the list of topics associated with a link includes items from the merged helpsets.

File Formats

Along with the HTML that is used to create topics, OHJ uses several control files to create and manage a help system, for example, files for defining the index and the table of contents. OHJ supports the following formats:

  • Oracle-extended JavaHelp. OHJ supports the XML file formats defined for Sun Microsystems's JavaHelp. Oracle has also extended those formats to provide additional features. We recommend using these file formats, so you can take advantage of all of OHJ's features.
  • Microsoft HTML Help v1.x. If you have already created help to be displayed in MS HTML Help, using these files makes it easy to display your help system in OHJ. (HTML Help control files must be uncompiled for use in OHJ.)

The following table briefly describes the file formats we recommend you use with OHJ. The last column shows which files are defined in the JavaHelp specification, which are JavaHelp formats with OHJ extensions, and which are unique to OHJ.

Type Purpose Source
helpset (.hs) Defines characteristics of the help system, including:
  • Other helpsets to be merged
  • Window specifications
  • Location of map files (for mapping topic IDs to URLs)
  • Location of link files (for defining associative links)
  • Characteristics of the Navigator tabs, including custom tabs
JavaHelp, with OHJ extensions
Table of contents (.xml) Defines content and layout of the table of contents tree that appears in the Navigator window's Contents tab. JavaHelp, with OHJ extensions
Index (.xml) Defines content and layout of the index that appears in the Navigator window's Index tab. JavaHelp, with OHJ extensions
Map (.xml) Associates help topic IDs with the URLs of the HTML content files; also associates topics with window types defined in the HelpSet. JavaHelp
Links (.xml) Used to generate the list of topics associated with an associative link keyword. OHJ
Full-text search (.idx) Binary file of the full-text search database. OHJ

For detailed information about these formats, see the OHJ "File Formats" specification.

Other Features

  • Accessibility features
    • All user-interface features are keyboard accessible, including the default HTML display component (the ICE Browser). Oracle has modified the ICE browser that ships with OHJ to provide this accessibility support.
    • The most recent versions of OHJ and of the ICE Browser have been successfully tested with the JAWS for Windows 3.7 Screen Reader from Freedom Scientific (see http://www.hj.com/main.html).
  • Internationalization features
    • All text strings in the user interface are stored in resource files, for easy translation.
    • The locale and encoding can be set programmatically.
    • The default HTML display component (the ICE browser) supports wrapping for non-space separated languages.
    • Help authors can set the charset of the HTML file, using the IANA character set encoding names (when using the default ICE browser HTML display component).
    • The OHJ user interface has been translated by Oracle into several languages.
  • Release 4.x of OHJ is implemented using Java Foundation Class (JFC) "Swing" components from Sun Microsystems.
  • OHJ has an open, pluggable architecture. That means that you can substitute your own components for default components such as the search facility or the HTML display component. In addition, components such as the Navigator tabs and the HTML display can be embedded into an application's user interface, to provide completely integrated help.
  • All OHJ application class files, control files, and content files can be encapsulated and compressed into JAR (Java ARchive) files. It is not necessary to unJAR the files to run the help system.

Authoring Tool Support

OHJ is now directly supported by the following authoring tools. We will announce support from more soon.




Copyright 2001, Oracle Corporation. Last updated 18 April 2001.