7 Topic Files

This chapter describes the topic files, topic ID and associative links, popups, window types, and custom protocol links used by OHJ and OHW.

This chapter includes the following sections:

7.1 About 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 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 also runs 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:

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 Oracle Help for the Web 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.

7.2 Topic ID Links

The target of an HTML <a href="target"> link can be specified using either a URL (as with standard HTML links), anchor 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 the Getting Started link is clicked, Oracle Help references the map file and jumps to the HTML file associated with the link's topic ID.

The topicid protocol also supports anchor links. For example:

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

When the Getting Started link is clicked, Oracle Help references the map file and jumps to the advanced anchor position in HTML file associated with the link's topic ID.

7.3 Associative Links

An associative link is a link that is associated with multiple targets. 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 topics associated with the "worksheet" keyword is specified as follows:

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

Oracle Help uses the associative link keyword to search the link file (or files) and display a pop-up window with a list of related topics. The 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>

For more information about link file, see Section 6.6, "Link File".

7.4 Custom Protocol Links

Oracle Help for Java 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 through the registerCustomProtocolHandler method. For the 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 custom protocol links, it searches for a CustomProtocolHandler registered with the Help object using the identifier myProtocol. If one is found, the handleValue(String value) method of the CustomProtocolHandler is invoked, passing myValue as the value.


If you want to provide link to an external URL, you are not required to register a custom protocol handler. OHJ provides a registered custom protocol external for the same.

For example, the following code creates a link that navigates to OTN page in the default internet browser instead of OHJ browser.

<a href="custom:external:http://www.oracle.com/technetwork/index.html">Oracle Technology Network</a>

7.5 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:

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

7.6 Topic IDs

Oracle Help topic IDs are maintained in the map file, and when Oracle Help must 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 the following syntax:

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

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


Third-party authoring tools may use the META tag for generating map files

For more information about Helpset Authoring Wizard, see Chapter 10, "Helpset Authoring Wizard".

7.7 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.


Window Types are available for OHJ only.

If you plan to use the Helpset Authoring Wizard, you can associate a window type with a topic in the topic file itself. and 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 the following syntax:

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

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


  • 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.

7.8 Dynamic Mapping of Topic IDs to Files

If your helpset uses a simple convention to map between topic IDs and map files, you may be able to significantly enhance Oracle Help's memory usage and startup time with dynamic mapping.

Oracle Help supports an engine attribute on the <mapref> subelement of the helpset's <maps> area. By setting the engine attribute, one can use a custom engine to parse the map file and create an object used to map between topic IDs and files. In fact, by using certain engines, you may actually eliminate the map file altogether.The engine attribute is optional, so if it goes unspecified, Oracle Help expects the location attribute to be set on the <mapref>, and the map file is parsed and stored in the same manner as it was in older versions of Oracle Help.However, Oracle Help supports two engines that support certain common conventions for mediating between topic IDs and files:

  • oracle.help.engine.XMLMapFixedConventionEngine

  • oracle.help.engine.XMLMapConventionEngine

If those two engines do not satisfy your needs for dynamic mapping, you can write a custom implementation of oracle.help.engine.DataEngine.

7.8.1 The oracle.help.engine.XMLMapFixedConventionEngine Help Engine

In many cases, for a filename of myfile.html, the corresponding topic ID is just myfile_html. If your map file is long and redundant list of obvious topic mappings of this form, you must set the engine attribute on <mapref> to oracle.help.engine.XMLMapFixedConventionEngine.

While using Oracle Help, setting the engine to this value makes your old map file expendable. However, if your help content may be viewed using an older version of Oracle Help, you should keep your old map file around so that the older versions of Oracle Help can fall back to the standard mechanism of topic mapping.

If you are concerned about the help system's memory usage and startup time, it is strongly recommended that you use this new engine. Doing so implies that your map file is never read, and therefore its contents are not stored in the memory. However, there is one caveat to the engine's use:

All help content (HTML files) must reside in the same directory as the helpset file. In addition, any subhelpsets must also reside in the same directory as the master helpset file. Subdirectories for subhelpsets are not permitted because the help system is not able to find your content unless it is in the same directory as the master helpset. However, different helpsets may reside in different directories.:

