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.
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>
Getting Started link is clicked, Oracle Help references the map file and jumps to the HTML file associated with the link's topic ID.
topicid protocol also supports anchor links. For example:
<a href="topicid:getting_started#advanced">Getting Started</a>
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
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>
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.
<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">
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">
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:
If those two engines do not satisfy your needs for dynamic mapping, you can write a custom implementation of
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
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_2 are not associated with window types and therefore use the helpset's default window type. The map IDs
topic_4 map to topic files that are displayed in the window defined by the intro window type. Map ID
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
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" /> </map>
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:
<maps> <mapref location="map.xml" engine="oracle.help.engine.XMLMapConventionEngine"/> </maps>
XMLMapConventionEngine supports the standard mechanisms for setting up topic ID and window type mappings. However, it also supports the new
If using the
map.xml may resemble the following:
<map version="1.1"> <topicNameConvention urlbase="http://www.example.org/help"> <text>beginningText</text> <filename/> <text>_</text> <extension/> <text>endingText</text> </topicNameConvention> </map>
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"> <topicNameConvention> <filename/> <text>_</text> <extension/> </topicNameConvention> <mapID .../> </map>
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
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
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
mapref would look like the following:
<mapref engine="XMLMap..." engineParams="oh help">
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.