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.
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.
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.
When you download OHJ from our Web site, you get the following:
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
Figure 2: Oracle Help for Java Docked
OHJ topic windows (or topic panes, when docked) display HTML content (see Figure 3).
Figure 3: Topic Windows
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:
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.
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.
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).
Figure 4: Table of Contents Tab in the Navigator Window
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:
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
The process for using the index is described below. The numbers in the list correspond to the numbers called out in Figure 5.
The index has the following features:
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
Users can set the following options when performing a full-text search:
Full-text search also has the following features:
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.)
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
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:
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:
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.
|helpset (.hs)||Defines characteristics of the help system, including:
||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.
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.