Skip navigation header
Oracle Help File Formats Table of Contents
Contents 		Previous topic
Previous 		Next topic
Next

OHW Configuration File

The Oracle Help for the Web (OHW) configuration file is an XML file that defines a OHW configuration. This configuration controls all adjustable features of the OHW 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 demonstration bundle uses ohwconfig.xml.)

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

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

The <branding> element specifies the product branding text or image that appears above the tab bar. The <branding> element can contain only one of the elements described in the following table. If both are present, <brandingImage> is used and <brandingText> is ignored. If no branding information is specified, OHW uses default branding text.

Element Description
<brandingText>

Renders text above the tab bar. This element supports the following attribute:

text - The text to be rendered.
<brandingImage>

Displays an image above the tab bar. This element supports the following attributes:

source - The image to display. The path to the image can be absolute or relative to the location of this file.

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

For example:


<branding>
  <brandingText text="Oracle iSomething Help" />
</branding>
or 

<branding>
  <brandingImage source="images/anImage.gif" shortDesc="Oracle iSomething Help branding image" />
</branding>

The <localeSettings> Element

OHW automatically uses the system default Java Locale and the default encoding for that Java Locale for locale-sensitive operations on Oracle Help control files. You can override this behavior with the <localeSettings> element. Note that the encoding for topic (HTML) files is specified directly in those topic files.

The <localeSettings> element must appear before the <books> element in the OHW configuration file. The <localeSettings> element can contain the following elements:

Element Description
<locale>

Specifies the ISO language, country, and (optionally) variant codes that will be used to construct a Java Locale for locale-sensitive operations. This element supports the following attributes:

language - A lowercase two-letter language code as defined by ISO-639 (example "en" for English).

country - An uppercase two-letter country code as defined by ISO-3166 (example "US" for United States).

variant - Optional variant code for browser or platform specific locales.

<controlFileEncoding>

Specifies the Java-supported encoding name for the character set encoding of the Oracle Help control files (example "ISO8859_1"). This element supports the following attribute:

encoding - A Java-supported encoding name. The set of supported encodings varies with JDK version. For a list of supported encodings for Sun's JDK 1.3, see http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html.

For example:


<localeSettings>
  <locale language="en" country="US"  />
  <controlFileEncoding encoding="ISO8859_1" />
</localeSettings>

The <books> Element

The <books> element specifies the content to be displayed in OHW. The <books> element can contain any number of helpsets, helpbooks, or a combination of both. (Helpsets and helpbooks are generically called "books.") The merging behavior is specified by providing values for the following attributes:

combineBooks - If true, the views from all the 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/helpbooks. If false, the default labels are used, for example, the tab labels Contents, Index, and Search.

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 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, for example) or by setting useLabelInfo to false in the OHW configuration file.

The <books> element can contain the following elements:

Element Description
<helpSet>

A helpset to include in this instance of OHW. This element has the following attributes:

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 informaton. The path can be either absolute or relative to the location of the OHW configuration file. If this attribute is used with the jar attribute, the location is the location of the helpset file in the JAR file.
<helpBook>

The helpbook to include in this instance of OHW. This element has the following attributes:

basename - The name, without the file name extension, of the control files in the directory. For example, if the control files are named myproject.hhc, myproject.hhk, myproject.idx, etc., the basename is "myproject."

location - The location of the helpbook file. The path can be either absolute or relative to the location of the OHW configuration file.

title - The title to use when if helpbooks/helpsets are merged, and the helpbook is displayed in the merged book list in the OHW user interface. (By contrast, this title is set in the <title> element in the helpset file for a helpset.)

For example:


<books combineBooks="true" useLabelInfo="true">
 <helpSet location="shakespeare/shakespeare.hs" />
 <helpSet location="myProduct/myProductHelp.hs" />
 <helpSet jar="myJar.jar" location="myHelpset.hs" />
 <helpBook baseName="discoverer" location="discoverer/" title="Discoverer Help" />
</books>

The <helpBook> and <helpSet> elements can contain zero or more <contentLocation> elements for situtation when help topic files are located in locations other than those expected by Oracle Help. See The <contentLocation> Element, described below.

Note: Helpbook files and helpBook objects were used in older versions of OHJ. While it is recommended that you use helpsets in current versions, Oracle Help still supports helpbooks. For information about helpsets vs. helpbooks in OHJ, see Adding the Help Data.

The <contentLocation> Element

By default OHW automatically processes help topic (HTML) files that are located in the same locations as helpset (.hs) files or helpbook base directories:

In helpsets, OHW processes help topic HTML files:

In helpbooks, OHW processes help topic HTML files:

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 following attribute:

baseURI - An absolute URI to the root location of a set of help content.

The <contentLocation> element can be a child of <helpBook> or <helpSet> (which are themselves children of <books>, discussed above). <helpBook> and <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 OHW servlet in order to be displayed. Therefore, it is necessary to explicitly list the locations where help topic files referenced in the helpbook or 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.)

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 combineBooks="true" useLabelInfo="true">
  <helpSet 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, e.g., http://www.myCompany.com/help/remoteHelpSet.hs. OHW therefore knows to process help topic files both in the same location as myHelpSet.hs and in the remote location.

The <parameters> Element

The <parameters> element specifies the values of various other OHW parameters. This element can contain the following elements:

Element Description
<maxSearchThreads>

The maximum number of threads to be spawned for searching, as required by the search navigator. This will be the maximum number of simultaneous searches that OHW can perform. This value should be carefully tuned to correspond to the anticipated load on the servlet.
<defaultHomeID>

The topic ID (from the map file) for the topic that should appear by default when a user goes directly to the URL for the OHW help system, as opposed to going to a specific topic.

For example:


<parameters>
  <maxSearchThreads>10</maxSearchThreads>
  <defaultHomeID>myTopicID</defaultHomeID>
</parameters>

 

Contents   |    Previous   |    Top of Page   |    Next

Copyright © 1996, 2004, Oracle. All rights reserved.