Methods for Integrating Oracle Forms with Online Help

Janice Carlson and John Lennon

Introduction

Oracle® Designer provides the ability to generate online Help. But can it create a Help system with the kind of features, accessibility, and razzle-dazzle that your clients may expect? A Help authoring tool can let you do just that.

This presentation provides an introduction to Help authoring tools and describes methods for integrating online Help with Oracle Forms.

Help Authoring Tools

The Help author has a handful of Help authoring tools from which to choose, including RoboHELP®, ForeHelp®, and Doc-to-Help®. Less costly shareware is also available. While each has its own strengths and weaknesses, the basic functions of any tool are to:

n         Provide a user interface that simplifies the process of creating and compiling a Microsoft Windows Help (WinHelp) system.

n         Allow the author to concentrate on content and clear, concise writing by reducing the time-consuming mechanics of generating the Help system.

The good Help authoring tool provides much more, by assisting the author to:

n         Assign a full range of Help features.

n         Add navigation to the Help system.

n         Integrate online Help with other technical and user documentation.

Information about authoring tools contained in this article is based on the capabilities of Blue Sky® Software Corporation’s RoboHELP. (According to International Data Corporation, Blue Sky outsells its nearest Help authoring tool competitor by two to one.) To quote Blue Sky, “RoboHELP turns Microsoft® Word into a full-featured authoring tool, allowing you to create state-of-the-art Help systems for Windows 95, Windows NT, and Windows 3.1, printed documentation, web sites, Microsoft HTML Help, and Netscape NetHelp.”

How Help Authoring Tools Work

A Help authoring tool like RoboHELP provides an easily mastered interface between the Help author and WinHelp’s stringent requirements. Features of a Help authoring tool assist in Help system development from the micro (creating a Help topic) to the macro (managing the Help system).

A Help authoring tool will assist the author to complete efficiently the following tasks:

n         Convert documents and graphics to the formats required by WinHelp

n         Create and modify Help topics

-         Assign browse sequences

-         Define topic keywords

-         Specify target windows

-         Add entry macros

n         Add jumps, popups, graphic and authorable buttons, and multimedia

n         Develop and manage a Help project

-         Create and maintain a Table of Contents

-         Create and maintain Index entries

-         Define main and secondary windows

-         Manage graphics files and external Help files

-         Assign start up macros, such as adding an Exit button to the main window

-         Compile

-         Manage DLLs

Many of these functions are discussed in more detail in the pages that follow.

Help Features

These features are almost shamefully easy to include in your system using a Help authoring tool, yet they provide the look-and-feel that users expect from a quality Help system.

Main Window

The main window is a fixed-size window. Typically, it is larger than a secondary or popup window. Microsoft recommends that the main window be reserved for background information or for large blocks of text, but this can prove limiting.

We have found it more practical to display step-by-step instructions in the main window. This makes it possible to display the procedures for a complete task, such as preparation instructions for a form, within a single screen, eliminating the need for the reader to scroll through multiple screens.

The main window is also suited for displaying the contents of the Help system. Figure 3 illustrates how a watermark graphic, implemented using a .DLL packaged with RoboHELP, adds visual impact.

Secondary Windows

Various types of secondary window can be defined for the Help system. Microsoft’s opinion is that these smaller windows should be reserved for step-by-step instructions. Based on your Forms application, this could be impractical. We prefer to use a secondary window to assist the reader navigating within the Help system.

Another use of a secondary window is to provide context-sensitive Help. This avoids a WinHelp limitation associated with using a popup window for context-sensitive information. The example in Figure 5 appears when the user clicks the Help button on the tool bar, selects Topic from the Help menu, or presses the F1 key within a field (text item).

Popups

Popups are small, self-sizing windows that appear on top of the current application. They typically contain definitions or context-sensitive data. As shown in Figure 6, a popup window is used effectively to display table data that would be distracting or awkward to include in a main or secondary window. 

Authorable buttons—such as buttons that provide a jump to another Help topic—do not function as expected in popup windows. This limits the reader’s ability to navigate from the popup to other information that may be required to complete a task.

Assigning Windows

Each Help topic can be assigned to a specific window. RoboHELP, though, provides the flexibility to override this assignment when the topic is referenced using a hypertext link.

A powerful feature of RoboHELP is that it allows the author to use the same Help topic in a number of ways. A single topic might appear as a popup when accessed from a hotspot graphic or Glossary, and then appear within a main or secondary window when accessed from the application or selected from a menu or the Index.

Graphics

