JavaHelp^TM 1.0 - Scenarios

Copyright 1998-1999 Sun Microsystems

Introduction

This document contains a number of scenarios that illustrate ways the JavaHelp system can be used to provide online help for different types of Java programs in a variety of network environments. These scenarios attempt to illustrate the flexibility and extensibility of the JavaHelp system.

Scenarios are presented in four areas:

Code examples complementing these scenarios can be found in the reference implementation release available at http://java.sun.com/products/javahelp.

Invocation Mechanisms

These scenarios describe the different ways the JavaHelp system can be invoked.

The JavaHelp system is often invoked from an application when a user chooses an item from a Help menu, clicks on a Help button in an application GUI, or uses one of the context-sensitive help activation gestures to request help on a GUI component.

The JavaHelp system provides a simple interface for requesting the creation of a help presentation by requesting that a topic ID (identified by a string) be displayed. Topic IDs are associated with URLs in the map file(s) mentioned in the HelpSet file.

For example, when coding a file chooser dialog box, a developer requests that the topic ID fc.help be displayed when the Help button at the bottom of the dialog box is clicked. In the HelpSet file (or in some cases the map file referred to in the HelpSet file) the ID fc.help is defined to be a file named FileChooser.html using the following syntax:

<mapID target="fc.help" url="FileChooser.html"/>

Separating the specification of actual file names from the program code, provides content authors the freedom to control the information that is associated with the topic ID.

A tooltip is a brief message presented to the user when the cursor remains over a button for an interval longer than a given threshold.

Although tooltip information could be included in the JavaHelp system data, it will usually be delivered as part of the application and will be co-located with the code.

Context-sensitive help (sometimes included in the term What-is help) is help information that describes graphical components in an application GUI. It is triggered by gestures that activate context-sensitive help and then specify the component in question. See CSH.html for more details.

Recent products are exploring the notion of a Helper, or an Assistant, an example is the assistant in MS's Office 97. A helper is a mechanism that reacts to state and state transitions in applications and provides guidance and suggestions to the user. Such a mechanism requires significant close interaction between the application and the information presented to the user. This is not directly supported in the 1.0 release of the JavaHelp system.

The following scenarios illustrate different ways that the JavaHelp system can be used to present and deploy Help information.

The "kiosk" scenario is one where documents are presented independent of an application.

An example on the Solaris platform is AnswerBook -- a technology used to display all of Sun's documentation online. All that is required is a help browser that can be launched to present and navigate through the information.

In JDK1.2, a JAR file can indicate a containing Application class that will be invoked automatically by the system (by passing it to a "java -jar" command).

The simplest scenario is one in which the Java application runs locally and accesses help data installed on the same machine.

The application requests the creation of a JavaHelp instance, loads the help data on it, and then interacts with this instance, either by requesting the help information be presented and hidden, or by requesting a specific topic (identified by an ID) be presented.

Embedded help is inherently application-specific since the application controls where each of the presentation UI components are located. The JavaHelp reference implementation is organized so that most applications will be able to achieve their needs very easily.

Component Help

Many current applications are composed of a collection of interacting components. Examples range from large applications like Netscape navigator (with plugins) to applications where JavaBeans components are connected together using JavaScript or Visual Basic.

The help information can be merged in different ways. For instance, the table-of-contents, index, and full-text search information from each component may be displayed one after the other to create a new, unified help system.

As HelpSets are loaded/unloaded into a JavaHelp instance, the information presented needs to be updated. The JavaHelp system provides a flexible mechanism for merging this information.

In some cases, it may be necessary to separate the application from the process that presents the help information. In this case the application process can make requests into a JavaHelp process (help server) through an RPC mechanism (the RPC may be wrapped in a library and be invisible to the application developer).

The help server model is useful if the application is not written in Java and does not include a JVM. It would also be useful for a suite of Java applications that can share a common help server.

The final scenario describes how the JavaHelp system is used from within web-based applications. In this case an applet or some other triggering entity (perhaps a JavaScript event) on an HTML page creates a HelpSet object and then invokes HelpSet.createJavaHelp().

This scenario can have a number of variations. Here are a three:

• In one case, the browser platform contains a customized implementation of the JavaHelp system. This implementation may have been delivered with the browser, or it may have been downloaded by the client into the CLASSPATH. The implementation may use the Swing HTML viewer, or, more likely, it may use some the HTML viewer that comes with the Web Browser.
  

