Server Based JavaHelp

## Server-Based JavaHelp Helpsets

Server-based applications have the same need for online help as client based applications, but they require that the helpset runs in a web browser, as the applications do, and that it be accessed from a server. Version 1.0 of the JavaHelp software API provided a foundation for developing online help for server-based applications. However, the specification did not define standards for a JavaHelp bean or for a Java Server PagesTM (JSP) tag library to access helpset data. Version 2 of the JavaHelp software does define these standards and provides a tag library for server-based applications.

### Java Server Pages

JSP enables web developers to develop dynamic web pages. JSP uses XML-like tags to encapsulate the logic that generates web content. JSP pages separate the page logic from its design and display, which prevents the overlapping of roles between web designers and programmers. Designers design the web pages and programmers add the logic and code to them.

For more information and tutorials on JavaServer Pages technology, see http://java.sun.com/products/jsp/docs.html.

### Server-Based JavaHelp Architecture

By combining the JavaHelp software API with new JavaHelp JSP tag libraries, web developers are now able to provide help for server-based applications. The diagram below illustrates the architecture.

.

A browser initiates a JSP request. Examples of a JSP request are displaying the help content in the helpset, the navigators, or the data for a given navigator. Typically, the JSP request contains JavaBeansTM components as well as JSP tag extensions. The JavaTM server turns the request into a Java Servlet. The servlet access the appropriate information from the helpset by using the classes in the JavaHelp library (`jh.jar`) and the JavaHelp tag library (`jhtags.jar`) and returns HTML and possibly JavaScript or dynamic HTML (DHTML) to the browser.

### JavaHelp Server Components

Access to helpset data on a server is accomplished through a combination of JavaBeans components specific to the JavaHelp system and JSP tag extensions. This section defines the standard JavaHelp JavaBeans and JSP tag extensions and scripting variables.

#### JavaHelp Server Bean

`ServletHelpBroker` is the JavaBean component that stores help state information, such as the helpset in use, the current ID, the current navigator and other pieces of help information. While it implements the `javax.help.HelpBroker` interface, some of the methods are either not implemented or throw `UnsupportedOperationExceptions` if called. The `javax.help.HelpBroker` methods that are not implemented in this component are listed below:

Method | Result
--- | ---
`initPresentation()` | No Operation
`setDisplayed(boolean)` | Ignored
`boolean isDisplayed()` | Always returns true
`enableHelpKey( Component, String id, HelpSet)` | No Operation
`enableHelp( Component|MenuItem, String id, HelpSet)` | No Operation
`enableHelpOnButton( Component| MenuItem, String id, HelpSet)` | No Operation

One new method is added to `ServletHelpBroker`:

Method | Result
--- | ---
`NavigatorView getCurrentNavigatorView()` | Returns the current navigator as a `NavigatorView`.

#### Using `ServletHelpBroker`

The `ServletHelpBroker` is used in the JSP request with a session scope. With this scope, the help broker remains in existence for the duration of a session. The following code defines the help broker:

`<jsp:useBean id="helpBroker" class="ServletHelpBroker" scope="session" />`

The `ServletHelpBroker` methods can be called in two ways:

- In tag libraries:

  `<jh:validate helpBroker="<%= helpBroker %>" />`

- Directly in the JSP:

  `<FRAME SRC=
  "<jsp:getProperty name="helpBroker" property="currentURL" />"
  NAME="contentsFrame" SCROLLING="AUTO">`

### JavaHelp JSP Tag Extensions

While you could retrieve all the helpset information required for displaying online help or documentation by using JavaBeans components and JSP scriptlets, you can instead avoid the appearance of programming and use a standard set of tag extensions in the JavaHelp tag library to invoke application functionality. The JavaHelp tag library is a common set of building blocks that perform the following functions:

- Concealing the complexity of access to helpset data
- Introducing new scripting variables into a page
- Handling iterations without the need for scriptlets

The JavaHelp JSP tags are defined below:

Tag | Tag Class TEI Class | Description | Attributes
--- | --- | --- | ---

`validate`

`ValidateTag`

Validates a `HelpBroker` with various parameters. Enables easy setup of a help broker with a new helpset. Also enables merging of helpsets and setting the current ID.

`helpbroker`
  required
  `HelpBroker` object