Used judiciously, such as to highlight an important feature of a form or window, graphics vividly and speedily convey information to the reader. While an unlimited number of graphics can be included in the Help system using RoboHELP, their size and frequency are restricted based on commonsense principles. For example, the reader should never need to use the horizontal scroll bar to view an image in its entirety.

Hotspot graphics, assigned by associating a portion of the graphic with a Help topic as a jump or popup, provide an interesting, interactive element to your system.

Another useful hotspot graphic is the graphical button. With the custom DLL provided by RoboHELP, you can place your own bitmap on a button and attach a macro—to jump to another Help topic or even open a Word or Excel file—that executes when the reader presses the button.

Browse Sequences

Assigning Help topics to a browse sequence gives the reader the opportunity to obtain additional information related to a topic. The reader simply clicks the forward or backward Browse button to move through the topics contained in the sequence.

Text Searches

Both keyword and full-text searching are available by assigning keywords to a topic. Yes, you can do this using WinHelp, but it is easier and faster with a Help authoring tool.

The reader most commonly approaches the Help system using its Index. Since first impressions are important, it is critical to assign keywords meaningful to the average reader. When the reader is unsuccessful at finding a topic using the Index, the typical response is to use the Find tab, which provides a full-text search of the Help system.

Help Navigation

Like a good Web site, the well-crafted Help system acknowledges that the reader may find navigation within the system perplexing or even annoying. By providing standard navigation features, such as consistent, meaningful buttons, graphics, and menus, the author increases the reader’s comfort with the presentation of information and enhances use of the Help system.

Navigation using Buttons and Graphics

Figures 8 through 10 illustrate the variety of buttons that the Help author can use to help the reader navigate and locate information.

The reader clicks the mini-button to jump to the Contents window.

The reader clicks within the graphic to jump to the desired alphabetic Glossary entries.

The reader clicks the Related Topics button to display a list of topics containing related or supplemental information.

While there are a number of buttons and graphics available to the author, it is preferable to limit these types of aids to a consistent set, to avoid confusing the reader and for ease of maintenance.

Navigation using Menus

Menus can be used both for overall navigation to the Help system and for navigation within primary sections of the system. In the secondary menu contained on the right side of the sample screen in Figure 11, each menu entry contains an invisible hypertext link to the corresponding topic. The secondary window thus serves two purposes; it provides the table of contents for the section, and can be used by the reader to selectively navigate through the topics contained in the section. This menu remains in place until it is manually closed by the reader or replaced by another of the same type of secondary window.

Using RoboHELP, this processing is defined by adding an entry macro to the topic displayed in the main window. The macro automatically displays the specified secondary window whenever the reader accesses the main window.

Other Navigation

Navigation features found in a typical Help system include these toolbar and menu options:

n         Back and Exit buttons.

n         Index and Find buttons, used to locate information by keyword or full-text search.

n         Browse (×Ø) buttons, used to scroll through the Help system.

n         Bookmark menu, used by the reader to bookmark information that is used frequently.

RoboHELP provides a simple-to-use interface for each of these features.

About Context-Sensitive Help

There are two types of context-sensitive Help:

n         Item-level Help provides information about each item in a dialog box, typically displayed in a popup window. With it, you adhere to Windows 95 and NT conventions.

n         Window-level Help provides a topic containing information about the entire dialog box, usually displayed in a main or secondary window. This is the standard for Windows 3.1 applications. Because it requires fewer Help topics to be defined and indexed, Window-level Help can be developed more quickly than item-level Help.

Whether you are using item- or window-level Help, the context-sensitive Help system requires communication and cooperation between the Help author and the developer.

The Help author and Forms developer can elect to include context-sensitive Help for an application by using map files or passing keywords.

Map Files

When using a map file, each topic is assigned a map number. There are two alternatives for applying map numbers.

n         RoboHELP generates a map file containing a map number for each topic. The application developer assigns the map numbers to specify the context-sensitive topic to be displayed by Help.

n         The developer provides a map file, and the Help author uses RoboHELP to assign the map numbers to each context-sensitive topic.

Map files are by necessity external to both the form and the Help project, representing an item to be maintained throughout the life of the system. For this reason, the authors did not elect to use map files to provide context-sensitive Help.

Passing Keywords

The second method for adding context sensitivity is for the Forms application to pass a keyword to the Help system. This simulates the process by which the reader selects a topic, identified by a keyword, from the Index.

One benefit to using keywords is that these are meaningful terms to the Help author and the Forms developer, rather than a string of arbitrarily assigned numbers. Consequently, they pose fewer problems when maintaining the Help system and Forms application.

Writing Help