• Since the JavaHelp system is a Java "standard extension," it is possible that a fully-conforming JDK browser may not have it in its CLASSPATH. In this case, if the HTML page refers to the standard JavaHelp system implementation, the standard extension machinery will automatically download the implementation and execute it. Since our implementation is quite small, this approach will often be practical. Browsers may choose to provide some way of easily installing extensions downloaded through this mechanism.

  This situation is depicted in the next picture where, for variety sake, we have changed the help presentation so the navigator is separate from the content.

  

  The corresponding APPLET tag may look something like this:

  
  <APPLET
      CODE=javax.help.HelpButton
      ARCHIVE="JavaHelpDefault1_0.jar"
  >
  <PARAM
      NAME=HelpSet
      VALUE=MyHelp.JAR>
  </APPLET>
  
  

• In some cases, some client browsers may not have a fully-conformant Java Virtual Machine. In that case we can use the Java Plug-in technology to request a compliant Java Virtual Machine. The request may lead to a download request if the virtual machine is not available locally; once installed later requests will proceed with no download step. Once the appropriate JVM has been started, the situation is equivalent to the previous two steps. The following figure illustrates this:
  

The JavaHelp system provides mechanisms for extending navigational views and content displayers, the classes providing this can be downloaded automatically using the standard classloader mechanisms of the Java platform (e.g. using ARCHIVE or CLASSPATH).

Search Scenarios

The JavaHelp system supports an extensible full-text search mechanism using the extension framework mechanism, plus a Search interface. The JavaHelp1.0 specification requires all implementations to support some search types and formats. This mechanism can be used to support a number of different search scenarios:

In a client-side search, searching is done locally on the "client-side", but the search data originates on the "server-side". This commonly occurs with web-based applications (applets). The help data usually resides on the same server as the applet code. When a search is initiated the search data is downloaded from the server, read into the browser's memory, and searched. The content files are downloaded only when they are presented.

Time is required for the search database to be downloaded during the initial search. Once downloaded the data can be kept in memory or in a temporary file on the client machine. Once the database is downloaded, searches are quite fast.

In a server-side search, both the search data and the content files are located on the server side; only the results of the search are downloaded to the client.

This is another option for applets. It permits developers to use a choice of commonly available search engines and can provide quick start-up time (especially if the search engine is started ahead of time). On the other hand, it requires additional administrative work to get the search engine installed. Note that this approach works very well with Java servlets.

In a stand-alone search, all of the components are local (search engine, search database, help content). From an implementation point-of-view, the stand-alone search is quite similar to the client-search except that there is no need to cache the search data in memory or in local files.

Note that help content files can be accessed locally and/or across a network.

The following diagrams represent typical packaging scenarios. These scenarios are intended to be exemplary and are not exhaustive.

The first picture represents a project in which the map file is packaged together with most (all?) of the content files. The "!" syntax is used to specify the URLs relative to the JAR where the map is located. The HelpSet file is packaged outside of the JAR file, perhaps to simplify updates later on.

In the following scenario, the map file and the JAR file are in different locations. This is probably not a common scenario, but is shown to illustrate packaging flexibility.

In the final scenario, the HelpSet file is bundled in the JAR file with the rest of the JavaHelp system data.

The advantage of this arrangement is that all the URLs are relative to the base URL of the HelpSet file, and that there is no need to mention the jar: protocol within any JavaHelp system file. This JAR, when placed in a CLASSPATH, permits a JDK1.1 application to refer to the HelpSet within the JAR file transparently. A similar situation occurs with Applets, when the JAR file is listed in the ARCHIVE attribute.

An example of where this functionality might be useful is in an application suite. The application suite may be comprised of a collection of constituent applications. As constituent applications are purchased and installed, their help information can be merged with help information from the other applications in the suite.

In the following scenario an application suite is comprised of three possible suite components. The help data for each component in the suite is delivered as its own HelpSet. The suite is shipped with a master HelpSet that lists the subcomponent HelpSets. When the HelpSet object for the suite HelpSet file is created, each subcomponent HelpSet file (specified by means of the <subhelpset> tag) is read to create HelpSet objects that are then merged into the containing HelpSet. Subcomponent HelpSet that are not installed are ignored.