Adding Online Help to Your Applications

Introduction

You can add online Help to your applications to provide assistance to your users. SAS/AF software supports help in several formats, including HTML-based Web pages and SAS/AF CBT catalog entries. Your applications can also take advantage of context-sensitive help and tooltips.

When you implement a Help system for your application, you should consider

how much detail you want to add to the help
whether or not context-sensitive help is required (so that you can make the necessary changes to frame and component properties)
what functionality the various help commands provide and how you can use them appropriately
how your help files are structured and stored

Adding Help to a Frame

You can add help to a frame by setting its Help attributes. To display the attributes in the Help category, expand the Attributes tree in either the Properties window or the Class Editor and select the Help node. You can set the following attributes:

CBTFrameName

Set the CBT frame name that you want to display if you are using SAS/AF CBT entries to deliver your help information. This attribute is valid only if a CBT entry is assigned for the frame's help attribute.

help

Set the frame's help attribute to specify the type of help and the item to display when help is selected. If you select a SAS catalog entry as the type of help, SAS/AF assumes that you want to display a CBT entry. Other types of help provide different ways of displaying help in a browser. For details on the types of help, see the help attribute in the Frame class.

showContextHelp

Set this attribute to toggle the display of the question mark control button (?) in the window border of the frame. Set this attribute to Yes if

your frame's type attribute is set to “Dialog”
you have defined help for components on your frame
you want the HELPMODE command to recognize context-sensitive help selections

Attaching Context-Sensitive Help to Frame Components

You can add context-sensitive help for components on a frame by using the “What's This” type of help for a component, for status-line messages, and/or for tooltips. You must set the appropriate attribute in the Properties window if you want to specify help for a component. You can set the following attributes:

CBTFrameName

Set the CBT frame name that you want to display if you are using SAS/AF CBT entries to deliver your help information. This attribute is valid only if a CBT entry is assigned for the component's help attribute.

help

Set the component's help attribute to specify the type of help and the item to display when help is selected. If you select a SAS catalog entry as the type of help, SAS/AF assumes that you want to display a CBT entry. Other types of help provide different ways of displaying help in a browser. For details on the types of help, see the help attribute in the Object class.

helpText

Set the component's helpText attribute to specify a message to display on the status bar when a user positions the cursor over the component.

toolTipText

Specify the text that you want to appear as a tooltip for the component. A tooltip (also known as “balloon help”) is presented as pop-up text when a user positions the cursor over the component for a particular time interval.

Calling Help from Your Application

SAS/AF software provides several commands that you can use to display help for your application. You can add these help commands to a menu item, or you can assign one of them as the command that is executed by a control such as a push button. You can also attach the commands to icon buttons on a toolbar.

The commands include

HELP

The HELP command displays help for the active frame or window based on the values of the frame's Help attributes. The Help topic or topics are displayed in the designated help browser.

The WINDOWHELP command performs the same function as HELP.

HELPMODE

When the HELPMODE command is issued, SAS enters object help detection mode (helpmode). In helpmode, the cursor changes to a question mark (?) and SAS waits for the user to select an object on the active frame. When a user selects an object while in helpmode, SAS displays the help that is defined in that object's help attribute.

WBROWSE valid-URL

The WBROWSE command simply displays a valid URL, which can be any page that can be displayed by the associated Web browser.

The HELP command can be used in conjunction with the HELPLOC:// protocol to display a specific Help topic. The HELPLOC:// protocol is a mechanism defined by SAS for displaying help files from within your application. For example, help helploc://myapp/intro.htm opens the Help topic that is stored in the HTML file named intro.htm.

To specify the location of the help files for your application, you must add the appropriate path in the HELPLOC system option in the configuration file that is used to start your application.

Note: SAS/AF software uses the HELPLOC option to identify the path it searches to locate online Help files. The default path for SAS online Help is a format such as

!SASROOT/X11/native_help

!sasroot\core\help

If you modify or remove this path from the HELPLOC option in your software configuration file (instead of in your application's configuration file), SAS software cannot locate its associated online Help.

You can add multiple search paths to HELPLOC. The SAS Help facility replaces the HELPLOC:// protocol with a path listed in the HELPLOC option. The paths are searched in the order in which they are listed until the valid Help topic is found or until there are no further paths to search. For example, if your HELPLOC option contains

('!sasroot\core\help' '!sasuser\classdoc')

you could add a path to the directory in which you stored the help for your application:

('f:\apps\myapp\help' '!sasroot\core\help' '!sasuser\classdoc')

The SAS Help facility will then search through f:\apps\myapp\help to locate a Help topic before it searches the SAS online Help path (!sasroot\core\help).

A path specified in the HELPLOC option does not have to be a local directory. It can also be a path on a valid Web server or a path to a network directory. For example, consider a HELPLOC option that is defined as

('!sasroot\core\help' 'http://mycompany.com/intranet/apphelp')

and a help call from a SAS/AF frame that uses the form

help helploc://myapp/intro.htm

In this example, the SAS Help facility will first search for the requested Help topic in the SAS online Help path. Then it will send a fully qualified URL to the browser to locate the Help topic at

http://mycompany.com/intranet/apphelp/myapp/intro.htm

See Configuring a SAS Session for Your Application for information on customizing the configuration file.