Fusion Middleware Documentation
Advanced Search


Developing Help Systems with Oracle Help
Close Window

Table of Contents

Show All | Collapse

3 Oracle Help for the Web User Interface

This chapter describes Oracle Help for the Web user interface components, such as global toolbar, topic navigator, index navigator, and search navigator.

This chapter contains the following sections:

3.1 About Oracle Help for the Web User Interface

The Oracle Help for the Web (OHW) user interface provides the same features as that of OHJ. However, as OHW is a Web application, there are some differences in appearance and behavior.

Figure 3-1 shows OHW in a Web browser.

Figure 3-1 Oracle Help for the Web User Interface

Description of Figure 3-1 follows
Description of "Figure 3-1 Oracle Help for the Web User Interface"

Figure 3-1 numbered callouts identify the following user interface components:

  1. Navigator area: Located on the left side of the page, this area uses the accordions approach, and each accordion panel represents one navigator. The OHW framework provides three standard navigators: Contents, Index, and Search. The exact set of navigators in an OHW instance is dynamically determined from the helpset definition file (for example, the.hs file).

  2. Branding area: Located at the top of the rich client interface, this area can contain text, an image, or both. Typically, this area identifies the help content or provides company information, such as the name and logo.

  3. Toolbar area: Located below the branding area, this area provides the main menu items, a helpset switcher (where applicable), and a quick search control.

  4. Topic view area: When a topic is selected in any tab of the Navigator area, the contents of that topic appear in this area.

With the exception of the branding area, these elements are configured in the helpset file. OHW and OHJ use the exact same file formats, including the helpset file. That means that one can take an existing OHJ help system and deploy it as an OHW system, without changing any of the existing control files.

For more information about deploying OHW system, see Chapter 16, "Deploying OHW Demo File".

3.2 OHW Global Toolbar

The top area of the rich client contains a helpset switcher (where applicable), a quick search control, a View menu that enables users to manipulate areas on the page, and a toolbar.

Figure 3-2 OHW Global Toolbar

Description of Figure 3-2 follows
Description of "Figure 3-2 OHW Global Toolbar"

Figure 3-2 numbered callouts identify the following user interface components:

  1. Helpset Switcher: A dropdown list that contains all helpsets defined in an OHW application. The helpset that is currently open is shown in the dropdown box, and users can use the list to switch to a different helpset. The Helpset Switcher is visible only when there are multiple independent sets of content and the combineBooks parameter, in the ohwconfig.xml file, is set to false.

  2. Search This Helpset: A quick search control that allows users to perform a quick search without switching to the Search navigator. The default search options in this case are set as case insensitive, all words and all sources. If there are multiple search navigators, the quick search control is not displayed. Multiple search navigators can be present when the helpset file contains more than one views with the navigator of type: oracle.help.navigator.searchNavigator.SearchNavigator.

  3. View: A menu that provides a list of command menu items to control visibility and navigation of the helpset. The command items are grouped into similar functionalities as follows:

    • Maximize Reading Pane toggles the expansion or collapse of the navigator pane.

    • Restore Default Window Layout rearranges the panes according to the default layout.

    • The navigator items section contains command items to navigate to all available navigators panes (Contents, Index, and Search, and the custom navigators, if any).

    • Show bookmarkable link for this topic page displays a popup that contains the permanent link to the current topic, which can then be used to create a bookmark.

  4. The toolbar contains the following buttons:

    1. Back To Topic: reopens the topic the user previously visited.

    2. Forward To Topic: reopens the topic the user just returned from.

    3. Print this topic page: prints the current topic.

    4. Email link to this topic page: opens the default email application, copies the URL of the current topic into the message body, and the topic title into the subject field.

    5. Show permanent link for this topic page: displays a popup that contains the permanent link to the current topic, which can then be used to create a bookmark.

A Collapse Pane button is also available to hide the toolbar and maximize the Topic Pane.

3.3 OHW Contents Navigator

The Contents Navigator displays topics in a hierarchical tree. The contents and structure of the tree shows the merged data from the table of contents views in the loaded helpsets. Users can expand or collapse branches of the tree and select leaves (and branches that have associated topics). When a leaf or branch associated with a topic is selected, the topic is displayed in the Topic Pane on the right. A scroll bar, if required, appears when necessary.If the Table of Contents in the Contents Navigator is not visible, use the View menu in the global toolbar to navigate to the tab.

Figure 3-3 OHW Contents Navigator

Description of Figure 3-3 follows
Description of "Figure 3-3 OHW Contents Navigator"

The Contents Navigator is always synchronized with the topic displayed in the Topic Pane. For example, if you click a link in a topic and jump to another topic, the new topic is automatically highlighted in the Contents tab.The state of the Contents tab is maintained even when a user switches between navigators. For example, if a user selects a topic and switches to the Index navigator and back (without opening any other topic), the selected topic, scroll position, and expansion state of the tree remain unchanged. This works with the auto-synchronization functionality.The context menu provides a list of command menu items to control visibility and navigation of the helpset. The items are:

  • Print This Page: prints the contents of the selected topic.

  • Email This Page: opens the default email application, copies the URL of the current topic into the message body, and the topic title into the subject field (also available through the global toolbar).

  • Link to This Page: displays a popup that contains the permanent link to the selected topic, which can then be used to create a bookmark (also available through the global toolbar).

  • Expand: expands the tree to display the child topics of the selected node.

  • Collapse: collapses the tree to hide the child topics of the selected node.

  • Expand All Below: expands all nodes under the selected node to display their respective child topics.

  • Collapse All Below: collapses all nodes under the selected node to hide their respective child topics.

  • Show As Top: displays the current node as the root of the tree.

Note:

The functions provided by the first three context menu items are also available through the global toolbar. For more information, see Section 3.2, "OHW Global Toolbar".

3.4 OHW Index Navigator

The Index Navigator displays a sorted list of keywords, in a hierarchy of two levels. A keyword can be associated with multiple topics. The hierarchy is indicated by indented child items.

Figure 3-4 OHW Index Navigator

Description of Figure 3-4 follows
Description of "Figure 3-4 OHW Index Navigator"

Figure 3-4 numbered callouts identify the following user interface components:

  1. Jump to keyword: The user enters a word or words in this field. 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 the keyword list.

  2. Keyword list: A list that contains a 2-level locale-sensitive collated list of keywords. Selecting a keyword in the list displays the associated topics in the topic list.

  3. Expand/Collapse: Click the button to hide the Keyword List and Jump to keyword text field, and expand the topic list to occupy all Index navigator. The button is useful if you have list of topics for the search keyword and you want to browse through them.

  4. Topic list: A list that displays the title and source of each topic that is associated with the keyword selected in the keyword list. When the user selects one of these titles, the topic is displayed in the Topic pane. Both the Topic and Source columns can be sorted in the ascending or descending alphabetical order.

3.5 OHW Search Navigator

The Search Navigator provides a user interface for constructing a full-text search query. The user may enter multiple words for the search string.

Figure 3-5 OHW Search Navigator

Description of Figure 3-5 follows
Description of "Figure 3-5 OHW Search Navigator"

Figure 3-5 numbered callouts identify the following user interface components:

  1. 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.

    You can also use the * wildcard character in your search string. Note that the support for the * wildcard character is available in between and in the end of the search string, but not in the beginning of the search string. For example, John*Doe and John* are valid search strings, *Doe is an invalid search string.

  2. Source: A dropdown that allows users to specify the set source topics among which the search is to be performed.

  3. Match: A dropdown that allows users 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).

  4. Case Sensitive: A checkbox, when selected, enables searching for words having the same case as the words entered by the user.

  5. Expand/Collapse: Click the button to hide the Search text, Source, Match, and Case Sensitive fields; and expand the topic list to occupy all Search navigator. The button is useful if you have list of topics for the search keyword and you want to browse through them.

  6. Topic List: The results area displays the Topic Title, Score and Source of each topic that matches the search criteria. The Score 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 Score. When a user hovers the mouse on an item, a tooltip appears to show the full names of relevant folders, topics, and source data. When the user selects a particular result, the associated topic is displayed in the topic pane.

The Oracle Help for the Web includes the Oracle Help Full Text Search indexer that adds word position information into the IDX files. The Oracle Help Full Text Search indexer enables exact phrase searches and improves the result ranking mechanism (giving more points if the search terms are found near to each other). To search for an exact phrase, place the phrase in double quotes. For example, "John Doe".

Oracle Help for the Web can also read IDX files created with previous versions of the Oracle Help Indexer, and enables you to use both old and new IDX files together, if required. Using an IDX file created with the new indexer, of a previous OHJ or OHW release, is not supported and raises a SearchException exception to be logged stating that the IDX version is not supported.

Note:

The IDX files created with Oracle Help Full Text Search indexer are not backward compatible. The indexer gives an error if you use an IDX file created with the current indexer, with an old version of Oracle Help for the Web.

3.6 OHW Topic Pane

The Topic pane displays the HTML help content.

The Topic pane has its own toolbar to manipulate the currently displayed topic. Figure 3-6 numbered callouts identify the following user interface components:

  1. Find in page: The user enters some specific text, which is to be searched in the topic content, in this field.

  2. Next: Searches for the next occurrence of the text specified by the user, and highlights the same if a match is found.

  3. Previous: Searches for the previous occurrence of the text specified by the user, and highlights the same if a match is found.

  4. Topic Pane: The pane with the help content.

3.7 Other OHW Features

OHW features, not otherwise mentioned in this Oracle Help Guide, include the following.

3.7.1 About OHW Feature

The About OHW feature displays information about the OHW help system, Oracle copyright information, and the OHW build you are using.

Note:

Oracle Help for Java supports the About OHW feature using the request query parameter aboutOHW.

To view the About OHW page, the user must navigate to the following URL:

http://localhost:<port_number>/<help ohw-rcf context-root>/faces/helppages/main.jspx?config=OHW+Servlet+1&aboutOHW=true

Upon navigating to this URL, the Topic pane displays the current OHW build information along with copyright information.

Figure 3-7 About OHW Window

Description of Figure 3-7 follows
Description of "Figure 3-7 About OHW Window"

3.7.2 Bookmarking Feature

Users can bookmark a page, and the same topic is displayed when navigating to the bookmark. Users can also save a URL link and send the link by email. The following points must be noted for Bookmarking feature:

  • To bookmark a page, users must use the Show permanent link for this topic page button on the global toolbar, which refreshes the rich client URL to a bookmarkable URL. Users can then use then browser's bookmarking feature to save the URL.

  • The state of the Index and Search navigators are not a part of the bookmark information. The Contents navigator is automatically in sync with the displayed topic.

3.7.2.1 Backward Compatibility

A bookmark from OHW can display the same topic view in OHW given the topic ID, group, and locale. However, as OHW bookmarks have many other parameters besides the ones that are supported, the state of all navigators may not be restored.

OHW URLs indexed by search engines continue to link to valid help content.

3.7.3 Single Pane Layout Feature

Users can view the current topic in a single pane layout by altering the URL.

For example:

topicId

http://localhost:7101/help-ohw-rcf-context-root/ohguide/?topic=ohg_about_about_html&linkHelp=false

vtTopicFile

http://localhost:7101/help-ohw-rcf-context-root/ohguide/?vtTopicFile=ohguide/ohg_about_about.html&linkHelp=false