Oracle® Fusion Middleware Developer's Guide for Oracle Help 11g Release 2 (11.1.2.1.0) Part Number E16280-02 |
|
|
PDF · Mobi · ePub |
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.
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 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.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 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.
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 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.
Note:
Third-party authoring tools may use the META tag for generating map filesFor more information about Helpset Authoring Wizard, see Chapter 10, "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. 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.
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 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
.
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" /> </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 .../> </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 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.