Favorites Navigator and File

Favorites are links to helpset topics that the user wants to save and reuse. The favorites file describes the content and layout of these links in the favorites navigator. Unlike other navigational views that store the view's metadata in the helpset directories, favorites are stored in the user's directory in the file userdir/.JavaHelp/Favorites.xml.

The favorites file format is based on the World Wide Web Consortium Extended Markup Language (XML). The DTD for this syntax is dtd/favorites_2_0.dtd. The top level tag is <favorites>. A version attribute is optional. When present, its value must be "2.0".

The JavaHelp system specifies one favorites navigator view: javax.help.FavoritesView. Favorites do not require a data definition as part of the navigator view definition. Also, the mergetype tag is ignored.

The following XML code shows a sample definition of a favorites navigator in the view section of a helpset file:

   <view>
      <name>Favorites</name>
      <label>Favorites</label>
      <type>javax.help.FavoritesView</type>
   </view>

The following figure shows how the Favorites navigator looks in the helpset for the JavaHelp System Users Guide. As the figure shows, when you add a Favorites navigator to a helpset, the JavaHelp system also adds a Favorites button to the default toolbar. Clicking the Favorites button enables the user to add the currently displayed help topic to the list of favorites in the navigator.

If you have defined your own windows (presentations) in the helpset file, the favorites button is not added automatically. To display a favorites button on the presentation's toolbar, you must add the following help action to the <presentation> tag's <toolbar> tag: <helpaction>javax.help.FavoritesAction</helpaction> For more information, see the toolbar tag description in the Helpset File section.

The following XML code is an example of a favorites file, which is created for you by the JavaHelp system:

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE favorites
       PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Favorites Version 2.0//EN"
       "http://java.sun.com/products/javahelp/favorites_2_0.dtd">
   <favorites version="2.0">
     <favoriteitem text="Love Holidays" >
        <favoriteitem text="On Love" target="onlove" hstitle="History of the Holidays"/>
        <favoriteitem text="Valentines" target="valentine" hstitle="History of the Holidays"/>
     </favoriteitem>
     <favoriteitem text="Numbers" >
         <favoriteitem text="Zero" target="0" hstitle="Master"/>
         <favoriteitem text="Zero - note " 
                     url="file:/usr/test/hs/Zeronote.html"
                     hstitle="Master"/>
     </favoriteitem>

The Favorites Tags

The following table describes the favorites tags:

<favorites>

Defines the user favorites list. It contains <favoriteitem> tags and the following optional attributes. xml:lang="lang" Language for the favorites list. Use the standard locale-country-variant format. Some examples: xml:lang="de" xml:lang="en" xml:lang="en-US" version="2.0" Version of JavaHelp software. .

<favoriteitem>

Defines a favorites link. You can nest favorites links to create hierarchies of favorites. Uses the following attributes: xml:lang="lang" (optional) Language for the favorites link. Use the standard locale-country-variant format. Some examples: xml:lang="de" xml:lang="en" xml:lang="en-US" text="string" Specifies the text that displays in the list. target="string" (optional) Specifies the map ID of the topic that displays when the link is chosen by the user. IDs are defined (associated with a URL) in the map file. url="string" (optional) Specifies the URL of the topic that displays when the link is chosen by the user. IDs are defined (associated with a URL) in the map file. hstitle="string" Specifies the title of the helpset. image="string" (optional) Specifies the image displayed before a favorites link. The argument to this attribute is a mapID defined (associated with a GIF or JPEG image) in the map file. If this attribute is not specified, the default images are displayed. presentationtype (optional) Specifies the type of window in which the favorite topic will be displayed (defined in the <presentation> section of the Hs file). For more information, see the presentation feature in Helpset File. presentationname (optional) Specifies the name of the window in which the favorites topic will be displayed.

See also:

The Helpset File

Map File

JAR Files

Table of Contents File

Index File

Glossary File

Creating the Full-Text Search Database