This chapter includes the following sections:
The Oracle Help for the Web configuration file is an XML file that defines a OHW configuration. This configuration controls all adjustable features of the OHWservlet. A typical name for this file is
ohwconfig.xml, but it can have any name, if that name is specified as the value of the
configFileName initialization parameter for the servlet. The OHW demonstration files uses
<helpConfiguration> element is the top-level element in the help configuration file. All of the elements of the configuration, described below, should appear between the
<helpConfiguration> tag and the
</helpConfiguration> tag. The
helpConfiguration element has two attributes,
You must always set the
version attribute of
helpConfiguration element. For Oracle Help for the Web, the value of the attribute should be
Enable debug mode by setting
debugMode="true" on the
<helpConfiguration> element in
ohwconfig.xml. This allows helpsets to be loaded in debug mode, where malformed helpsets are skipped over. The debug text is displayed along with the branding information in the upper left corner of the screen and in the title bar of the browser. The debug text indicates how many malformed helpsets have been skipped over while running the application.
If there are no malformed helpsets, following message is displayed in the branding area, also shown in Figure 8-1:
Debug Mode: 0 Missing Helpsets".
There could be many reasons for a malformed helpset. The following are some common reasons:
id attribute is missing
id attribute is a duplicate id
location attribute is missing
location points to an invalid location
When you deploy the help system, a WARNING message is logged to indicate that debug mode is being used. Whenever a helpset is skipped over, a SEVERE message is logged (instead of throwing an exception), and the log message displays the
location attributes of the helpset that was skipped over. By default, the log messages are logged through
System.err stream and are displayed in the developer environment's console window. If you're using JDeveloper, the messages are logged in the Log window and a log file is created at
Let's assume you enabled the
debugMode as follows:
<helpConfiguration version="2.0" xmlns="http://xmlns.oracle.com/help/web/config" debugMode="true" >
Then, if you changed the location of your
ohguide helpset to
ohguide_new directory, but forgot to update the corresponding path in
<books> <helpSet id="ohguide" location="ohguide/ohguide.hs"/> <helpSet id="shake" location="shakespeare/shakespeare.hs"/> </books>
The following message is displayed in the branding area, also shown in Figure 8-2:
Debug Mode: 1 Missing Helpsets
<brandings> element specifies the product branding text or image that appears above the tab bar. The
<brandings> does not have any attributes, and is a placeholder for all brandings information.
<brandings> element can contain only one element described in the following table. If no branding information is specified, the default branding text is used.
Renders branding information from attribute information and can be specified to work with certain locales. This element supports the following attributes:
OHW narrows the locale used, but does not expand it. For instance, if you specified a locale
Renders branding information from a
OHW narrows the locale used, but does not expand it. For instance, if you specified a locale
If you are using XLIFF resource bundles, add the resource bundle support (
resourcebundle.jar) library in the classpath.
resourcebundle.jar file is available in
<MW_HOME>\oracle_common\modules\oracle.javatools_11.1.1\ directory, where
MW_HOME is the middleware home.
<brandings> <branding text="Oracle Help" /> </branding>
<brandings> <branding text="Help" locales="en en_US" /> <branding text="Ayuda" locales="es" /> </brandings>
<brandings> <brandingFromResource resource="myApp.resource.MyBundle" textKey="title" /> </brandings>
When implementing internationalization, you can avoid having to translate
ohwconfig.xml by using these best practices for helpsets that require translation:
<brandingFromResource> to reference a bundle that is translated for all locales, instead of putting the branding information directly into
ohwconfig.xml. Because the branding information comes from a standard Java resource bundle, the bundle can be translated as part of the regular translation process.
Put an XML declaration at the top of all help control files: map, TOC, index, and helpset files. If you do this, you must not use
<controlFileEncoding>. Use the same encoding for all control files in a given localized helpset. The encoding specified in the helpset file is used to read in all of the control files.
If you are using an old version of OHJ, the helpset may not recognize an XML declaration and so may require
<controlFileEncoding> to be set.
You need not separate out each different locale into a different file, because the file has nothing that must be translated. Some sites may want to maintain the separation for other reasons.
You can specify a single locale or multiple locales in the
<locales> section of the
ohwconfig.xml file. The locales section has one or more tags specifying a single locale in the system. These tags are either of type
<locale> element or
<localeFromFile> element. As the names suggest, the
<locale> element specifies the locale inline, whereas the
<localeFromFile> element delegates the declaration of the locale to an external file. The external file, in turn, contains a single
Specifies the ISO language, country, and (optionally) variant codes that is used to construct a Java Locale for locale-sensitive operations. Also specifies the Java-supported encoding name for the character set encoding of the Oracle Help control files (for example, ISO8859_1).
This element supports the following attributes:
<locales> <locale language="en"> ... set of books for this locale ... </locale> </locales>
<books> element specifies the content to be displayed in Oracle Help for the Web. The
<books> element can contain any number of helpsets. Helpsets are also called as books.
<books> element can contain the following elements:
A helpset to include in this instance of OHW. This element has the following attributes:
<books> <helpSet id="shakre" location="shakespeare/shakespeare.hs" /> <helpSet id="myproduct" location="myProduct/myProductHelp.hs" /> <helpSet id="myhelpset" jar="myJar.jar" location="myHelpset.hs" /> </books>
<helpSet> elements can contain zero or more
<contentLocation> elements for situation when help topic files are located in locations other than those expected by Oracle Help.
By default OHW automatically processes help topic files that are located in the same locations as helpset (
In helpsets, OHW processes help topic HTML files:
in the same directory as the
.hs file and subdirectories under that location
or if the helpset is in a JAR file, all help topic files in the same JAR
If you have help topic files in some other location, you must use the
<contentLocation> element to point to that location.
<contentLocation> element has the attribute
baseURI. It represents a URI to the root location of a set of help content, using a path that is either absolute or relative.
<contentLocation> element can be a child of
<helpSet> (which are themselves children of
<helpSet> can contain zero or more
This element is needed because, unlike plain HTML files, Oracle Help help topic files must be processed by the servlet to be displayed. Therefore, it is necessary to explicitly list the locations where help topic files referenced in the helpset reside, if they are not in the default locations. This can happen if your helpset includes a subhelpset in another location or even on another web server or if your context sensitive map file contains references to help topic files located elsewhere on the same server or on a different server.
If you know the absolute path of content location, you can specify the absolute path.
For example, if OHW is configured with a local helpset,
myHelpSet.hs, that references a subhelpset on another server,
http://www.myCompany.com/help/remoteHelpSet.hs, the configuration file should contain:
<books> <helpSet id="myhelpset" location="myHelpSet.hs"> <contentLocation baseURI="http://www.myCompany.com/help/" /> </helpSet> </books>
This configuration informs OHW that the local
myHelpSet.hs file references help content on that server. For example,
OHW thus processes help topic files both in the same location as
myHelpSet.hs and in the remote location.
If you do not know the absolute path of the content location, you can specify a relative content location. These locations are relative to the configuration file, not the helpset file, and must be terminated with a trailing slash.
For example, to specify a content location that is under
images directory, which is located in the same directory as the configuration file, you could declare the following:
<contentLocation baseURI="images/" />
To specify a content location pointing to an images directory that is located one directory below the configuration file, you can declare the following:
<contentLocation baseURI="../images/" />
The location is relative to the helpset. If the helpset is inside a JAR file, the JAR file is evaluated as a directory when resolving the relative path. For instance, assume these directory paths:
/myhelpsets/myhs.jar /myhelpsets/myhs.jar!myhelpset.xml /common_images
<baseURI> value would be:
This sample of the section of a configuration file specifies an English and Japanese configuration file.
<locales> <!-- An English locale --> <locale language="en" country="US" controlFileEncoding="UTF-8"> <books> <helpSet id="hs1" location="ohguide/ohguide.hs"/> <helpSet id="hs2" location="shakespeare/shakespeare.hs"/> </books> </locale> <!-- A Japanese locale from an external file --> <localeFromFile source="jp_config.xml" /> </locales>
If you have many localized helpsets all using the same images, CSS stylesheets, or other resources, OHW can support the sharing of these resources across the helpsets. Typically, shared resources exist in a separate directory, usually below any subdirectories holding the localized helpset information. For instance, the following is a typical directory structure for using shared resources:
<main directory> ohwconfig.xml /en - owh_helpset_en.hs - English helpset files /es - ohw_helpset_es.hs - Spanish helpset files /shared /images - shared images /css - shared stylesheets
Since OHW by default can only access directories that are underneath the
.hs file. Thus to make the shared directory available to OHW, you must define a content location for this directory. For best results, use a relative content location for this task.
OHW supports relative paths when dealing with resources, and appropriately converts these paths to the correct paths at runtime. To make use of shared resources, an HTML file can point to the resource using a relative path. For example, if you have an HTML file in the
./en directory to point to a shared image resource, the HTML file should contain the following code:
<img alt="Image of cat" src="../shared/images/cat.gif />
If you have the content location defined, OHW fixes this path so that it works at runtime. You can also use relative paths within the control files for your helpset. For example, you could define the following code in your map file that is located in the
<mapID target="someDescriptor" url="../shared/html_files/theContent.html" />
Finally, if your localized helpset is contained in a JAR file, then the JAR file is counted as a directory when specifying the relative path. Thus, if all helpset files are contained in a JAR under the
./en directory, and you want to point to a shared image resource, the HTML file should contain this code:
<img alt="Image of cat" src="../../shared/images/cat.gif />
.. in above code is required because the JAR file counts as a directory.
<parameters> element specifies the values of various other OHW parameters. These parameters are all case-insensitive.
true, only navigators of the same type and with the same label are merged into the same navigator, for example the Index tab. That can lead to unintended results if you have set
true. For example, if one helpset has overridden the default Index label with Keyword Index and left another with the default, the indexes won't be merged in the same tab. You can change this by setting the labels to be the same (in the helpset file for a helpset) or by setting
false in the configuration file.
<parameters> <combineBooks>true</combineBooks> <useLabelInfo>false</useLabelInfo> </parameters>
Other important parameters include:
The number of keywords to show on one page. The default value is
The number of topics to show on one page. The default value is
The number of search results to show on one page. The default value is
These elements are used to support performance tuning or specify nondefault error, state, or locale handling.
The maximum number of threads that OHW can use to perform searches. Default value is
If you presume that many users would be connected to the help system and using the search feature at the same time, you can increase the value of maxSearchThreads to more than 10, however it is not recommended. If the help system does not respond during search, verify that the index file (
When a topic is not found, OHW displays this topic instead. The value of this parameter is a topic ID. OHW provides a standard error page if no value is set.
Specifies the state manager OHW should use. If set to
OHW uses the specified locale determiner to select a localized helpset based on a user request. OHW provides a default locale determiner that uses browser settings to determine the locale if no value is set.
The number of active localized helpsets to be kept in memory simultaneously. The default value is
<navigatorAliases> element enables you to use classnames in your helpset file that do not correspond to the classnames of the navigators in OHW. Alias registrations are done through the use of the
<alias> element. The
<alias> elements are contained within a single
<navigatorAliases> element, and has the following attributes:
name - The name to use as the alias.
value - The value this alias should map to.
<navigatorAliases> <alias name="oracle.help.navigator.tocNavigator.TOCNavigator" value="oracle.help.web.navigator.tocNavigator.TOCTreeNavigator" /> </navigatorAliases>
The tree-based TOC Navigator of OHW uses the
oracle.help.web.navigator.tocNavigator.TOCTreeNavigator class name.
OHW supports links for custom protocols through the Oracle Help custom protocol. For information about custom protocol links in OHJ, see Section 7.4, "Custom Protocol Links."
In order to handle custom protocol links in OHW, clients must register Custom Protocol Converters in the
ohwconfig.xml file for each custom protocol used in their help content. The syntax in the
ohwconfig.xml file looks like this:
<customProtocolRegistry> <customProtocol name="xlink" class="oracle.help.web.converter.ConfigurableCustomProtocolConverter"> <parameters> <prepend>http://www.myserver.com/index.jsp?someParam=</prepend> <targetFrame>_blank</targetFrame> </parameters> </customProtocol> </customProtocolRegistry>
Users may write their own implementations of
CustomProtocolConverter. However, OHW includes the
ConfigurableCustomProtocolConverter, which is configurable using parameters set in
ohwconfig.xml. The supported parameters are:
<prepend>optional string to be prepended to the value</prepend> <append>optional string to be appended to the value</append> <targetFrame>optional target frame</targetFrame>
In an HTML topic file, authors could use the standard Oracle Help custom protocol syntax. For example:
<a href="custom:xlink:someXLINKID">An Example Custom Protocol Link</a>
OHW processes all
custom:links and run them through the Custom Protocol Converter registered for that custom protocol name.
The link in the above example would be replaced with:
<a href="http://www.myserver.com/index.jsp?someParam=someXLINKID" target="_blank" />
In OHJ, it is a popular convention to use
custom:external: to launch a link in a new browser window. In OHW, the built-in
CustomProtocolConverter for the external protocol enables the links to work without the users having to explicitly register a converter.
OHW supports the
<locale> tag in the OHW configuration file, which defines a single instance of a locale that OHW supports. The
<locale> tag specifies the ISO language, country, and (optionally) variant codes that are used to construct a Java Locale for locale-sensitive operations. It also specifies the Java-supported encoding name for the character set encoding of the Oracle Help control files (for example, ISO8859_1). The first
<locale> element listed is the default locale.
In OHW, the loading of helpsets is handled in a different manner. OHW as an RCF application may have a screen with 50 components, with Definition Text content, specified in a single file within its own helpset. To avoid loading all helpsets and reduce the lag that this would cause when a user simply opens that screen, preloading of a selected helpset is desirable.
So, for OHW, the configuration file supports an optional attribute for the
<locale> tag, which is called
preload. The possible values that this attribute can take are
TOPICMAP. If not specified, its value defaults to
The behaviors of each value are:
|Preload Value||Initial Start of OHW||When Topic is Accessed||When UI is Accessed|
No action required.
Load the topic map until the requested topic is found.
Load all views and navigators in the selected helpset.
Load all helpsets in the locale (which initializes all views and navigators) and also load all topic maps.
Access from cache.
Access from cache.
Load only the topic maps for all helpsets in the locale.
Access from cache.
Load all views and navigators in the selected helpset.
For example, the configuration file could look like this:
<?xml version='1.0' ?> <helpConfiguration> ... <locales> <locale language="en" preload="ALL"> <books> <helpset id="helpset1" location=" helpset1.hs"/> <helpset id=" helpset2" location=" helpset2.hs"/> </books> ... </locale> </locales> ... </helpConfiguration>
OHW provides a method to reload the Oracle Help for the Web configuration file at runtime to include any changes made in the file while help system is running. An example of such a change is including future patched helpsets without redeploying the help system. When the configuration file reloads, it empties the cache and rebuilds it again.
If you want that user can reload the configuration file at runtime, add a new parameter
web.xml, create a new parameter
ohwConfigAutoUpdate and set it to
For example, the
web.xml file could look like this:
<?xml version = '1.0' encoding = 'UTF-8'?> ... <init-param> <param-name>ohwConfigAutoUpdate</param-name> <param-value>true</param-value> </init-param>
Update the configuration file as desired.
Open the default home page of the help application after updating the configuration file.
The old configuration settings are cleared and new settings take effect after the help application home page is opened.