9 Oracle Help for the Web Configuration File

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 OHW-RC and OHW-UIX servlet. A typical name for this file is ohwconfig.xml, but it can have any name, as long as that name is specified as the value of the configFileName initialization parameter for the servlet. The OHW-UIX and OHW-RC demonstration files uses ohwconfig.xml.

The configuration file consists of the following elements and their child elements:

• Section 9.1, "The <helpConfiguration> Element"

• Section 9.2, "The <brandings> Element"

• Section 9.3, "The <locales> Element"

• Section 9.4, "Sharing Resources Across Helpsets"

• Section 9.5, "The <parameters> Element"

• Section 9.6, "The <navigatorAliases> Element"

• Section 9.7, "Custom Protocol Links"

• Section 9.8, "Preloading Helpsets Containing Embedded Help"

9.1 The <helpConfiguration> Element

The <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, version and debugMode.

You must always set the version attribute of helpConfiguration element. For Oracle Help for the Web, the value of the attribute should be 2.0.

For example:

<helpConfiguration version="2.0">

9.1.1 The debugMode Attribute

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 9-1:

Debug Mode: 0 Missing Helpsets".

Figure 9-1 Helpset Information in Debug Mode

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

Whe 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 id and 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 <JDEV_HOME>\jdeveloper\systemversion\DefaultDomain\servers\DefaultServer\logs\DefaultDomain.log.

For example:

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 ohwconfig.xml:

<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 9-2:

Debug Mode: 1 Missing Helpsets".

Figure 9-2 Missing Helpset Information in Debug Mode

9.2 The <brandings> Element

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

The <brandings> element can contain only one of the elements described in the following table. If no branding information is specified, the default branding text is used.

Table 9-1 <brandings> Child Elements

Element	Description
<branding>	Renders branding information from attribute information and can be specified to work with certain locales. This element supports the following attributes: text – The text to be rendered. Note that you can provide simple HTML attributes such as italics by using the special character named entities (escape characters). For example, to preserve the italics in the name MyItalics, the branding text line would be: <branding text="My&lt;i&gt;Italics&lt;/i&gt;" /> imageHeight – The image height for the branding image. If not specified, the image is displayed with default height of 25 pixels. imageSource – The image source for a branding image. This takes precedence over the text if both are set. The declaration of an image location is not always the same as the translated path: For a servlet path like /foo/myImage.jpg, the translated path is /<context-root>/foo/myImage.jpg For an absolute path like http://mydomain.com/myImage.jpg the translated path is http://mydomain.com/myImage.jpg For an off the server root path like //foo/myImage.jpg the translated path is /foo/myImage.jpg imageShortDesc – A short description for the image. This text is displayed in the same way an ALT description is handled in HTML. For example, it appears when the mouse rolls over the image. locales – A space deliminated list of locales that this branding should be supplied for. If this is missing, the branding information will be applied across all registered locales. OHW narrows the locale used, but does not expand it. For instance, if you specified a locale nl and the browser was set to use locale nl_NL, OHW will first try and fail to find nl_NL, then try and succeed in finding nl. Thus, if you specify a more specific locale in OHW (nl_NL) and a less specific locale in the browser (nl), the specification will be ignored, in alignment with other standard locale mechanisms such as resource bundle.
<brandingFromResource>	Renders branding information from a ResourceBundle. This element supports the following attributes: resource - Java classname of ResourceBundle to use. textKey - The key into the ResourceBundle for the branding text. imageSourceKey - The key into the ResourceBundle for the branding image source. This takes precedence over the textKey is both are present. imageShortDescKey - The key into the ResourceBundle for the branding image description. This text is displayed in the same way an alt description is handled in HTML. For example, it appears when the mouse rolls over the image. locales - A space deliminated list of locales that this branding should be supplied for. If this is missing, the branding information will be applied across all registered locales. OHW narrows the locale used, but does not expand it. For instance, if you specified a locale nl and the browser was set to use locale nl_NL, OHW will first try and fail to find nl_NL, then try and succeed in finding nl. As a consequence of this, if you specify a more specific locale in OHW (nl_NL) and a less specific locale in the browser (nl), the specification will be ignored, in alignment with other standard locale mechanisms such as the resource bundle.

For example:

<brandings>
  <branding text="Oracle Help" />
</branding>

or

<brandings>
  <branding text="Help" locales="en en_US" />
  <branding text="Ayuda" locales="es" />
</brandings>

or

<brandings>
  <brandingFromResource resource="myApp.resource.MyBundle" textKey="title" />
</brandings>

9.2.1 Best Practice for Internationalization

When implementing internationalization, you can avoid having to translate ohwconfig.xml by using these best practices for helpsets that require translation:

1. Use <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.

2. Put an XML declaration at the top of all help control files: map, TOC, index, and helpset files. If you do this, you do not need to use <controlFileEncoding>. Use the same encoding for all control files in a given localized helpset. The encoding specified in the helpset file will be used to read in all of the control files.

   Note:

   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.

3. You need not separate out each different locale into a different file, because the file has nothing that needs to be translated. Some sites may wish to maintain the separation for other reasons.

9.3 The <locales> Element

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, will contain a single <locale> element.

Table 9-2 <locales> Child Element

Element	Description
<localeFromFile>	The <localeFromFile> element contains a single attribute and no children. The <locale> element within the external file will effectively replace the <localeFromFile> element functionally. This element supports the following attribute: source - The source of the file containing the <locale> element for this locale. This filename is relative to the configuration file.
<locale>	Specifies the ISO language, country, and (optionally) variant codes that will be 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). The first <locale> element listed is the default locale. This element supports the following attributes: language - A lowercase two-letter language code as defined by ISO-639 (for example, en for English). country - An uppercase two-letter country code as defined by ISO-3166 (for example, US for United States). variant - Optional variant code for browser or platform specific locales. group - Optional group that the locale is associated with. Group selection occurs on the URL with the special group parameter. The <locale> section supports children of type <book>.

