Oracle Help File Formats	Contents	Previous	Next

Helpset File

The helpset file is an XML file that organizes project-level information about the helpset. For example, it points to other control files to be used for the helpset, including map, table of contents, index, associative links, and search. These references are used, in part to define the set of navigational views that Oracle Help uses to construct the user interface.

(Older versions of OHJ used a "helpbook" file and a HelpBook object. Helpbooks are still supported in current versions of OHJ; however, it is preferrable in current versions to use helpsets (helpset file and HelpSet object). See Adding the Help Data for information about programming OHJ with helpbooks vs. helpsets.)

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

• <helpset>
• <title>
• <maps>
• <wintype>
• <links>
• <view>
• <subhelpset>

This topic also shows a sample helpset file.

The <helpset> Element

The contents of a helpset file are entirely contained within a single <helpset> element.That is, a helpset file must begin with <helpset> and end with </helpset>. Only one <helpset> element is allowed in a helpset file.

The <title> Element

The <title> element assigns a name to the helpset. For example:

  <title>API Reference</title>

Under certain conditions, this title is displayed in the Oracle Help user interface as the name of the helpset. For example, it is displayed in the drop-down list of helpsets when Oracle Help is implemented to display a list of merged helpsets (instead of concatenating them). For more information about his feature, see the following:

• Merged Helpsets gives an illustration of this behavior in the OHJ user interface.
• Constructing the Help object tells how to implement OHJ to display the list of merged helpsets.
• The <books> Element tells how to configure OHW to display this list.

The <maps> Element

The <maps> element points to one or more map files, which are used to map topic IDs to topic files. The <maps> element has the following child elements:

Example:

  <maps>
    <mapref location="main_map.xml"/>
    <mapref location="tutorial/tut_map.xml"/>
  </maps> 

The <wintype> Element

The <wintype> element defines the characterisics of one or more windows that can be used by OHJ to display topics, including size, screen placement, text color, and background color. See OHJ Topic Windows for examples of how this looks in the OHJ user interface. OHW ignores this element. This information is also ignored if topics are displayed directly in a web browser.

The helpset file can have any number of <wintype> sections; one for each window type. The <wintype> tag has one valid attribute:

default - If true, the current window type is the default window type to be used if a topic file does not designate a window type. If false, this window type is not a default and will not be used except when explicitly listed in the map file. When the default attribute is not present, its value is assumed to be false.

The <wintype> element can have the following child elements:

Note that attributes specified in HTML topic content files always take precedence over attributes specified in the <wintype> section of the helpset.

The following <wintype> element defines a window to be used for tutorial topics:

  <wintype default=false>
    <name>Tutorial</name>
    <height>50%</height>
    <width>200</width>
    <x>10</x>
    <y>10</y>
    <textfg>000000</textfg>
    <linkfg>0000cc</linkfg>
    <bg>ffffff</bg>
    <title>Tutorial</title>
    <toolbar>06004</toolbar>
  </wintype>

This example defines a window type called "Tutorial" with a default height that is 50% of the screen height and a default width of 200 pixels. This window will display 10 pixels from the top and left side of the screen. The background of the window will be white with black text and blue links. The title bar of this window will read "Tutorial." The window's toolbar will contain Print, Back, and Forward buttons.

The <links> Element

The <links> element points to one or more link files, which are used to associate multiple targets with link IDs. The <links> element has the following child element:

For example:

  <links>
    <linkref location="linkfile1.xml"/>   
    <linkref location="linkfile2.xml"/>   
  </links>   

The <view> Element

The <view> element specifies how Oracle Help should render navigational "views." A navigational view is a representation of the data in the navigation control files (such as table of contents, index, and search) plus the user interface controls for navigating through them. Oracle Help includes Java classes to render standard types of views. Each type of view is presented on its own tab: by default the Contents tab, the Index tab, and the Search tab.

A helpset can include multiple views of each type. That is, the user interface can display multiple tables-of-contents tabs, index tabs, and so forth. Oracle Help can also merge views of the same type. It does this by merging all views of the same type that have the same label. (See the discussions of the <type> and <label> elements in the following table.) Views with the same type and label are merged as follows:

• Table-of-contents views are appended together.
• Index views are merged in a sorted order.
• Search views are merged in no order. Order is irrelevant, since all search results are sorted by the user interface.

The <view> element can have the following child elements:

In the following example, two table of contents tabs are created, one labeled User's Guide and the other labeled Reference. They both use the XML file format for the table of contents (specified in the <data> element), but they have different values in the <label> element. If both of the labels were the same, the table of contents files, ug_toc.xml and ref_toc.xml, would be combined into a single table of contents, and it would be shown in a single tab.

  <view>
    <label>User's Guide</label>
    <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
    <data engine="oracle.help.engine.XMLTOCEngine">ug_toc.xml</data>
  </view>
  
  <view>
    <label>Reference</label>
    <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
    <data engine="oracle.help.engine.XMLTOCEngine">ref_toc.xml</data>
  </view>
  