`setInvalidURL`
  not required
  String representing the URL for `InvalidHelpSet` message.
`helpSetName`
  not required
  String representing the URL for `the helpset name.`
`currentID`
  not required
  String id of desired currentID.
`merge`
  not required
  Boolean value. If true then merge helpset into current helpset if one exists. Otherwise do not merge helpset.

`navigators`

NavigatorsTag
NavigatorsTEI

Returns `NavigatorView` information for a given `HelpBroker`.

`helpbroker`
  required
  `HelpBroker` object
`currentNav`
  not required
  String name of the current navigator`.`

`tocItem`

`TOCItemTag
TOCItemTEI`

Provided with a `TOCView`, returns `TOCItem` information.

`tocView`
  required
  `TOCView` object
`helpbroker`
  required
  `HelpBroker` object
`baseID`
  not required
  Determined by expression. String text for the base identification of the `TOCItem`.

`indexItem`

`IndexItemTag
IndexItemTEI`

Provided with an `IndexView`, returns `IndexItem` information.

`IndexView`
  required
  Determined by expression. `IndexView` object.
`helpbroker`
  required
  `HelpBroker` object
`baseID`
  not required
  Determined by expression. String text for the base identification of the `IndexItem`.

`searchItem`

`SearchItemTag
SearchItemTEI`

Provided with a `SearchView`, returns `SearchItem` information.

`SearchView`
  required
  Determined by expression. `SearchView` object.
`helpbroker`
  required
  `HelpBroker` object
`baseID`
  not required
  Determined by expression. String text for the base identification of the `SearchItem`.

Unless otherwise specified, all attribute values are determined by expression. Also, with the exception of the `validate` tag, the body of all tags are JSP.

#### Using the `validate` Tag

The `validate` tag is designed to be used once in a JSP, as shown below:

`<jh:validate helpBroker="<%= helpBroker %>" />`

The preceding code verifies that a valid `HelpBroker` exists and then loads the helpset that has been defined either in the `validate` tag with the `helpSetName` attribute or as an `HTTP POST` request.

### Navigator Scripting Variables

The `navigator`, `tocItem`, `indexItem`, and `searchItem` tag extensions introduce a predefined set of scripting variables into a page. These variables enable the calling JSP to control the presentation without having to perform processing to determine the content. Unless otherwise specified, each scripting variable creates a new variable, and the scope is set to `NESTED`. `NESTED` variables are available to the calling JSP only within the body of the defining tag.

#### Navigator Variables

The navigator variables are defined in the table below.

Variable | Data Type | Description
--- | --- | ---
`classname` | `java.lang.String` | Name of the `NavigatorView` class.
`name` | `java.lang.String` | Name of the view as defined in the helpset.
`tip` | `java.lang.String` | Tooltip text for the view.
`iconURL` | `java.lang.String` | URL for the icon if set with the `imageID` attribute in the helpset.

#### Using the Navigator Variables

The `navigator` tag is used to return information about the current navigator. In the illustration below the `navigator` tag is used to determine the navigators that are used in the helpset and sets an HTML `<img>` tag based on the navigator name.

    <jh:navigators helpBroker="<%= helpBroker %>" >
       <A HREF="navigator.jsp?nav=<%= name %>">
       <IMG src="<%= iconURL!=""?
            iconURL : "images/" + className +".gif" %>"
            Alt="<%= tip %>"
            BORDER=0></A>
    </jh:navigators>

#### `tocItem` Variables

The tocItem variables are defined in the table below.

Variable | Data Type | Description
--- | --- | ---
`name` | `java.lang.String` | `tocItem` text as defined in the `name` attribute.
`target` | `java.lang.String` | `tocItem` target as defined in the `target` attribute.
`parent` | `java.lang.String` | Hex value identifying the parent node.
`parentID` | `java.lang.String` | String identifying the parent node.
`node` | `java.lang.String` | Hex value identifying this node.
`nodeID` | `java.lang.String` | String identifying this node.
`iconURL` | `java.lang.String` | URL for the icon if set with the `imageID` attribute in the `tocItem`.
`contentURL` | `java.lang.String` | URL for the content represented by this item.
`isCurrentNav` | `java.lang.Boolean` | True if current navigator, false if not.

#### Using `tocItem`

