2 Oracle Help for Java User Interface
This chapter describes Oracle Help for Java user interface components, such as Navigator window, Topic window, Index tab, Search tab, and Favorites tab.
This chapter contains the following sections:
2.1 About Oracle Help for Java User Interface
The Oracle Help for Java (OHJ) user interface has two main parts, Help Navigator window and Help Topic window. The Help Navigator window includes controls for finding topics and the Help Topic window displays HTML content.
Figure 2-1 Help Navigator and Help Topic Windows
Description of "Figure 2-1 Help Navigator and Help Topic Windows"
Figure 2-2 Docked Windows
Description of "Figure 2-2 Docked Windows"
2.2 OHJ Topic Windows
The OHJ Help Topic windows (or topic panes, when docked) display HTML content. Figure 2-3 shows topic windows with different types of HTML content.
Figure 2-3 Topic Windows
Description of "Figure 2-3 Topic Windows"
The default HTML display component included in the OHJDK is a special implementation of the ICEbrowser from ICEsoft Technologies, Inc. For more information about the browser and its supported technologies, see
http://www.icesoft.com. You may use and redistribute this component free of charge if it is used as part of a help system using OHJ. This HTML display component supports the following:
Cascading Style Sheets (CSS) 1 and most of CSS 2. CSS 3 is not supported.
Multimedia, as supported by Java Media Framework 2.0.
Support for Screen Reader software
Single topic and multiple topic printing
Popups with HTML support
Associative links, where a single index word or phrase can be associated with multiple topics. When the user selects one of these links, a list of all topics associated with the link is presented, and the user can choose a topic from the list.
Author-defined window types, where authors can specify colors such as background color, text color, and link color, window size and position, window title, and toolbar buttons.
Topic ID linking—hyperlink targets are specified by ID rather than URL
Synchronization with items in the table of contents
You do not have to use the default HTML display. You can replace it with a different HTML display component. Or, if your application and the help system run as an applet in a Web browser, you can use a browser window as the topic window. Consequently, the display capabilities for your implementation of OHJ rely on the HTML display you chose to embed in the system.
2.3 OHJ Navigator Window
The navigator window is a tabbed control for navigating and finding topics in the help system. By default, the navigator window contains tabs for a Contents, Index, and Search. Authors can control several characteristics of the navigator window simply by setting parameters for the help system. For example, you can change the labels on the tabs and add icons. You could also display multiple tables of contents, for example, one for product help and one for a tutorial. For a more complex system, a Java programmer can create custom tabs, and the author can add them to the navigator window.
This topic contains the following sections:
2.3.1 Contents Tab
The Contents tab displays topics in a hierarchical tree. The contents and structure of the tree are specified by the author. Multiple file formats are supported for defining the tree.
Figure 2-4 Contents Tab in the Navigator Window
Description of "Figure 2-4 Contents Tab in the Navigator Window"
When a user double-clicks a topic title in the table of contents, that topic is displayed in the topic window. The user may also open a topic in a new, additional, topic window by selecting a button on the toolbar, or by selecting a command from the right-click context menu.
The table of contents view has the following features:
The item selected (highlighted) in the table of contents is automatically synchronized to the topic shown in the topic window. For example, if you click a hyperlink in a topic and jump to a new topic, the selection in the table of contents switches from the old topic to the new one.
Unlimited levels of hierarchy are allowed.
The list of items in the navigator window can be printed.
2.3.2 Index Tab
The Index tab displays an alphabetical list of keywords associated with topics. The keywords are defined by the help author, and, like the table of contents, multiple file formats are supported for specifying the list.
Figure 2-5 Index Tab in the Navigator Window
Description of "Figure 2-5 Index Tab in the Navigator Window"
Figure 2-5 numbered callouts identify the following user interface components:
Text entry field: The user types a word or words in this field.
Keyword list: As the user types, the first keyword in the list that matches the typed letters is selected. As more letters are typed, a more accurate selection is made. Alternatively, the user can simply select a keyword from this list.
Topic list: The titles of any topics that are associated with the keyword selected in Keyword List are displayed in this list. When the user double-clicks one of these titles, the topic is displayed in the topic window. The user may also select the topic and click Open.
The index provides many useful features:
One keyword can be associated with many topics, and many keywords can be associated with a single topic.
Two levels of indenting are supported.
When merging helpsets, one unified index is created with proper alphabetization for the entire index. In other words, the entries are merged and resorted; they are not concatenated.
Indexes are properly alphabetized when translated into languages other than that used to create the index.
Identical entries are collapsed to show only one.
2.3.3 Search Tab
The Search tab displays a text field where the user can enter text, then select Search. The titles of topics whose content contains that word or phrase are listed in the Results list at the bottom of the tab. When the user double-clicks a title, that topic appears in the topic window.
Figure 2-6 Search Tab in the Navigator Window
Description of "Figure 2-6 Search Tab in the Navigator Window"
Figure 2-6 numbered callouts identify the following user interface components:
Search text: The user enters a word or words in this field. To search for an exact phrase, enclose the search phrase in double quotes.
Case Sensitive: A checkbox, when selected, enables searching for words having the same case as the words entered by the user.
Search for: A set of option buttons that allows a user to specify whether to list topics that contain any or all of the specified words, or perform a search based on a Boolean expression (AND, OR).
Topic List: The results area displays the Rank, Topic Title, and Source of each topic that matches the search criteria. The Rank column indicates the ranking of the topics according to how well they match the search criteria. All columns can be sorted in the ascending or descending alphabetical order. By default, all topics are sorted by Rank. When the user selects a particular result, the associated topic is displayed in the topic pane.
Users can set the following options when performing a search:
Enable or disable case-sensitivity of search keywords.
List topics that contain all search words or at least one search word.
Search based on a Boolean expression (AND, OR).
Search tab provides many useful features:
Results are ranked according to how well they match the search criteria.
Previously entered search criteria are saved and can be displayed in a drop-down list.
Results list the title of the topic and its source.
Users can sort results by rank, topic title, or topic source.
The search database is generated when authoring the help system. The OHJDK and as other authoring tools that support OHJ include a utility for generating this database, called the Text Search Indexer. The search database uses an Oracle-defined file format. This search database is always used when you implement it on the client. You can also implement your own search on a server. For example, if you store your topics in an Oracle database, you can use the database's text processing capabilities to perform the search.
For more information about Text Search Indexer, see Chapter 11, "Using the Text Search Indexer".
An Oracle database is not required to use OHJ.
2.3.4 Favorites Tabs
Users can mark topics in a helpset as favorites using the Favorites Navigator, similar to the Favorites functionality in web browsers.
Figure 2-7 Favorites Tab in the Navigator Window
Description of "Figure 2-7 Favorites Tab in the Navigator Window"
Users can identify and manage favorite topics from a helpset:
Add or delete favorite topics
Create folders and subfolders
Rename current topics from the default topic title name
Users can access Favorites navigator functionality from the Tools menu of Help Topic window, which displays an Add Favorites dialog, or by right-clicking a favorite in the Favorites navigator.
Unlike Contents, Search, or Index, the Favorites navigator is displayed by invoking the method
enableFavoritesNavigator() URL, which specifies a file,
favorites.xml, to contain favorites information. For more information, see Section 13.4, "Adding the Favorites Tab or Custom Tab"
2.3.5 Custom Navigator Tabs
Among other features, the OHJ API enables you to customize the default OHJ user interface. For example, you can program custom tabs, also called navigators, in Java and add them to the navigator window. Figure 2-8 shows a custom tab Product Education.
Figure 2-8 Custom Navigator Tab in the Navigator Window
Description of "Figure 2-8 Custom Navigator Tab in the Navigator Window"
2.4 Merged Helpsets
A collection of help topics, with their associated control files, is called a helpset. Helpsets can be merged at runtime; multiple authors can create multiple helpsets that are seamlessly merged after authoring completed. Similarly, new components can be added to a user's help system without having to rework the entire system.
Several features support merged helpsets:
The Contents navigator merges helpsets into one tree with the contents from all merged helpsets. As of Oracle Help for Java and Oracle Help for the Web, the Contents navigator merges all tree nodes that have the same labels and do not have conflicting targets.
The index shows the index entries from all helpsets, properly sorted.
The text search searches through all merged helpsets.
Alternatively, authors can specify that selected helpsets are displayed in a drop down list in the toolbar. This can simplify the presentation of a complex help system to the user.
Figure 2-9 Merged Helpsets in a Choice List
Description of "Figure 2-9 Merged Helpsets in a Choice List"
When this implementation is used, the Contents and the Index tabs show only items from the helpset that is selected from the list. The Search text searches only for items in the selected helpset.
When an author provides associative links, the list of topics associated with a link includes items from the merged helpsets.
2.4.1 Merging Table of Contents
Oracle Help for Java and Oracle Help for the Web, both support the merging of TOC files from multiple helpsets to create one tree. The TOC that results from merging multiple tables is essentially the result of laying all trees on top of one another. If multiple TOCs contain identical nodes (nodes that have the same text and target topic Id), then these nodes are combined into one node that has all original nodes' children.
Consider the scenario when you have two helpsets that make use of
<?xml version='1.0'?> <toc version="1.0"> <tocitem text="1" target="1_topic" /> <tocitem text="2" target="2_topic" > <tocitem text="2.1" target="2.1_topic" /> <tocitem text="2.2" target="2.2_topic" /> </tocitem> <tocitem text="3" target="3_topic" /> </toc>
<?xml version='1.0'?> <toc version="1.0"> <tocitem text="2" target="2_topic" > <tocitem text="2.2" target="2.2_topic"> <tocitem text="2.2.1" target="2.2.1_topic" /> <tocitem text="2.2.2" target="2.2.2_topic" /> </tocitem> </tocitem> </toc>
Figure 2-10 shows the TOC that results from merging
toc2.xml. You can see that there is only one node for
2 because the target is
2_topic for both the
<tocitem> items with
text=2. The same applies for the node with
This example assumes that the
<view> elements defining the Contents navigators for the helpsets do not have titles. If a
<view> for a Contents navigator includes a
<title>, then this title is used as a parent node to all
<tocitem> items defined by the
toc.xml file. For more information, see Chapter 5, "Metadata Files".
2.5 Other OHJ Features
Oracle Help for Java (OHJ) features, not otherwise mentioned in this Oracle Help Guide, include the following features:
2.5.1 Accessibility Features
OHJ has the following accessibility features:
All user interface features are keyboard accessible, including the default HTML display component (the ICEbrowser). Oracle has modified the ICEbrowser that ships with OHJ to provide this accessibility support.
The most recent versions of OHJ and of the ICEbrowser have been successfully tested with the JAWS for Windows Screen Reader from Freedom Scientific. For more information, see
2.5.2 Internationalization Features
OHJ has the following internationalization features:
All text strings in the user interface are stored in resource files, for easy translation.
The locale and encoding can be set programmatically.
The default HTML display component (the ICEbrowser) supports wrapping for non-space separated languages.
Help authors can set the
charsetof the HTML file, using the IANA character set encoding names (when using the default ICEbrowser HTML display component).
The OHJ user interface has been translated by Oracle into several languages.
2.5.3 Java Foundation Class (JFC) Swing Components
The OHJ Help system is implemented using Java Foundation Class (JFC) Swing components.
2.5.4 Open, Pluggable Architecture
OHJ has an open, pluggable architecture. That means that you can substitute your own components for default components such as the search facility or the HTML display component. In addition, components such as the Navigator tabs and the HTML display can be embedded into an application's user interface, to provide completely integrated help.
All OHJ application class files, control files, and content files can be encapsulated and compressed into JAR (Java Archive) files. It is not necessary to unJAR these files to run the help system.