6 Metadata Files

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

6.1.2 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 dropdown list of helpsets when Oracle Help is implemented to display a list of merged helpsets, instead of concatenating them.

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

For example:

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

6.1.4 The <wintype> Element

The <wintype> element defines the characteristics of one or more windows that can be used by OHJ to display topics, including size, screen placement, text color, and background color. For more information about how this looks in the OHJ user interface, see Section 2.1, "OHJ Topic Windows".

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 toolbar will contain the Print, Back, and Forward buttons.

6.1.5 The <links> Element

The <links> element points to one or more link files, which are used to associate multiple targets with link IDs. For more information about links, see Section 7.4, "Link File".

The <links> element has the following child element:

For example:

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

6.1.6 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 TOC, 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 accordian panel: by default, the Contents, Index, and Search panels.

A helpset can include multiple views of each type. That is, the user interface can display multiple TOC 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. Views with the same type and label are merged as follows:

• TOC 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:

oracle.help.navigator.tocNavigator.TOCNavigator
oracle.help.navigator.keywordNavigator.KeywordNavigator
oracle.help.navigator.searchNavigator.SearchNavigator

In the following example, two TOC 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 TOC files, ug_toc.xml and ref_toc.xml, would be combined into a single TOC, 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 code, only one 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, the items from the ug_toc.xml table of contents file 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.

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

6.1.7 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 multiple views are merged in a single helpset. That is, subhelpset views with the same <type> and <label> are merged. For more information, see Section 6.1.6, "The <view> Element".

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.

Oracle Help assumes that subhelpsets may not always be present. For example, a master helpset for a suite of products may have a subhelpset for each product in the suite: product A, product B, and product C. The user might initially install just product A. At a later time, the user might install product C. Subhelpsets aid in this situation, because you can specify subhelpsets that will be loaded if they are found, and will be ignored if they are not found.

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

6.2.1 Map File Elements

The following table describes the elements used in the map file:

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 will be displayed in the window defined by the intro window type. Map ID topic_5.tsk will display File_5.html in the window defined by the task window type. Map ID topic_5.cncpt will display the same topic file (File_5.html) in a different window type (concept). The association between URL and wintype will be 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.