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

6 Help Information Files

Help information files contain information about the content of the help system. The information includes:

6.1 Table of Contents File

The Table of Contents (TOC) file is an XML file that describes the content and layout of the table of contents, and it is typically rendered as the Contents tab. Note that each helpset jar file must have one Table of Contents file.

If a helpset jar file contains several child helpsets, use the master Table of Contents file to control the content and layout of parent helpset's table of contents.

6.1.1 TOC Elements

Table 6-1 describes the elements used in the table of contents file:

Table 6-1 TOC File Elements

Element Description

<toc>

Defines the table of contents. This element contains <tocitem> elements. The <toc> element supports the following attribute:

  • version - The version of the table of contents file format specification. The version documented here is 1.0.

<tocitem>

Defines a table of contents entry. A <tocitem> element can contain other <tocitem> elements to create a hierarchy of topics. Nesting "tocitem_1" within "tocitem_2" defines "tocitem_1" to be hierarchically contained within "tocitem_2." The <tocitem> element supports the following attributes:

  • target - The topic ID of the topic to display when this item is selected by a user. Topic IDs are maintained in the map file. A parent node (that is, an item that contains others beneath it in the hierarchy) may or may not include a target. If it does not have a target, selecting that node displays its child items and nodes.

  • text - The text displayed in the table of contents for this item.

  • image - An image to display next to this item. The value of this attribute is an image ID specified in the map file.


The following example shows a short table of contents file:

<?xml version='1.0'?>
  <toc version="1.0">
  <tocitem text="Introduction to My Product" image="prodIcon">
    <tocitem target="aboutmyp" text="About My Product" />
    <tocitem target="architec" text="My Product Architecture" />
    <tocitem target="feature1" text="About Feature One" />
    <tocitem target="feature2" text="About Feature Two" />
    <tocitem target="feature3" text="About Feature Three" />
    <tocitem text="Learning My product">
      <tocitem target="qtour" text="Quick Tour" />
      <tocitem target="docguide" text="Guide to Documentation" />
    </tocitem>
  </tocitem>
  <tocitem text="Step-by-step Procedures" image="prodIcon">
    <tocitem text="Basic Tasks">
      <tocitem target="task1" text="To..." />
      <tocitem target="task2" text="To..." />
      <tocitem target="task3" text="To..." />
    </tocitem>
    <tocitem text="Working with ...">
      <tocitem target="task4" text="To..." />
      <tocitem target="task5" text="To..." />
    </tocitem>
  </tocitem>
  </toc>

This definition produces the following TOC hierarchy:

  • Introduction to My Product

    • About My Product

    • My Product Architecture

    • About Feature One

    • About Feature Two

    • About Feature Three

    • Learning My Product

      • Quick Tour

      • Guide to Documentation

  • Step-by-step Procedures

    • Basic Tasks

      • To...

      • To...

      • To...

    • Working with ...

      • To ...

      • To ...

6.2 Master Table of Contents

A master table of contents file controls the TOC structure of all child helpsets, and manages other table of contents files. You must declare the master table of contents before declaring helpset files.

6.2.1 How To Configure Master Table of Contents

To use a master table of contents, you must first configure the Oracle Help for the Web configuration file.

  1. Declare master table of contents helpset file in the Oracle Help for the Web configuration file.

    The following example shows a code extract from the configuration file:

    <books>
      <helpSet id="master" location="master/src/helpset/master.hs"/>
      <helpSet id="ohguide" location="ohguide/src/helpset/ohguide.hs"/>
      <helpSet id="blafdoc" location="blafdoc/src/helpset/blafdoc.hs"/>
      <helpSet id="shake" location="shakespeare/src/helpset/shakespeare.hs"/>
    </books>
    

    In the above example, the following code declares a master table of contents helpset file:

    <helpSet id="master" location="master/src/helpset/master.hs"/>

    Note that the master table of contents helpset file must be declared first before any other helpset files.

  2. Create a master helpset file.

    The entry for master table of contents helpset looks similar to any other TOC entry, as shown in the following code extract example of master.hs file.

    <view>
        <type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
        <data engine="oracle.help.engine.XMLTOCEngine">toc.xml</data>
      </view>
    
  3. Create a master table of contents XML file that defines the structure of all table of contents.

    This master table of contents XML file looks similar to any other toc.xml file, but it contains <tocfile> elements. The <tocfile> elements define the location of child table of contents XML files, as shown in the following example.

    <toc version="1.0">
      <tocitem text="Root">
        <tocitem text="Some random node">
          <tocfile location="ohguide/toc.xml" />
          <tocfile location="javadoc/toc.xml" />
        </tocitem>
        <tocfile location="blafdoc/toc.xml;shakespeare/shakespeare.hhc" />
      </tocitem>
      <!-- All helpset toc files not explicitly declared in this file will be
           inserted under the following node. This includes toc files that are
           located in a subhelpset. -->
      <tocitem text="Extension Help Content">
        <tocfile location="*" />
      </tocitem>
    </toc>
    

    Note that the master table of contents file controls the structure of the content, you must define your content through helpset files.

6.3 Index File