In the following example, the map IDs topic_1 and topic_2 are not associated with window types and therefore use the helpset's default window type. The map IDs topic_3 and topic_4 map to topic files that are displayed in the window defined by the intro window type. Map ID topic_5.tsk displays File_5.html in the window defined by the task window type. Map ID topic_5.cncpt displays the same topic file (File_5.html) in a different window type (concept). Note also that the association between URL and wintype is used when linking from topic to topic using URLs instead of topic IDs. For example, if a topic had a hard-coded target to File_5.html, clicking the link would display the HTML content in a task window type.

<?xml version='1.0' ?>
<map version="1.0">   
    <mapID target="topic_1" url="file_1.html" />
    <mapID target="topic_2" url="file_2.html#a1" />
    <mapID target="topic_3" url="file_3.html" wintype="intro" />
    <mapID target="topic_4" url="file_4.html#a2" wintype="intro" />
    <mapID target="topic_5.tsk" url="file_5.html" wintype="task" />
    <mapID target="topic_5.cncpt" url="file_5.html" wintype="concept" />

This scheme allows authors to assign window types to HTML files and to also override those associations by linking to an alternate topic ID. For example, for topic-to-topic links, TOC links, index links, and hard-coded links to File_5.html, the author might use topic_5.tsk, but for links from a tutorial, the author might use topic_5.cncpt. By keeping this information in the map file, the author has one central repository for managing these assignments.

7.8.2 The oracle.help.engine.XMLMapConventionEngine Help Engine

If on your <mapref> element you set engine to be oracle.help.engine.XMLMapConventionEngine you may define your own topic name convention in your map file. For example, consider the following <maps> definition in a helpset:

  <mapref location="map.xml" engine="oracle.help.engine.XMLMapConventionEngine"/>

The XMLMapConventionEngine supports the standard mechanisms for setting up topic ID and window type mappings. However, it also supports the new <topicNameConvention> element.

If using the XMLMapConventionEngine, your map.xml may resemble the following:

<map version="1.1">
  <topicNameConvention urlbase="http://www.example.org/help">

The idea of the <topicNameConvention> is simple.You simply specify how your topic IDs are structured. If you set the urlBase attribute on the <topicNameConvention>, all help content files are assumed to be located at that URL. If all of your topic IDs begin with a string that is not a part of the filename or extension, you can specify a value for <text> at the beginning of the convention. Then you must specify either the <filename/> or the <extension/> to indicate whether the filename or extension appears first in your topic name convention. Then you can specify the <text> that separates the filename and extension. Either the <filename/> or the <extension/> should follow to indicate whether the filename or extension appears second in the convention. A final <text> may be specified if all topic IDs end with some text that is not part of the filename or extension.

According to the above topic name convention, the topic ID of beginningTextmyfile_htmlendingText would resolve to the file http://www.example.org/help/myfile.html. If the urlBase attribute was unspecified, it would be assumed that myfile.html is in the same directory as the helpset file.

If you want to set up some standard topic mappings and window types in your map file but still use the topic name convention provided by the XMLMapFixedConventionEngine, you could define a topicNameConvention in your map file as follows:

<map version="1.1">
  <mapID .../>

In the above convention and the XMLMapFixedConventionEngine, the text that separates the filename and extension can appear multiple times in the topic ID. For example, consider the topic my_file_html. The engines assume that the separator between filename and extension is actually the last appearance of the "_" character in the topic ID. Therefore, the topic resolves to my_file.html.

7.8.3 Optimizing Dynamic Maps

Dynamic mapping of topic IDs to files can result in great improvements in your help system performance. However, context sensitive help calls to specific topics may take a long time to resolve if your library includes many helpsets.

The fundamental reason for this is that the convention-based mapping engines return URLs for topic IDs even if the URLs do not resolve to anything. Because of this, context sensitive help calls go through each helpset in the library and check whether the URLs generated by the engines actually resolve.

In the worst case, for a single context sensitive help call, the help system attempts to connect to as many URLs as there are helpsets in your library. However, Oracle Help provides a simple remedy to alleviate the problem. If you set an engine on your <mapref> element, you may also set the engineParams attribute.

If you use the XMLMapConventionEngine or the XMLMapFixedConventionEngine, you may want to set engineParams to be a space-separated list of prefixes for the topics in your helpset. For example, if all topics in your helpset begin with either oh or help, your mapref would look like the following:

<mapref engine="XMLMap..." engineParams="oh help">

Setting engineParams for either of the convention-based engines ensures that the helpset only tries to resolve topics if they start with a valid prefix, preventing an attempted connection to an URL. Failure to set engineParams does not break your help system, but performance will not be optimal.