Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Help
11g Release 2 (11.1.2.0.0)

Part Number E16280-01
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Metadata Files

Metadata files provide information about the structure and operation of the help system:

5.1 Helpset File

The helpset file is an XML file with .hs extension 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.

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

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

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

5.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:

Table 5-1 <maps> Child Elements

Element Description

<mapref>

The location of a map file for this book. When multiple map files are specified, they are merged. Each <mapref> item is searched in order and a merged map is constructed. The <mapref> element has the following attributes:

  • location – The URL of the map file relative to the helpset.

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

<homeID>

The ID (defined in the map file) of a topic that is used in some cases as the default topic for the helpset. That is, if no topic is specified when OHJ is launched, this topic is displayed by default. The <homeID> element is functional only in the following OHJ implementations:

  • OHJ Documentation Viewer (installed with OHJ).

  • When OHJ is implemented so that the navigator window and the topic window are docked by default.

The <homeID> element is not used in OHW.


For example:

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

5.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".

Note:

OHW does not recognize <wintype> 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 is not used unless 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:

Table 5-2 <wintype> Child Elements

Element Description

<name>

The name of this window type. This name is used to associate topics with the window type. If multiple windows are defined in a helpset, they must have unique names.

<height>

The height of the window. A numeric value indicates a distance in pixels. A numeric value followed by a percent sign (%) indicates a percentage of the visible screen.

<width>

The width of the window in pixels. A numeric value indicates a distance in pixels. A numeric value followed by a percent sign (%) indicates a percentage of the visible screen.

<x>

The horizontal position of the window. A numeric value indicates a distance in pixels. A negative value indicates distance between the right edge of the window and the right edge of the screen. A numeric value followed by a percent sign (%) indicates a percentage of the visible screen.

<y>

The vertical position of the window in pixels. A numeric value indicates a distance in pixels. A negative value indicates distance between the bottom edge of the window and the bottom of the screen. A numeric value followed by a percent sign (%) indicates a percentage of the visible screen.

<textfg>

The six-digit hexadecimal RGB value of the foreground color of the text in the window. A preceding # on the value may be present, but is ignored. For any single topic, a foreground color specified in the HTML topic file or CSS overrides this value.

<linkfg>

The six -digit hexadecimal RGB value of the foreground color of the links in the window. A preceding # on the value may be present but is ignored. For any single topic, a link color specified in the HTML topic file or CSS overrides this value.

<bg>

The six -digit hexadecimal RGB value of the background color of the window. A preceding # on the value may be present but is ignored. For any single topic, a background color specified in the HTML topic file or CSS overrides this value.

<title>

Text that appears in the title bar of the window.

<toolbar>

Defines the buttons to display in the window's toolbar. A five-digit hexadecimal value which is the sum of one or more of the following:

  • 00004 – Turns off the default buttons on the toolbar.

  • 00040 – Adds a URL address field to display the current URL.

  • 00400 – Add the Navigator button.

  • 02000 – Add the Print button

  • 04000 – Add the Back and Forward buttons.

  • 08000 – Add the Search button.

  • 10000 – Add the Dock/Undock buttons

A preceding # on the value may be present, but it is ignored.


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

  • a window type called Tutorial with a default height that is 50% of the screen height and a default width of 200 pixels

  • window is displayed 10 pixels from the top and left side of the screen

  • window background is white, with black text and blue links

  • window title bar reads Tutorial

  • window toolbar contains the Print, Back, and Forward buttons

5.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 6.5, "Link File".

The <links> element has the following child element:

Table 5-3 <links> Child Elements

Element Description

<linkref>

The location of a map file for this book. When multiple map files are specified, they are merged. Each <linkref> item is searched in order and a merged link database is constructed. <linkref> has the following attributes:

  • location – The URL of the link file relative to the helpset.

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


For example:

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

5.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:

Table 5-4 <view> Child Elements

Element Description

<label>

The label displayed on the navigator tab in the user interface. This label is optional. If no label is provided, Oracle Help uses Contents, Index, and Search for the appropriate tabs. The <label> element supports the following attribute:

  • image - [optional] An ID in the map file that is associated with an image file. The image appears next to the label text in the navigator tab.

<title>

