Providing Context-Sensitive Help for Web Applications

RoboHelp authors need to have a thick skin. Face it. Web application users often access online help only as last resort. For some, it's an admission of defeat. To ease that frustration, a RoboHelp author can provide online help when and where the user needs it. Using context-sensitive help (CSH), an option available in Macromedia RoboHelp, is a technique for satisfying a user's quest for answers.

This article applies to non-programming RoboHelp authors and explains how to provide context-sensitive help to web application users. It also shows web developers how to use the WebHelp API to display context-sensitive topics in special windows, defined by the help author.

You can download the sample web application as well as a RoboHelp project to practice creating context-sensitive help. I've provided Captivate demos to help you understand the process—these "show me" demos make the process clearer.

In this tutorial, you will learn the following:

• How to work with application developers and provide context-sensitive help
• How to design a familiar pattern for users to access help topics
• How to create windows of a special size and place them onscreen where you want the help topic to appear
• How to use RoboHelp to create map files automatically (special code that programmers use to bring your design to life)
• How to use conditional build tags to provide both window and field-level help output from a single project source
• What to provide web developers so they can implement the process

Requirements

To complete this tutorial you will need to install the following software and files:

RoboHelp Office X5

• Try
• Buy

Tutorials and sample files:

• context_help_pt1.zip (ZIP, 2.5 MB)

  This ZIP file contains the entire RoboHelp Office X5 project source code so that you can follow along with this tutorial. Unzip the file into a folder of your choice. Subfolders will automatically be created. Double-click the file bdbhelp.xpj to view the project in RoboHelp Office X5.

• context_help_pt2.zip (ZIP, 2 MB)

  This ZIP file contains the Builder Data Bank sample web application. It is a simulation; only the default.htm page is intended to work with the Help links. Builder Data Bank is a web application that helps architects and home builders keep track of thousands of graphic files. (View and test the real application online at www.johndaigle.com/bdb.) These files include graphic formats such as DWG, JPG, GIF, TIF, PSD, and countless others. Uploading these graphics, storing them, and being able to search and retrieve a particular file is crucial to a home builder's efficiency. As with many applications, there are novices and power users.

  Unzip the file into a folder of your choice. Subfolders will automatically be created. Click the default.htm file to view the web application in your browser (Microsoft Internet Explorer 6 preferred) and to see how the help links work.

Note: Because context-senstitive help appears in JavaScript pop-up windows, you must turn off or disable any pop-up blockers that may be installed in the browser.

Author and Developer: A Context-Sensitive Partnership

Typically web applications use a dynamic, database-driven scripting language such as Macromedia ColdFusion (CFM). Among others are Microsoft Active Server Pages (ASP), JavaServer Pages (JSP), PHP pages, and many others. Web application developers or programmers often use a scripting language to make context-sensitive help topics appear in a window that opens adjacent to the user's workspace.

Determining the Help Access Points

As you can see in the Builder Data Bank scenario (see Figure 1), an author and developer agree to provide three access points to help:

• Help link at the top of the main menu on each screen to show window-level help topics
• Tip link to field level context-sensitive topics
• Show Me link to Captivate demos

Figure 1. The Help access design, showing three links to context-sensitive help topics

Use the following steps to bring the design in Figure 1 to life:

Play the demo: Accessing Help in a Web Application

Creating a Single-Source Project

Once the documentation is written, edit the topics to accommodate two conditions (see Figure 2):

• Show Me link placement in topics that contain Captivate demos or simulations
• Close This Window button placement in designated field-level topics

Figure 2. Graphics and buttons should appear conditionally, based on the user's actions

However, having these two elements (Show Me graphic and Close This Window button) in the same topic could be difficult to manage. This is because the window-level help that appears from the Help link should contain the Show Me link, but not the Close This Window button.

On the other hand, the opposite is true for the field-level topics! This seems to defeat the goal of keeping the project as a single source without duplicating topics. Fortunately, RoboHelp provides a two-part solution:

• Creating conditional build tags for the two variables
• Creating single-source layouts for window-level and field-level output

