The HelpSet File

Helpset File

When the JavaHelp system is activated by your application, the first thing it does is read the helpset file specified by the application. The helpset file defines the helpset for that application. A helpset is the set of data that comprises your help system. The helpset file includes the following information:

Map file The map file is used to associate topic IDs with the URL or path name of HTML topic files.

View information Information that describes the navigators being used in the helpset. The standard navigators are: table of contents, index, and full-text search. Additional navigators are the glossary and the favorites navigators. Information about custom navigators is included here as well.

Helpset title The <title> defined in the helpset (.hs) file. This title appears at the top of the main window and any secondary windows defined in your helpset file.

Home ID The name of the (default) ID that is displayed when the help viewer is called without specifying an ID.

Presentation The windows in which to display the help topics. This is a new feature of the JavaHelp 2 software that is described in more detail below under <presentation>.

Sub-helpsets This optional section statically includes other helpsets by using the <subhelpset> tag. The helpsets indicated by this tag are merged automatically into the helpset that contains the tag. More details about merging can be found in Merging Helpsets.

Implementation This optional section creates a registry that provides key data mapping to define the HelpBroker class to use in the HelpSet.createHelpBroker method. The registry also determines the content viewer to user for a given MIME type. See <impl> below.

After your product is installed on your user's system, your Java program must be able to find the helpset file. The application specifies the path to the helpset file when it starts the JavaHelp system. By convention, the name of the helpset file ends with the .hs extension.

Helpset File Format

The format of the helpset file is based on the World Wide Web Consortium Extended Markup Language (XML 1.0) proposed recommendation:

http://www.w3.org/TR/PR-xml-971208

The following is an example of a helpset file (description follows):

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN"
         "http://java.sun.com/products/javahelp/helpset_2_0.dtd">
<helpset version="2.0">
   <!-- title --> 
   <title>Java Development Environment - Help</title>
			
   <!-- maps --> 
   <maps>
     <homeID>top </homeID>
     <mapref location="Map.jhm" />
   </maps>
	
   <!-- views --> 
   <view xml:lang="en" mergetype="javax.help.UniteAppendMerge">
      <name>TOC</name>
      <label>Table Of Contents</label>
      <type>javax.help.TOCView</type>
      <data>IdeHelpTOC.xml</data>
   </view>
	
   <view xml:lang="en" mergetype="javax.help.SortMerge">
      <name>Index</name>
      <label>Index</label>
      <type>javax.help.IndexView</type>
      <data>IdeHelpIndex.xml</data>
   </view>
	
   <view xml:lang="en">
      <name>Search</name>
      <label>Search</label>
      <type>javax.help.SearchView</type>
         <data engine="com.sun.java.help.search.DefaultSearchEngine">
         JavaHelpSearch
         </data>
   </view>

   <!-- A glossary navigator -->
   <view  mergetype="javax.help.SortMerge">
      <name>glossary</name>
      <label>Glossary</label>
      <type>javax.help.GlossaryView</type>
      <data>glossary.xml</data>
   </view>

   <!-- A favorites navigator -->
   <view>
      <name>favorites</name>
      <label>Favorites</label>
      <type>javax.help.FavoritesView</type>
   </view>

   <!-- presentation windows -->

   <!-- This window is the default one for the helpset. 
     *  Its title bar says "Project X Help". It
     *  is a tri-paned window because displayviews, not
     *  defined, defaults to true and because a toolbar is defined.
     *  The toolbar has a back arrow, a forward arrow, and
     *  a home button that has a user-defined image.
   -->
   <presentation default=true>
       <name>main window</name>
       <size width="400" height="400" /> 
       <location x="200" y="200" />
       <title>Project X Help</title>
       <toolbar>
           <helpaction>javax.help.BackAction</helpaction>
           <helpaction>javax.help.ForwardAction</helpaction>
           <helpaction image="homeicon">javax.help.HomeAction</helpaction>
       </toolbar>
   </presentation>

   <!-- This window is simpler than the main window. 
     *  It's intended to be used a secondary window.
     *  It has no navigation pane or toolbar.
   -->
   <presentation displayviews=false>
       <name>secondary window</name>
       <size width="200" height="200" /> 
       <location x="200" y="200" />
   </presentation>
 
   <!-- subhelpsets --> 
   <subhelpset location="file:/c:/Foobar/HelpSet2.hs" />

   <!-- implementation section -->
   <impl>
      <helpsetregistry helpbrokerclass="javax.help.DefaultHelpBroker" />
      <viewerregistry viewertype="text/html" 
         viewerclass="com.sun.java.help.impl.CustomKit />
      <viewerregistry viewertype="text/xml" 
         viewerclass="com.sun.java.help.impl.CustomXMLKit />
   </impl>