The `tocItem` tag returns information about the TOC items defined in a `TOCView`. In the sample code below, the `TOCView` returns `tocItem` scripting variables that are added to the JavaScript tag `tocTree.addTreeNode`.

    tocTree = new Tree("tocTree", 22, "ccccff", true, false);
    <% TOCView curNav = (TOCView)helpBroker.getCurrentNavigatorView(); %>
    <jh:tocItem helpBroker="<%= helpBroker %>" tocView="<%= curNav %>" >
       tocTree.addTreeNode("<%= parentID %>",
                           "<%= nodeID %>",
                           "<%= iconURL!=""?iconURL:"null" %>",
                           "<%= name %>","<%= helpID %>",
                           "<%= contentURL!=""?contentURL:"null" %>",
                           "<%= expansionType%>" );
    </jh:tocItem>
    tocTree.drawTree();
    tocTree.refreshTree();
      <%
      ID id = helpBroker.getCurrentID();
      if (id != null) {
      %>
         tocTree.selectFromHelpID("<%= id.id%>");
      <%
         }
      %>

#### `indexItem` Variables

The `indexItem` variables are defined in the table below.

Variable | Data Type | Description
--- | --- | ---
`name` | `java.lang.String` | `indexItem` text as defined in the `name` attribute.
`target` | `java.lang.String` | `indexItem` target as defined in the `target` attribute.
`parent` | `java.lang.String` | Hex value identifying the parent node.
`parentID` | `java.lang.String` | String identifying the parent node.
`node` | `java.lang.String` | Hex value identifying this node.
`nodeID` | `java.lang.String` | String identifying this node.
`iconURL` | `java.lang.String` | URL for the icon if set with the `imageID` attribute in the `indexItem`.
`contentURL` | `java.lang.String` | URL for the content represented by this item.

#### Using `indexItem`

The `indexItem` tag returns information about the index item defined in an `IndexView`. In the sample code below, the `IndexView` returns `indexItem` scripting variables that are added to the JavaScript tag `addNode`.

    indexTree = new Tree("indexTree", 22, "ccccff", false, true);
    <% IndexView curNav = (IndexView)helpBroker.getCurrentNavigatorView(); %>
    <jh:indexItem indexView="<%= curNav %>" helpBroker="<%= helpBroker %>" >
        indexTree.addTreeNode("<%= parentID %>",
                              "<%= nodeID %>", "null",
                              "<%= name %>","<%= helpID %>",
                              "<%= contentURL!=""?contentURL:"null" %>",
                              "<%= expansionType%>");
    </jh:indexItem>
    indexTree.drawTree();
    indexTree.refreshTree();
    <%
      ID id = helpBroker.getCurrentID();
      if (id != null) {
      %>
         indexTree.selectFromHelpID("<%= id.id%>");
      <%
         }
      %>

#### `searchItem` Variables

The `SearchItem` variables are defined in the table below.

Variable | Data Type | Description
--- | --- | ---
`name` | `java.lang.String` | Unique name of the `searchItem`.
`helpID` | `java.lang.String` | String ID associated with this `searchItem`.
`confidence` | `java.lang.String` | The quality of the hits as returned by the search engine.
`hits` | `java.lang.String` | Number of hits.
`contentURL` | `java.lang.String` | URL for the content represented by this item.
`hitBoundries` | `java.lang.String` | A list of boundaries. Returns in the format of {begin, end},...

#### Using `searchItem`

The `searchItem` tag returns information about the search items defined in a `SearchView`. In the sample code below, the `SearchView` returns `searchItem` scripting variables that are added to the JavaScript tag `addNode`.

    searchList = new SearchList("searchList", 22, "ccccff");
    <jh:searchTOCItem searchView="<%= curNav %>"
                      helpBroker="<%=    helpBroker %>"
                      query="<%= query %>" >
       searchList.addNode("<%= name %>",
                          "<%= confidence %>",
                          "<%= hits %>",
                          "<%= helpID %>",
                          "<%= contentURL %>" );
    </jh:searchTOCItem>
    searchList.drawList();
    searchList.refreshList();
    searchList.select(0);

See also:

  Context-Sensitive Help
  Programming with the JavaHelp System
  Adding the JavaHelp System to Applications
  Embedding JavaHelp Components