This chapter describes the topic files, topic ID and associative links, popups, window types, and custom protocol links used by OHJ , OHW-RC, and OHW-UIX.
This chapter includes the following sections:
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.
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-UIX and OHW-RC do 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-UIX or OHW-RC servlet on the web server and are streamed to users' browsers as standard HTML links and as browser-specific JavaScript.
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.
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 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>
For more information about link file, see Section 7.5, "Link File".
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 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 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.
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>
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 filesFor more information about Helpset Authoring Wizard, see Chapter 11, "Helpset Authoring Wizard".
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.
Note:
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. 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.
Note:
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.
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 will expect the location attribute to be set on the <mapref>, and the map file will be 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.
In many cases, for a filename of myfile.html, the corresponding topic ID is just myfile_html. If your map file is simply a long, redundant list of obvious topic mappings of this form, you will want to set the engine attribute on <mapref> to oracle.help.engine.XMLMapFixedConventionEngine.
While using Oracle Help, setting the engine to this value will make 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 will not be 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 will be displayed in the window defined by the intro window type. Map ID topic_5.tsk will display File_5.html in the window defined by the task window type. Map ID topic_5.cncpt will display the same topic file (File_5.html) in a different window type (concept). Note also that the association between URL and wintype will be 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.
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>
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">
<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 etc.../>
</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 my_file.html.
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 will attempt 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 will only try to resolve topics if they start with a valid prefix, preventing an attempted connection to an URL. Failure to set engineParams will not break your help system, but performance will not be optimal.