#
JavaHelpTM 1.0 - Customization

##
Copyright 1998-1999 Sun Microsystems

## Introduction

There are several mechanisms for customizing JavaHelp:

- Defining a different default HelpBroker
- Associating alternate content viewers with MIME types
- Using non-standard NavigatorView or JHelpNavigator
- Choosing SearchEngine
- Exploiting the URL protocols

## Help Broker

A HelpBroker provides abstraction of the presentation details of a HelpSet. There are two ways of obtaining a HelpBroker: through an explicit instantiation of DefaultHelpBroker, or by invoking the createHelpBroker() method on a `HelpSet` instance. The default `HelpBroker` returned by the `createHelpBroker()` call is implementation dependent--the reference implementation returns `DefaultHelpBroker`.

Constructors of `HelpBroker`s take a HelpSet instance as an argument; `DefaultHelpBroker` uses a JHelp for its presentation, adding to it all the `HelpNavigator`s that were requested in the `HelpSet` file and arranging them so they all share the same `HelpSetModel`.

A JavaHelp system implementation may choose not to create a `DefaultHelpBroker` as the default `HelpBroker` for any of several reasons, for example to maintain a consistent presentation. Thus, it is often best to use `createHelpBroker()` to obtain the `HelpBroker`.

## Content Viewers

The JavaHelp reference implementation uses `JEditorPane` to present the HTML content of a given URL. This class supports a registration mechanism by which you can add viewers for given MIME types. This mechanism is exported through the JHelpContentViewer JavaHelp class and can be used to display additional MIME types, or to change the presentation of a given type from the default presentation. The mapping can be changed globally or on a per-HelpSet instance. For additional information, see Key-Data Map below.

## NavigatorView and JHelpNavigator

The NavigatorView class defines a NavigatorView type and provides access to the information in a `<view>` tag in a HelpSet file. A NavigatorView also provides a `JHelpNavigator` through its `create` method. JHelpNavigator is the Swing class used in the JavaHelp system to capture the presentation of a NavigatorView. A `JHelpNavigator` can be created directly, but more commonly it is created implicitly through the `create()` method in a NavigatorView.

### View-Specific Knowledge

Specific `NavigatorView` may have additional methods and fields that encode specific information on the view type. For instance, both TOCView and IndexView provide a `parse` method that can be used to parse a URL that conforms to the file format. These methods use a `Factory` class to provide access for customizing the result of the parsing.

The separation of view data and its presentation means that it is possible to access the view data without having to actually create the presentation. It also means that it is easy to modify the presentation without having to duplicate some data-specific information; for example, by reusing the parsing methods.

### Different Formats

The Help Navigator mechanism can also be used to provide access to meta-data that is in a "foreign" or "legacy" format. This might enable an application to access information from legacy applications or an alternate meta-data format such sitemap, or meta-data from the Library of Congress, or other library system. This may be done by creating a new NavigatorView that can parse the "foreign" format but that reuses the presentation from the JavaHelp `JHelpNavigator`.

A variation of this last case, the data is not stored anywhere but it is created dynamically. This is easily acomplished by subclassing TOCView (for instance) and redefining the method getDataAsTree() to return the data whenever invoked.

### Different Presentations

A JHelpNavigator selects its presentation through the standard Swing method `getUIClassID()` to indicate its ComponentUI class. A new JHelpNavigator that is not capable or willing to reuse an existing ComponentUI needs to return an appropriate class value in `getUIClassID()`. If appropriate, this ComponentUI may be a subclass of the standard ComponentUI classes (`BasicTOCNavigatorUI.java`, `BasicIndexNavigatorUI.java` and `BasicSearchNavigatorUI.java`) with some methods redefined. A useful method to redefine is setCellRenderer which permits to change the presentation details of the Tree in both TOC and Index presentations.

### Two Examples of Custom Views

The three standard Views included in JavaHelp 1.0 (TOCView, IndexView, SearchView) cover most online documentation needs, but there are other situations where one might want to have custom views and navigators. As a first example, the Java Tutorial could be used to illustrate the concept of a Help Navigator. The Java Tutorial is an online document that describes the Java Platform. The tutorial is organized into trails: groups of lessons on a particular subject. A version of the tutorial could take advantage of a NavigatorView that supported the notion of a trail. Such a view could remember the position within the trail, quickly reference examples within the trail, and navigate to other trails.

Another example is an API class viewer. Such a viewer was created for demonstration purposes and is included in the reference implementation. This NavigatorView uses information collected from source files that are annotated using the `javadoc` system. The traditional data generated by `javadoc` is produced as HTML files. Static HTML indexes and trees are used to provide navigational information. The result is useful but it is difficult to effectively navigate. The classviewer NavigatorView is customized to dynamically display this information. A picture of an early version of the presentation is shown next:

In this example there are three navigational views: TOC, Index, and Search. Index is an index of all the methods, classes, and packages, and Search provides a full-text search of all the `javadoc` information. The TOC view uses the new classview NavigatorView. When a class is selected in the top pane of the navigator, the `JHelpNavigator` determines if it has already loaded the metadata for that class. If not, it presents the fields, constructors and methods in the bottom pane. When a method is selected, the appropriate content file is presented in the JavaHelp system TOC pane. In this particular prototype, the information presented is only that of the selected class but the navigator could easily provide access to inherited information too.

For this example, we use the new Doclet facility in JDK1.2 to generate the desired metadata.

## Search Engines

The standard `NavigatorView` and `JHelpNavigator` search classes (`javax.help.SearchView` and `javax.help.JHelpSearchNavigator`) provide an interaction with search engines via the classes in the `javax.help.search` package. `SearchView` views may have an optional `<engine>` attribute of their `data` tag indicating the specific `javax.help.search.SearchEngine` subclass to use to perform searches. The default is `com.sun.java.help.search.DefaultSearchEngine`, which is the search engine included in the reference implementation.

The same view and presentation can be used with other search engines following the same protocol, by naming the `SearchEngine` class in the `<engine>` attribute and making the class available.

Different view and or presentations of search can be provided using the standard customization mechanisms for this. These may, or not, reuse the default search engine.

## Key-Data Map

`HelpSet` provides a simple registry mechanism that provides per-instance or global key-data mapping. The mechanism can be accessed via the `setKeyData`, `setDefaultKeyData` and `getKeyData` methods. This mechanism is used by the `JHelpContentViewer` to determine the EditorKit to use for a given MIME type, and also to determine the HelpBroker to use in the `HelpSet.createHelpBroker()` method.

The per-HelpSet registry will be instantiated from the contents of the `<impl>` section of the HelpSet file in the 1.0 version of the JavaHelp system.

## Using new URL protocols

Another mechanism for extending JavaHelp is by providing new protocols that can, for example, provide SGML -> HTTP translation. This is very easy to do in a Java application by defining a few simple URL classes; it is not possible to do in an Applet in JDK1.1 since there is no support for downloadable URL protocols.

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