Oracle Help File Formats	Contents	Previous	Next

Topic Files

Topic files are HTML files that contain the content for a help topic. The features supported in the HTML files depend on the browser (or HTML display component) used to display them.

The HTML display component that ships with the current releases of OHJ is an Oracle-modified version of the ICEbrowser from ICEsoft Technologies, Inc. Versions 5.01 and later of the ICEbrowser are compliant with the HTML 4.0 standard and can display tables and frames as well as run Java applets. However, the standard ICEbrowser does not support several features important for a full-featured help system. Therefore, under license from ICEsoft Technologies, Oracle has modified the ICEbrowser to support conventions developed by Oracle to provide the following features:

Topic ID Links
Associative Links
Popups
Custom Protocol Links
Topic IDs
Window Types

For these features to work in OHJ, you must use the default ICEbrowser version of OHJ. If you substitute a different HTML display component, these features will not work. Also, if you display your HTML topic files directly in a web browser, that browser will not recognize the protocols and metadata documented on this page; therefore these features will not work.

OHW does support these features. However, the process is different than in OHJ. An OHW help system can be viewed in any current web browser, and those browsers do not directly support these conventions. Therefore, these custom features are processed in the OHW servlet on the web server and are streamed to users' browsers as standard HTML links and as browser-specific JavaScript.

Topic ID Links

The target of an HTML <a href="target"> link can be specified using either a URL (as with standard HTML links) or by using the Oracle Help topicid protocol, along with a topic ID specified in the helpset's map file. For example:


  <a href="topicid:getting_started">Getting Started</a>

When this link is clicked, Oracle Help references the map file and jumps to the HTML file associated with the link's topic ID.

For example, follow this link to try a topic ID link defined as follows:


  <a href="topicid:ohff_topicidex_html">this link</a>

Associative Links

An associative link is a link that is associated with more than one target. When the user selects an associative link in a topic, a list of all topics associated with the link is displayed, and the user can choose a topic from the list.

Oracle Help supports associative links through the Oracle Help alink protocol, along with the link file that specifies the associative links for the helpset. For example, an associative link that displays all the topics associated with the "worksheet" keyword is specified as follows:


  <a href="alink:worksheet">Related Topics</a>

Oracle Help uses the associative link keyword (in this case "worksheet") to search the link file (or files) and display a pop-up window with a list of related topics. This feature is particularly useful when link files from multiple helpsets are merged.

For example, select this link to display a list of associative links defined as follows:


  <a href="alink:alinkexamples">this link</a>

Custom Protocol Links

Oracle Help for Java 4.2.6 and later support links for custom protocols through the Oracle Help custom protocol. For example, a link that uses a custom protocol named "myProtocol" is specified as follows:


  <a href="custom:myProtocol:myValue">Link to activate custom protocol</a>

Defining custom protocols is a powerful way for your help system to call back into your application. You can handle such links in your application by registering a CustomProtocolHandler with your Help instance. Create an implementation of oracle.help.CustomProtocolHandler and register it with your oracle.help.Help instance via the registerCustomProtocolHandler method. For this example link, you would register an instance of your CustomProtocolHandler using the String "myProtocol" as the first argument to the registerCustomProtocolHandler method.

When Oracle Help for Java encounters links like the one above, it searches for a CustomProtocolHandler registered with the Help object using the identifier "myProtocol." If one is found, the CustomProtocolHandler's handleValue(String value) method is invoked, passing "myValue" as the value.

Popups

Popups are supported through the Oracle Help popup protocol. For example:


  <a href="popup:sheetdefinition">Sheet Definition</a>

The keyword that follows the popup protocol is a topic ID, as specified in the helpset's map file. When the pop-up link is clicked, the contents of the file associated with the topic ID is displayed in a lightweight pop-up window.

For example, select this link to display a popup defined as follows:


  <a href="popup:ohff_popupdemo_html">this link</a>

Topic IDs

Oracle Help topic IDs are maintained in the map file, and when Oracle Help needs to reference a topic ID, it uses the data from the map file. However, you can specify topic IDs in the topics file themselves and then use the Helpset Authoring Wizard to generate a map file from that information. To define a topic ID in a topic file, insert a META tag with this syntax:


  <META name="topic-id" content="topic_id_name">

where topic_id_name specifies the topic ID to be used in the map file.

Note: Third-party authoring tools may use this META tag for generating map files.

Window Types

The helpset file can contain a WinType section where you can define one or more named windows with characteristics such as size, position, and background color. You can associate topics (and topic IDs) with these window types in the map file so that whenever the topic is displayed, it is displayed in the specified window. This feature works only in OHJ; it is ignored in OHW.

If you plan to use the Helpset Authoring Wizard, you can associate a window type with a topic in the topic file itself. If you want to do this, you must also specify a topic ID in the topic-id META tag for the topic. Then the wizard uses the information from both META tags to generate the map file.

To associate a window with a topic in a topic file, insert a META tag with this syntax:


  <META name="window-type" content="window_name">

where window_name is the name of a window defined in the helpset file.

Notes:

You do not have to use this method for associating topics with window types. It may be easier to do it directly in the map file.
Third-party authoring tools may use this META tag for associating topics with window types.
In older versions of OHJ, the OHJ display engine read and used this META tag directly. This is no longer the case: the map file is now the central repository for this information.