</helpset>

The Helpset Tags

The following table describes the helpset tags:

<helpset> Defines the helpset. It can contain all the following tags.

blue bullet <title> Names the helpset. This string can be accessed by the application and used in the presentation (for example, in the viewer header stripe).

<maps> Specifies the default topic and URL of the map file used in the helpset.

<maps> Tags

<homeID>
Specifies the name of the (default) ID that is displayed when the help viewer is called if an ID is not explicitly specified.

<mapref>
Specifies the URL of the map file relative to the helpset.

blue bullet <view> Defines the navigators used in the helpset. Each navigator is defined by its own <view>.

<view> Attributes

xml:lang="lang"
Language for the view. Use the standard locale-country-variant format. Some examples:

xml:lang="de"

xml:lang="en"

xml:lang="en-US"

mergetype="class"
Specifies the path to the merge class. The merge classes are:

javax.help.UniteAppendMerge

javax.help.SortMerge

javax.help.AppendMerge

javax.help.NoMerge

For more information, see Merging Helpsets.

<view> Tags

<name>
Names the view.

<label>
Specifies a label associated with the view. This string is displayed in the navigator's tab if the presentation's displayviewimages attribute is "false".

<type>
Specifies the path to the navigator class.

<data>

Specifies the path to the data used by the navigator. When used with the search navigator, this tag contains the following attribute:

engine    A String indicating the path to the search engine class.

<image>
Specifies the image displayed for the navigator in the tab bar at the top of the navigator pane. The argument to this attribute is an ID defined in the map file. The ID must be associated with a GIF or JPEG file. If this attribute is not specified, the default navigator image is displayed.

blue bullet <presentation> Defines the windows used in the helpset. Each window is defined by its own <presentation> tag. See the helpset example above for sample code for this tag and its attributes.

<presentation> Attributes

xml:lang="lang"
Language for the view. Use the standard locale-country-variant format. Some examples:

xml:lang="de"

xml:lang="en"

xml:lang="en-US"

default="true|false"
This presentation is the default one for this helpset. The default value of this attribute is "false". (In other words, if you do not specify this attribute, the presentation is not the default one.)

If more than one presentation is specified as default, the last one specified is the default presentation.

displayviews="true|false"
Show the navigational views of this helpset in a pane on the left side of the window (like the tri-paned viewer). The default value is "true".

displayviewimages="true|false"

The default value "true" displays the image for each navigator in the navigator's tab. If set to "false", the text defined in each view's <label> tag is displayed instead.

<presentation> Tags

<name>
Names the window, allowing it to be called by name from the Java program or from the TOC. If you define a presentation, be sure to tell the Java programmer its name and when you expect it to be called from the program.

<size>
Specifies the size of the window with the following attributes:
width="nnn"   Width in pixels.
height="nnn"  Height in pixels.

<location>
Specifies the position of the window with the following attributes:
x="nnn"  Horizontal (x) coordinate.
y="nnn"  Vertical (y) coordinate.

<title>
Specifies the text that appears in the title bar at the top of the window.

<image>

Specifies the image displayed on the left side of the help window's title bar. The argument to this attribute is an ID defined in the map file. The ID must be associated with a GIF or JPEG file. If this attribute is not specified, the default JavaHelp image is displayed.