Even the best Help authoring tool cannot guarantee the success of your Help system. If your readers encounter inaccurate or imprecise instructions or confusing terminology, they are apt to ignore online Help and seek assistance from other, more costly sources, such as fellow workers or the Help desk.

Fortunately, applying a few simple guidelines to your written instructions can eliminate unnecessary problems and enhance the credibility of the Help system.

The following checklist for reviewing written instructions, and other useful reference material for the Help author, is provided in Standards for Online Communication.

n         Phrase procedures in user terms.

n         Number each step that users must perform.

n         Limit each numbered step to a single action.

n         Present steps in the order in which users must perform them.

n         Try to write no more than five action steps for each procedure.

n         Start steps with imperative verbs.

n         Keep steps short.

Accessing Help

The Forms developer has the easy task of calling the Microsoft Help API from the Forms application. Microsoft provides the necessary interfaces: user.exe for Windows 3.x and user32.dll for Windows 95 and NT. The appropriate interface is called using functions based on the ora_ffi library. As developers, we do not have to write these; Oracle provides them as part of the demonstration and reusable code included with Developer/2000.

Forms Library

There are numerous ways to implement calls to the Help system. The method shown in Figure 12 uses a Forms library (.PLL), and the only code contained in the forms are calls to the library procedures. This method is used throughout our forms for common code, and has the advantage of ease of maintenance. The code is all in one place, and only one place. If a major change is required in the future–such as a conversion to HTML Help–it can be implemented without modifying every form. The path and filename of the application’s Help file are assigned to a global variable during application initialization.

The library in Figure 12 has two packages, FORM_HELP and WINHELP.

FORM_HELP provides the interface between the forms and Oracle’s package WINHELP, which in turn interfaces with the Microsoft API. (Note that there are constants for each WinHelp function; the list contained in Figure 12 is condensed for brevity.)

Program Units

The Forms_Help package contains the following procedures, used to call the WinHelp package’s public function, call_help.

Help_Form

This procedure passes the help_partialkey constant and the tile of the main window of the form (get_window_property) to call_help. WinHelp locates the topic in the Index and displays the appropriate window, in this case general information about the form.

Help_Contents

This procedure passes the help_contents constant to WinHelp and displays the Contents window, as shown in Figure 3 on Page 2.

Help_Topic

This procedure is used to achieve context-sensitive Help. A topic is specified in the code and passed to WinHelp, which attempts to navigate directly to the topic window. If there is no match, the Index is displayed with the nearest match highlighted.

There are various methods of determining what to pass as a topic; these are a matter for agreement between the Application and Help teams. The easiest and perhaps most commonly used method is to simply use :system.cursor_item. However, this can result in an Index that is ugly and largely unintelligible to the user unless an unwieldy cross-index is maintained.

The method preferred by the authors is to use keywords in the hint property of the text item. These keywords have an exact match in the Help Index, and are parsed from the hint text and passed to WinHelp. (See Figure 14.) The hints have to be individually entered in any event, and the additional work is minimal.

Help_On_Help

This procedure navigates the user to Microsoft’s Help for using Microsoft Help. Here the user can learn how to use and customize Help by adding annotations and bookmarks.

Help_Quit

This procedure is called in a post-forms trigger to ensure that WinHelp is closed when the user exits. If forms are to run standalone, it should be incorporated in every form. Otherwise, it should be called in the controlling form.

The User Interface

The first step is to add a form level KEY-HELP trigger. This trigger fires when the user presses the Help button on the tool bar, selects Topic from the pull-down Help menu, or presses the Help (F1) key. This trigger calls the Help_Topic procedure to provide context-sensitive Help.

Next, to provide full access to the Help system, create a customized pull-down menu. It is easy to add menu items to the sample menu provided by Oracle. Menu items are defined as:

Menu Item Type = Plain

Magic Item = None

Command Type = PL/SQL

and the appropriate call to the Form_help library is entered as the PL/SQL command. Attach the menu to every form by specifying it in the form level properties as usual.

Most applications include an About option on the Help menu. This tells the user as little–or as much–as the developer chooses. It might state something like “Time Reporting System Version 2.1 - Copyright XYZ Software Inc. 1998,” or it could go into considerably more detail. At its simplest, the About window would be just another Help topic, as shown in Figure 17.

The application the authors are currently building is a large work management system, which will have over a thousand users in three states. To enable the Help desk to assist users, it was considered important to display as much information as possible, not just about the application, but also about the users and their environment.

This is achieved by including a modal window and an associated block in our reference form. This block is referenced (sub-classed in Forms 5) in every form. The code behind the About item on the Help menu causes the window shown in Figure 18 to be displayed.

The Future of Help