The index file is an XML file that describes the content and layout of the index. It is typically rendered as the Index tab.

6.3.1 Index Elements

Table 6-2 describes the elements used in the index file.

Table 6-2 Index File Elements

Element Description

<index>

Defines the index. It can contain <indexitem> and <indexentry> tags.

<indexitem>

Defines an index item that appears in the keyword list. Nesting index_item_1 within index_item_2 defines index_item_1 to be hierarchically contained within index_item_2, listed and indented below index_item_2 in the index. Oracle Help currently supports only two levels of keywords. The index view collapses any nesting beyond two levels.

If an index item has multiple topics associated with it, the topics should be listed as index entries defined in <indexentry> elements.

The <indexitem> element has the following attribute:

  • target - The topic ID (defined in the map file) of the topic to display when the entry is chosen by the user.

<indexentry>

Defines an index entry displayed in the topics list when the parent index item is selected in the index list. This tag uses the following attribute:

  • target - The topic ID (defined in the map file) of the topic to display when the entry is chosen by the user.


This example defines a very short index file:

<?xml version='1.0' ?>
  <index version="1.0">
  
  <indexitem target="Add_Icon"
      text="Add Icon Command">
    <indexitem target="addtosheet"
        text="Adding an icon to a sheet />
    <indexitem target="addtoworkbook"
        text="Adding an icon to a workbook" />   
  </indexitem>
  
  <indexitem target="Sheet_Background"
       text="Adding a background to a sheet" />
 
  <indexitem text="Adding a new sheet to a workbook">
    <indexentry target="New_Sheet_command"
        text="New Sheet Command />
    <indexentry target="Add_new_sheet"
        text="To add a new sheet to a workbook" />
  </indexitem>
  
  <indexitem target="Add_item_to_sheet"
      text="Adding an item to a sheet" />
  </index>

The file in the example above produces this index list:

Add Icon Command
    Adding an icon to a sheet
    Adding an icon to a workbook
  Adding a background to a sheet
  Adding a new sheet to a workbook
  Adding an item to a sheet

If a user selects Adding a new sheet to a workbook from that list, a list of the following topics is displayed:

New Sheet Command
  To add a new sheet to a workbook

This topic list appears at the bottom of the index pane, as opposed to indented topics, Adding an icon to a sheet and Adding an icon to a workbook, which appears in the keyword list at the top of the index pane.

Selecting a keyword that does not have index entries but has a directly associated target (for example, Adding an item to a sheet) displays the same text in the topics list as it does in the keyword list. Because of the way Oracle Help displays the index, it is a better practice never to use targets in the <indexitem> tags. Instead, always use the <indexentry> tags to specify topics associated with an <indexitem> -- even when there's only one target for a keyword.

In other words, the following code:

<indexitem text="sheet backgrounds">
    <indexentry target="Sheet_Background" text="adding a background to a sheet" />
</indexitem>

...is better than the following code:

<indexitem target="Sheet_Background" text="adding a background to a sheet" />

6.4 Search Index File

The search index file is used when a user performs a text search in Oracle Help, ordinarily from the Search tab. This file uses a proprietary binary format. Any third-party help authoring tool that supports Oracle Help should be able to generate this file. In addition, the OHJDK includes two utilities that generate a search index file:

6.5 Link File

The link file is an XML file that defines link IDs and associates them with multiple topic IDs (which are defined in the map file). A link ID, or a link keyword, can be used with the alink protocol in a topic file to display a list of links to the topics associated with the ID. In other words, associative links make it possible to associate an HTML link with multiple targets. The user can then choose which target to follow.

6.5.1 Link File Elements

Table 6-3 describes the elements used in the link file:

Table 6-3 Link File Elements

Element Description

<link>

Defines the link file. The <link> element can contain only <linkitem> elements and their child <linkentry> elements.

<linkitem>

Defines the associative link. The <linkitem> element can only include <linkentry> elements. It has the following required attribute:

  • topicid – Defines the link ID.

<linkentry>

Defines an entry in the list of links displayed when an associative link is clicked. This element supports the following attributes:

  • target – Specifies the topic ID (defined in the map file) of the topic to display when the entry is chosen by the user.

  • text – The text displayed in the link list


The following example defines two associative links:

<?xml version='1.0' ?>
  <link version="1.0">
  
  <linkitem topic="dog_links">
    <linkentry target="about_dogs" text="About Dogs" />
    <linkentry target="dog_species" text="A List of Dog Species" />
    <linkentry target="dog_stories" text="Dog Stories" />
    <linkentry target="dog_lore" text="Dog Lore" />
  </linkitem>
  
  <linkitem topic="cat_links">
    <linkentry target="about_cats" text="About Cats" />
    <linkentry target="cat_species" text="A List of Cat Species" />
    <linkentry target="cat_stories" text="Cat Stories" />
  </linkitem>
  </link>

Using the first link ID from that example, you could define a link <a href="alink:dog_links">dogs</a>. When a user selected the dogs link, the following list of links would be displayed:


About Dogs
A List of Dog Species
Dog Stories
Dog Lore

Clicking About Dogs would display the topic mapped to the about_dogs ID in the map file.