<toolbar>
Indicates that the window is to have a toolbar.

You define buttons on the toolbar by using a <helpaction> tag for each button and a Java class name for the action.

<helpaction> javax.help.HelpAction
</helpaction>

HelpAction is any of the following default class names, each of which defines an action and a button image:

BackAction

Goes to previous topic.

FavoritesAction

Adds current map ID (currently displayed topic) to Favorites navigator.

ForwardAction

Goes to next topic.

HomeAction

Loads the home topic in the content pane

PrintAction

Prints the topics selected in the navigator.

PrintSetupAction

Runs print setup before printing.

ReloadAction

Reloads the current topic page in the content viewer.

SeparatorAction

Creates a separator between action buttons.

Each action button has a default button image. If you want to use a different image, you must define a map ID for the image file in the map file and reference the map ID inside the <helpaction> tag by using the image attribute.

<helpaction> Attribute

image="mapID"

For example:

<helpaction image="images_backbutton"> javax.help.BackAction </helpaction>

blue bullet <subhelpset> This optional tag can be used to specify helpsets you want merged with the helpset that contains the tag. See Merging Helpsets for more information. Contains the following attribute:

location     URL of the helpset file to be merged.

blue bullet <impl>
The implementation section creates a registry that provides key data mapping to define the HelpBroker class to use in the HelpSet.createHelpBroker method. The registry also determines the content viewer to user for a given MIME type.

<impl> Tags

<helpsetregistry>
Registers the default HelpBroker class. Uses the following attribute:
helpbrokerclass="class" - Required. Name of a class that implements HelpBroker.

<viewregistry>
Registers a viewer class for a given MIME type. Uses the following attributes:
viewertype="mine/type" - Required. MIME type.
viewerclass="class" - Required. Class name.

see-also pointer See also:

Map File

Table of Contents File

Index File

Glossary File

Favorites File

Creating the Full-Text Search Database

Map file	The map file is used to associate topic IDs with the URL or path name of HTML topic files.
View information	Information that describes the navigators being used in the helpset. The standard navigators are: table of contents, index, and full-text search. Additional navigators are the glossary and the favorites navigators. Information about custom navigators is included here as well.
Helpset title	The `<title>` defined in the helpset (`.hs`) file. This title appears at the top of the main window and any secondary windows defined in your helpset file.
Home ID	The name of the (default) ID that is displayed when the help viewer is called without specifying an ID.
Presentation	The windows in which to display the help topics. This is a new feature of the JavaHelp 2 software that is described in more detail below under `<presentation>`.
Sub-helpsets	This optional section statically includes other helpsets by using the `<subhelpset>` tag. The helpsets indicated by this tag are merged automatically into the helpset that contains the tag. More details about merging can be found in Merging Helpsets.
Implementation	This optional section creates a registry that provides key data mapping to define the HelpBroker class to use in the `HelpSet.createHelpBroker` method. The registry also determines the content viewer to user for a given MIME type. See `<impl>` below.