A title for the view. This title appears in different places in the different navigational views:

  • In the TOC, the title is displayed as the title of the top-level node. All top-level nodes from the TOC file (or from multiple TOC files, if they are merged) are then placed under this title node. If a title is not provided for a TOC view, then all top-level nodes in the TOC definition appear as top-level nodes in the TOC view.

  • In the search and index views, the title is displayed as the Source location for any topics listed as the result of a search or from choosing an index item. If a title is not provided for a search or index view, the Source location is blank.

The title tag supports the following attribute:

  • image - [optional] An ID in the map file that is associated with an image file. If provided for a table-of-contents view, the image appears next to the text for the top-level node. If provided for an index or search view, the image is ignored.

<type>

The name of the Java class to be used as the user interface for this view. The following types are provided with the default implementation:

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

If JavaHelp types are specified, Oracle Help maps these correctly to Oracle Help types.

<data>

The path to the data used by this view, in other words, to the pertinent navigational control file, such as table-of-contents file, index file, or search file. The contents of this element can be a file name or a URL. The <data> element supports the following attributes:

  • class – [optional] A class whose location is the base location for the data file. Any path information is relative to this base location, including any references to HTML files.

  • engine – The name of the Java class to process the data file. A different engine is required for each of the file types supported by Oracle Help, including Oracle Help's XML formats (based on the JavaHelp formats), the MS HTML Help HHC/HHK file formats, and the TOC/TOK formats supported by earlier versions of OHJ. For more information about supported engines and view type, see Section 5.1.6.1, "Data View Type and Engines".


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 compared to 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 appears as the source for any topic from this helpset.

  • When a user performs a search in the Search tab, User's Guide is 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>

5.1.6.1 Data View Type and Engines

The following tables lists valid engine values for each view type:

Table 5-5 View Type: oracle.help.navigator.tocNavigator.TOCNavigator

Engine Description

oracle.help.engine.XMLTOCEngine (default)

Oracle Help XML table of contents (extension of JavaHelp TOC)

oracle.help.engine.HHCEngine

Microsoft HTMLHelp 1.x table of contents

oracle.help.engine.TOCEngine

Table of contents from previous versions of OHJ


Table 5-6 View Type: oracle.help.navigator.keywordNavigator.KeywordNavigator

Engine Description

oracle.help.engine.XMLIndexEngine (default)

Oracle Help XML keyword index (extension of JavaHelp keyword index)

oracle.help.engine.HHKEngine

Microsoft HTMLHelp keyword index.

oracle.help.engine.TOKEngine

Keyword index from previous versions of OHJ


Table 5-7 View Type: oracle.help.navigator.searchNavigator.SearchNavigator

Engine Description

oracle.help.engine.SearchEngine (default)

Oracle help text search database.


5.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 5.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 are loaded if they are found, and are ignored if they are not found.

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

5.2 Map Files

The map file is an XML file that associates IDs with files. The primary use of the map file is to define topic IDs and associate them with topic files. You can also associate topic IDs (and thereby the topics) with any window types defined in <wintype> elements in the helpset file. These IDs are used in the table of contents files, in index files, and in the API for context-sensitive calls.

The map file can also be used to define image IDs and associate them with image files. You can use these image IDs to display images next to tab labels (specified in <view> elements in the helpset file). They can also be used to display images next to items in the table of contents specified in <tocitem> elements in the table of contents file.

5.2.1 Map File Elements

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

Table 5-8 Map File Elements

Element Description

<map>

Defines the mappings. The <map> element contains only <mapID> elements.

<mapID>

An ID and its associations. The <mapID> element has the following attributes:

  • target – The ID for the associated file. Valid characters are any alphanumeric character or punctuation symbol except the equals sign (=). IDs must be unique across all helpsets in a given help instance. However, you can assign multiple IDs to a single file. For example, you could assign one ID for a topic file to appear in one window type and a different ID for the same topic file to appear in a different window type.

  • url – The location of the file to associate with this ID (target). Relative URLs are resolved against the absolute URL for the map file. You may also specify a section of the file using anchor links.

  • wintype – [optional] The name of a windows type, defined using <wintype> elements in the helpset file. If a windows type is not specified, the topic associated with this ID is displayed in the default window defined in the helpset. The attribute is applicable for OHJ only.


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