In the following example, only one table of contents tab is created, even though the two views use different file formats (XML vs. HHC) and different data engines. That is because the label and the type are the same. One advantage of this feature is that you can merge help systems using the old format with help systems using the new one without compromising the way the tabs are presented.

  <view>
    <label>Table of Contents</label>
    <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
    <data engine="oracle.help.engine.XMLTOCEngine">new_toc.xml</data>
  </view>
  
  <view>
    <label>Table of Contents</label>
    <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
    <data engine="oracle.help.engine.HHCEngine"old_toc.hhc</data>
  </view>
  

The next example shows one view each for a table of contents, an index, and a search. They do not have labels, so Oracle Help creates three tabs with the default labels, Contents, Index, and Search. Each view contains a <title> element with the value "User's Guide." This produces the following results:

• In the Contents tab, all the items from the ug_toc.xml table of contents file will all appear under a single top-level node called "User's Guide."

• When a user selects an item from the keyword list in the Index tab, a list of associated topics is displayed. "User's Guide" will appear as the source for any topic from this helpset. (OHJ and OHW use different means to show the source.)

• When a user performs a search in the Search tab, "User's Guide" will be shown in the list of results as the source for any topics found from this helpset.

This feature is useful when you merge several helpsets. It helps to keep the user oriented by reducing the number of top-level nodes in the table of contents and by showing the sources of topics found when using the index and search.

  <view>
    <title>User's Guide</title>
    <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
    <data engine="oracle.help.engine.XMLTOCEngine">ug_toc.xml</data>
  </view>

  <view>
    <title>User's Guide</title>
    <type>oracle.help.navigator.keywordNavigator.KeywordNavigator</type>
    <data engine="oracle.help.engine.XMLIndexEngine">ugindex.xml</data>
  </view>
  
  
  <view>
    <title>User's Guide</title>
    <type>oracle.help.navigator.searchNavigator.SearchNavigator</type>
    <data engine="oracle.help.engine.SearchEngine">search.idx</data>
  </view>

The <subhelpset> Element

The <subhelpset> element is used to include other helpsets with the one defined in this helpset file. The views from combined subhelpsets are merged in the same way mutlitple views are merged in a single helpset. That is, subhelpset views with the same <type> and <label> are merged. See <view>, above, for more information

The <subhelpset> element supports the following attributes:

location - Specifies the URL of the helpset to be merged.

class - [optional] A class whose location is the base location for the subhelpset file. Any path information in the location attribute is relative to this base location.

Sample Helpset File

The following listing shows a sample helpset with all of the sections discussed above, including five views: two tables of contents, two keyword indexes, and a text search.

  <?xml version='1.0'?>
  <helpset version="1.1">
  
  <maps>
    <mapref location="topics.xml"/>
  </maps>
  
  <wintype>
    <name>Tutorial</name>
    <height>50%</height>
    <width>200</width>
    <x>10</x>
    <y>10</y>
    <title>Tutorial</title>
    <toolbar>06004</toolbar>
  </wintype>
       
  <links>
    <linkref location="linkfile1.xml"/>
    <linkref location="linkfile2.xml"/>
  </links>
  
  <view>
    <label image="tocgif">Table of Contents</label>
    <title image="uggif">Forms User's Guide</title>
    <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
    <data engine="oracle.help.engine.XMLTOCEngine">ugcontents.xml</data>
  </view>
  
  <view>
    <label>Keyword Index</label>
    <type>oracle.help.navigator.keywordNavigator.KeywordNavigator</type>
    <data engine="oracle.help.engine.XMLIndexEngine">ugindex.xml</data>
  </view>
  
  <view>
    <label image="tocgif">Table of Contents</label>
    <title image="dggif">Forms Developer's Guide</title>
    <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
    <data engine="oracle.help.engine.HHCEngine"
      class="oracle.forms.documentation.dev">
      dgcontents.hhc   
    </data>
  </view>
  
  <view>
    <label>Keyword Index</label>
    <type>oracle.help.navigator.keywordNavigator.KeywordNavigator</type>
    <data engine="oracle.help.engine.HHKEngine"  
      class="oracle.forms.documentation.dev">
      dgindex.hhk</data>
  </view>
  
  <view>
    <label>Search</label>
    <title>Forms Documentation</title>
    <type>oracle.help.navigator.searchNavigator.SearchNavigator</type>
    <data engine="oracle.help.engine.SearchEngine"  
      class="oracle.forms.documentation.dev">
      search.idx</data>
  </view>
  
  <subhelpset location="prodsup.hs"/>
  <subhelpset location="advanced.hs"/>
  </helpset>

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