`<helpset>`		Defines the helpset. It can contain all the following tags.
	`<title>`	Names the helpset. This string can be accessed by the application and used in the presentation (for example, in the viewer header stripe).
	`<maps>`	Specifies the default topic and URL of the map file used in the helpset. `<maps>` Tags `<homeID>` Specifies the name of the (default) ID that is displayed when the help viewer is called if an ID is not explicitly specified. `<mapref>` Specifies the URL of the map file relative to the helpset.
	`<view>`	Defines the navigators used in the helpset. Each navigator is defined by its own <view>. <view> Attributes `xml:lang="`lang`"` Language for the view. Use the standard locale-country-variant format. Some examples: `xml:lang="de"` `xml:lang="en"` `xml:lang="en-US"` `mergetype`="class" Specifies the path to the merge class. The merge classes are: `javax.help.UniteAppendMerge` `javax.help.SortMerge` `javax.help.AppendMerge` `javax.help.NoMerge` For more information, see Merging Helpsets. <view> Tags `<name>` Names the view. `<label>` Specifies a label associated with the view. This string is displayed in the navigator's tab if the presentation's `displayviewimages` attribute is `"false"`. `<type>` Specifies the path to the navigator class. `<data>` Specifies the path to the data used by the navigator. When used with the search navigator, this tag contains the following attribute: `engine` A `String` indicating the path to the search engine class. `<image>` Specifies the image displayed for the navigator in the tab bar at the top of the navigator pane. The argument to this attribute is an ID defined in the map file. The ID must be associated with a GIF or JPEG file. If this attribute is not specified, the default navigator image is displayed.
	`<presentation>`	Defines the windows used in the helpset. Each window is defined by its own `<presentation>` tag. See the helpset example above for sample code for this tag and its attributes. `<presentation>` Attributes `xml:lang="`lang`"` Language for the view. Use the standard locale-country-variant format. Some examples: `xml:lang="de"` `xml:lang="en"` `xml:lang="en-US"` `default="true\|false"` This presentation is the default one for this helpset. The default value of this attribute is "`false`". (In other words, if you do not specify this attribute, the presentation is not the default one.) If more than one presentation is specified as `default`, the last one specified is the default presentation. `displayviews="true\|false"` Show the navigational views of this helpset in a pane on the left side of the window (like the tri-paned viewer). The default value is "`true`". `displayviewimages="true\|false"` The default value "`true`" displays the image for each navigator in the navigator's tab. If set to "`false`", the text defined in each view's `<label>` tag is displayed instead. `<presentation>` Tags `<name>` Names the window, allowing it to be called by name from the Java program or from the TOC. If you define a presentation, be sure to tell the Java programmer its name and when you expect it to be called from the program. `<size>` Specifies the size of the window with the following attributes: `width="nnn"` Width in pixels. `height="nnn"` Height in pixels. `<location>` Specifies the position of the window with the following attributes: `x="nnn"` Horizontal (x) coordinate. `y="nnn"` Vertical (y) coordinate. `<title>` Specifies the text that appears in the title bar at the top of the window. `<image>` Specifies the image displayed on the left side of the help window's title bar. The argument to this attribute is an ID defined in the map file. The ID must be associated with a GIF or JPEG file. If this attribute is not specified, the default JavaHelp image is displayed. `<toolbar>` Indicates that the window is to have a toolbar. You define buttons on the toolbar by using a `<helpaction>` tag for each button and a Java class name for the action. `<helpaction> javax.help.`HelpAction `</helpaction>` HelpAction is any of the following default class names, each of which defines an action and a button image: `BackAction` Goes to previous topic. `FavoritesAction` Adds current map ID (currently displayed topic) to Favorites navigator. `ForwardAction` Goes to next topic. `HomeAction` Loads the home topic in the content pane `PrintAction` Prints the topics selected in the navigator. `PrintSetupAction` Runs print setup before printing. `ReloadAction` Reloads the current topic page in the content viewer. `SeparatorAction` Creates a separator between action buttons. Each action button has a default button image. If you want to use a different image, you must define a map ID for the image file in the map file and reference the map ID inside the `<helpaction>` tag by using the `image` attribute. `<helpaction>` Attribute `image="`mapID`"` For example: `<helpaction image="images_backbutton"> javax.help.BackAction </helpaction>`
	`<subhelpset>`	This optional tag can be used to specify helpsets you want merged with the helpset that contains the tag. See Merging Helpsets for more information. Contains the following attribute: `location` URL of the helpset file to be merged.
	`<impl>`	The implementation section creates a registry that provides key data mapping to define the HelpBroker class to use in the `HelpSet.createHelpBroker` method. The registry also determines the content viewer to user for a given MIME type. `<impl>` Tags `<helpsetregistry>` Registers the default `HelpBroker` class. Uses the following attribute: `helpbrokerclass="class"` - Required. Name of a class that implements `HelpBroker`. `<viewregistry>` Registers a viewer class for a given MIME type. Uses the following attributes: `viewertype="mine/type"` - Required. MIME type. `viewerclass="class"` - Required. Class name.