Defining Three Windows to Display Topics

In the RoboHelp Project Manager, open the Windows virtual folder and create three new windows, as shown in Figure 3. You can look under the hood and review specifics in the downloadable project itself to see precisely how this is done.

Figure 3. Windows virtual folder in the Project Manager

The Help link at the top of each page of the application will display help in a two-pane window with a TOC/Index/Search pane (see Figure 4).

Figure 4. WithNavPane window showing the full navigation pane

The Tip link will display the field-level topic in a minimalist pop-up window (see Figure 5).

Figure 5. NoNavPane window showing no menus or buttons

For the FieldLevel window to be cross-browser compatible, it is a good practice to include a Close This Window button to ensure that the help window does not fall behind the main window.

The Show Me link directs users to Captivate demos or simulations, which open in a sized window (see Figure 6).

Figure 6. ClickMove window showing topics with animation

Notice that the included sample RoboHelp project has two single-source layouts: one for window-level output (MainHelp) and one for field-level output (FieldLevel). The main reason for this is to provide more detailed information in window-level output to exclude from the field-level version, along with the Close This Window button.

Creating Conditional Build Tags

From the Program Manager, right-click the Conditional Build Tags virtual folder and create two tags, as shown in Figure 7. Assign the tags to the conditional content within the topics.

Figure 7. Conditional Build Tags allow the creation of different output from the same source project

Following the actions in this step accomplishes two things:

• Assigns QuickDemo to the Show Me demo icons
• Assigns CloseWindow to the Close This Window button

Play the demo: Applying Conditional Build Tags

Creating a New Map File and Assigning Numbers to Help Topics

Open the virtual Context-Sensitive Help folder and then open the Map Files folder (see Figure 8). You will see that BSSCDefault.h is the standard map file that comes with RoboHelp, although you could create your own or import one from a developer.

Figure 8. Map Files folder with the default BSSCDefault.h map file

Double-click All Map IDs to open the Edit Map IDs dialog box. The Map File pop-up menu showing <Project Map File> refers to the BSSCDefault.h map file.

Select topics in the right pane of the dialog box and click the Auto-Map button to assign a number and context ID to each topic required:

Play the demo: Using the Edit Map IDs Dialog Box

Generating Window and Field-Level Versions of WebHelp

Now that you have assigned the conditional build tags and defined the windows, it is time to create single-source layouts. In the sample project, they are named FieldLevel and MainHelp (see Figure 9).

Figure 9. Single-source layouts

Play the demo: Defining Window Size and Position

Giving the WebHelp API and Documentation to the Developer

The WebHelp Application Programming Interface (API) includes a number of prepared functions, libraries, forms, and code appropriate for a number of platforms, including the following:

• Web pages with JavaScript
• C++
• Visual Basic
• Java applications

Most commonly, developers use the JavaScript file. By default, you can find it here:

C:\Program Files\RoboHelp Office\CSH API\RoboHelp_CSH.JS

Following the provided Builder Data Bank sample application, you must place RoboHelp_CSH.JS in the application path. Place a link to that file between the <head> tags of each application page:

<head>
 <script src="RoboHelp_CSH.js"></script>
</head>

The developer calls the topic within the application's page by creating a link, as follows:

<a href="javascript:RH_ShowHelp(0,'WebHelp/default.htm>WithNavPane', HH_HELP_CONTEXT, 5)">Help</a>

Documentation outlines the flexible choices available to the developer depending on which platform he or she uses to create the application.

Generating Reports to Help Developer Map Topics to the Application

Select Tools > Reports > Map IDs to generate a Map ID and number report. You can then copy it into a Microsoft Word document so that the author can add comments on a topic-by-topic basis, including the name of the window for displaying a particular topic.

Validating the Links and Testing for Usability

Once the developer has coded the links, validate the links by testing them in the application.

There is no substitute for testing the usability of your design with real users as soon as it is possible to create a prototype, along with a beta version of the application. This will reveal red flags and provide clues as to the areas needing the most revisions.

Where to Go from Here

• RoboHelp Help Community

About the author