For example:

<locales>
  <locale language="en">
    ... set of books for this locale ...
  </locale>
</locales>

9.3.1 The <locale> Child Element <books>

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

The <books> element can contain the following elements:

Table 9-3 <books> Child Elements

Element

Description

<helpSet>

A helpset to include in this instance of OHW. This element has the following attributes: id – Unique id to this book. This attribute is required. jar – The location of the JAR (Java Archive) file, if the helpset is in a JAR file. If this attribute is used, the location attribute must also be used to specify the location of the helpset file inside the JAR file. location – The location of the helpset file. If the helpset is not JARred, this is name of the helpset file, with any appropriate path information. The path can be either absolute or relative to the location of the configuration file. If this attribute is used with the jar attribute, the location is the location of the helpset file in the JAR file. controlFileencoding – A Java-supported encoding name. The set of supported encodings varies with JDK version. For a list of supported encodings for Java SE, see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.

For example:

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

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

9.3.2 The <contentLocation> Element

By default OHW automatically processes help topic files that are located in the same locations as helpset (.hs) files.

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.

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

The <contentLocation> element can be a child of <helpSet> (which are themselves children of <books>). A <helpSet> can contain zero or more <contentLocation> elements.

This element is needed because, unlike plain HTML files, Oracle Help help topic files must be processed by the servlet in order 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.

Absolute Path Content Locations

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, http://www.myCompany.com/help/remoteHelpSet.hs.

OHW thus processes help topic files both in the same location as myHelpSet.hs and in the remote location.

Relative Path Content Locations

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

The <baseURI> value would be:

../../common_images

9.3.3 Sample <locales> Section

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>

9.4 Sharing Resources Across Helpsets

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 helpeset 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 will need to 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 will appropriately convert 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 that you want 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 will fix this path so that it works under 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 ./en directory:

<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 wish to point to a shared image resource, the HTML file should contain this code:

<img alt="Image of cat" src="../../shared/images/cat.gif />

The extra .. in above code is required because the JAR file counts as a directory.

9.5 The <parameters> Element

The <parameters> element specifies the values of various other OHW parameters. These parameters are all case-insensitive.

Table 9-4 <parameters> Child Elements

Element	Description
<combineBooks>	If true, the views from all books are displayed in one set of navigators (tabs). If false, each book has its own set of navigators displaying just the information for that book.
<useLabelInfo>	If true, the author-defined labels are used for the navigators of merged helpsets. If false, the default labels are used, for example, the tab labels Contents, Index, and Search.
<displaySiteNavigation>	If true, turns on site navigation links across all supported navigators. For browsers that support site navigation, the appropriate links will be generated in the meta content of pages served by OHW.

When combineBooks is 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 useLabelInfo to 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 useLabelInfo to false in the configuration file.

For example:

<parameters>
  <combineBooks>true</combineBooks>
  <useLabelInfo>false</useLabelInfo>
</parameters>

Other important parameters include:

Table 9-5 <parameters> Keyword Child Elements

Element	Description
<keywordBlockSize>	The number of keywords to show on one page. The default value is 10.
<keywordTopicsBlockSize>	The number of topics to show on one page. The default value is 10.
<searchBlockSize>	The number of search results to show on one page. The default value is 10.

These elements are used to support performance tuning or specify non-default error, state, or locale handling.

Table 9-6 <parameters> Performance Child Elements

Element	Description
<maxSearchThreads>	The maximum number of threads that OHW can use to perform searches. Default value is 10.
<errorPage>	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.
<stateManager>	Specifies the state manager OHW should use. If set to 'cookie', user state will be saved for one month. If set to 'session', the user state will be saved through single request. The default is 'session'.
<localeDeterminer>	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.
<cacheSize>	The number of active localized helpsets to be kept in memory at one time. The default value is 3.

9.6 The <navigatorAliases> Element

The optional <navigatorAliases> element allows 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.

For example:

<navigatorAliases>
  <alias name="oracle.help.navigator.tocNavigator.TOCNavigator" value="oracle.help.web.navigator.tocNavigator.TOCTreeNavigator" />
</navigatorAliases>

Note:

The tree-based TOC Navigator of OHW uses the oracle.help.web.navigator.tocNavigator.TOCTreeNavigator class name.

9.7 Custom Protocol Links

OHW supports links for custom protocols through the Oracle Help custom protocol. For information about custom protocol links in OHJ, see Section 8.3, "Custom Protocol Links".

In order to handle custom protocol links in OHW, clients need to 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 will process 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.

9.8 Preloading Helpsets Containing Embedded Help

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 will be 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-UIX, all helpsets for a locale are loaded on demand and all at once. In OHW-RC, the loading of helpsets is handled in a different manner. The OHW-RC 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-RC, the configuration file supports an optional attribute for the <locale> tag, which is called preload. The possible values that this attribute can take are NONE, ALL, and TOPICMAP. If not specified, its value defaults to NONE.

The behaviors of each value are:

Table 9-7 Preload Value Behavior

Preload Value	Initial Start of OHW	When Topic is Accessed	When UI is Accessed
NONE	No action required.	Load the topic map until the requested topic is found.	Load all views and navigators in the selected helpset.
ALL	Load all helpsets in the locale (which initializes all views and navigators) and also load all topic maps.	Access from cache.	Access from cache.
TOPICMAP	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>