This chapter describes the metadata files (helpset and map files) used by OHJ and OHW.
This chapter includes the following sections:
Metadata files provide information about the structure and operation of the help system. Metadata files can be categorized into two types, Helpset files and Map files. Both files are XML files.
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:
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 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.
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 6-1 <maps> Child Elements
| Element | Description |
|---|---|
|
|
The location of a map file for this book. When multiple map files are specified, they are merged. Each
|
|
|
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
The |
For example:
<maps> <mapref location="main_map.xml"/> <mapref location="tutorial/tut_map.xml"/> </maps>
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.2, "OHJ Topic Windows".
Note:
OHW-UIX and OHW-RC do 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 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:
Table 6-2 <wintype> Child Elements
| Element | Description |
|---|---|
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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 will override this value. |
|
|
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 will override this value. |
|
|
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 will override this value. |
|
|
Text that appears in the title bar of the window. |
|
|
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:
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 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.
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.5, "Link File".
The <links> element has the following child element:
Table 6-3 <links> Child Elements
| Element | Description |
|---|---|
|
< |
The location of a map file for this book. When multiple map files are specified, they are merged. Each
|
For example:
<links> <linkref location="linkfile1.xml"/> <linkref location="linkfile2.xml"/> </links>
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 6-4 <view> Child Elements
| Element | Description |
|---|---|
|
|
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
|
|
|
A title for the view. This title appears in different places in the different navigational views:
The title tag supports the following attribute:
|
|
|
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. |
|
|
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
|
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>
The following tables lists valid engine values for each view type:
Table 6-5 View Type: oracle.help.navigator.tocNavigator.TOCNavigator
| Engine | Description |
|---|---|
|
|
Oracle Help XML table of contents (extension of JavaHelp TOC) |
|
|
Microsoft HTMLHelp 1.x table of contents |
|
|
Table of contents from previous versions of OHJ |
Table 6-6 View Type: oracle.help.navigator.keywordNavigator.KeywordNavigator
| Engine | Description |
|---|---|
|
|
Oracle Help XML keyword index (extension of JavaHelp keyword index) |
|
|
Microsoft HTMLHelp keyword index. |
|
|
Keyword index from previous versions of OHJ |
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.2.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.
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>
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. These image IDs can be used 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.
The following table describes the elements used in the map file:
| Element | Description |
|---|---|
|
|
Defines the mappings. The |
|
|
An ID and its associations. The
|
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.