JavaHelp
JavaHelpTM 1.0 - JavaBeans Help data


Copyright 1998-1999 Sun Microsystems

Introduction

There are different types of help information associated with JavaBeans components.

In the first case, information is associated with the presence of the JavaBeans component in its container. For example, this is what happens when a JavaBeans component is added to a Builder tool palette, or when a new JavaBeans component plug-in is dropped into JMAPI.

The second case occurs at runtime within a JavaBeans component. For example, the JavaBeans component is a complex plug-in. While in a popup window for that plug-in, we want to display the help information in a form that is consistent with whatever display presentation the container uses for help information.

The third case occurs when a JavaBeans component is instantiated into a container and it is given some semantics by customizing it and by attaching to events and actions. In this case we want an easy mechanism to assign help data that describes the semantics so that a gesture can retrieve that help data.

The mechanisms described in the following section pertain to the first two cases. The third situation is covered by the mechanisms for context-sensitive help and other, more ad hoc, mechanisms.

Help Information

The needs of the two cases described above require the association and retrieval of two pieces of information per JavaBeans component:

Having two different pieces of information (cf. having the HelpID be a fixed value) provides for additional packaging flexibility and leads to a nice default convention, and useful default values are important to keep within the JavaBeans design philosophy. The default for this information depends on whether the name of the JavaBeans component is in the unnamed package or not:

Name is of the form OurButton:

If the name is of the form sunw.demo.buttons.OurButton:

Mechanism

The proposed mechanism is to use two optional String-valued BeanInfo attributes with the names suggested above: "helpSetName", and "helpID". This mechanism is relatively simple, does not require the JavaBeans component to be initialized, and it is consistent with other uses of BeanInfo attributes (e.g. Swing's use for container information).

To simplify following the default rules described above, we add two methods to a JavaHelp class that take a Class object and return the desired Strings after consulting the appropriate methods.

An Example:

Below is the buttons example from the BDK , modified to provide Help information. This example uses the default values for HelpSetName and HelpId:

Manifest and JAR File

The manifest file just changes to include the Help files; it would look like:


    // Beans, Implementation Classes, and Gif images are as before
    
    // the HelpSet file
    Name: sunw/demo/buttons/Help.hs
    
    // The Map file
    Name: sunw/demo/buttons/help/Map.html
    
    // Actual html data - in this case all in one file
    Name: sunw/demo/buttons/help/Buttons.html

    // View data
    Name: sunw/demo/buttons/help/toc.xml

    Name: sunw/demo/buttons/help/index.xml

    Name: sunw/demo/buttons/help/search.dat

The HelpSet File

All the HelpSet files are the same. The HelpSet file is quite simple (see below for details on the classes view). 


    # ...

    # map URL
    <homeID>sunw.demo.buttons.topId</homeID>
    <map>
        <data>!/sunw/demo/buttons/help/Map.html</data>
    </map>

    # data views
    <view>
        <name>TOC</name>
        <label>Table of Contents</label>
	<type>javax.help.TOCView</type>
        <data>!/sunw/demo/buttons/help/toc.xml</data>
    </view>

    <view>
        <name>Index</name>
        <label>Index</label>
        <type>javax.help.IndexView</type>
        <data>!/sunw/demo/buttons/help/index.xml</data>
    </view>

    <view>
        <name>Search</name>
        <label>Search</label>
        <type>javax.help.SearchView</type>
        <engine>com.sun.java.help.search.DefaultSearchEngine</engine>
        <data>!/sunw/demo/buttons/help/search.dat</data>
    </view>

The Help Map

In this simple example, the Map just handles the top IDs, plus a global introduction to the buttons package. 


    sunw.demo.buttons.topId="!/sunw/demo/buttons/help/Buttons.html#Top"
    sunw.demo.buttons.OurButton.topId="!/sunw/demo/buttons/help/Buttons.html#OurButton"
    sunw.demo.buttons.ExplicitButton.topId="!/sunw/demo/buttons/help/Buttons.html#ExplicitButton"
    sunw.demo.buttons.OrangeButton.topId="!/sunw/demo/buttons/help/Buttons.html#OrangeButton"
    sunw.demo.buttons.BlueButton.topId="!/sunw/demo/buttons/help/Buttons.html#BlueButton"

An Alternative Arrangement

A alternative arrangement would have been to place all the help data in a single nested JAR file. For example:

Manifest and JAR file


	// The Beans, Implementation Classes and Gifs as before

	// The Help data
	Name: sunw/demo/buttons/Help.hs

	// The rest of the Help data
	Name: sunw/demo/buttons/help.jar

The HelpSet File

 The Help file has to change a bit: 

    # no property requests

    # map URL
    <homeID>sunw.demo.buttons.topId</homeID>
    <map>
        <data>!/sunw/demo/buttons/help.jar!/Map.html</data>
    </map>

    # data views
    <view>
        <name>TOC</name>
        <label>Table of Contents</label>
        <type>javax.help.TOCView</type>
        <data>!/sunw/demo/buttons/help.jar!/toc.xml</data>
    </view>

    <view>
        <name>Index</name>
        <label>Index</label>
        <type>javax.help.IndexView</type>
        <data>!/sunw/demo/buttons/help.jar!/index.xml</data>
    </view>

    <view>
        <name>Search</name>
        <label>Search</label>
        <type>javax.help.SearchView</type>
        <engine>com.sun.java.help.search.DefaultSearchEngine</engine>
        <data>!/sunw/demo/buttons/help.jar!/search.dat</data>
    </view>

The Help Map

In this example, we can choose to use exactly the same Help map as what we used in the previous arrangement.

JavaHelpTM 1.0
Send your comments to javahelp-comments@eng.sun.com
Last modified: Mon Apr 12 16:42:45 MDT 1999