JavaHelpTM 1.0 - Customization
There are several mechanisms for customizing JavaHelp:
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 HelpBrokers take a HelpSet
instance as an argument;
DefaultHelpBroker uses a
JHelp
for its presentation,
adding to it all the HelpNavigators 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
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
Specific
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.
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.
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.
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.
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
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
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.
Different Formats
Different Presentations
Two Examples of Custom Views
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.
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.
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.