Using Context-Sensitive Help Features

The Toolkit provides features to hook in context-sensitive HTML help based on your Java™Server Pages (JSP) pages. To use these features, you must understand how the controller framework retrieves help files, uses a help mapping file, and determines the location of help files.

NOTE  If you are modifying the FileNet P8 Workplace application, you can tailor the supplied help content to reflect your changes. The context-sensitive help files for Workplace are located on the FileNet documentation server in the <app_root>/ae_help/workplace/<subdirectories> directory.

The subdirectories correspond to the locations of the JSP pages in the FileNet P8 Workplace application. All context-sensitive help files are prefixed with "Wcm", for example "WcmAddFavorite.htm".

How a Help File is Retrieved

The diagram below summarizes the process for serving up context-sensitive help pages from the Toolkit framework. When a user selects a help link from an HTML page, the following steps occur:

  1. Event is targeted to the WcmController.onHelp handler.
  2. WcmController.onHelp(...) gets the name of the help page. By default, this is the name of the current JSP page. The name of the help page will be used as a help key into help_map.properties, the help mapping file.

    Note that your application can override the default help page name by calling WcmController.setHelpPage(...).

  3. WcmController.onHelp(...) gets the help context, if any, and concatenates it to the help page. The help context is intended for use by container classes that encapsulate different UI panels, each of which requires its own help page. In the FileNet P8 Workplace application, the WcmInfoModule and WcmWizardModule are examples of container classes that set the help context so that the appropriate help page is associated with the currently displayed UI panel. (These classes derive from WcmMultiPanelModule, and WcmMultiPanelModule.render(...) calls WcmController.setHelpContext(...).)
  4. WcmController.onHelp(...) calls getHelpURL(...), which initiates the work of getting the context sensitive help URL for the current page.

    getHelpURL(...):

  5. WcmController.getHelpURL(...) passes the help key, server location to WcmHelpMap.getQualifiedHelpURL(...). WcmHelpMap.getQualifiedHelpURL(...) uses the help key to get the help file name from the help map (help_map.properties). If the key is not found in the help map, the key will be used as the help file name.

    Note that the fully qualified URL includes the help root path and the extension of the help file. These values are set in the help map with reserved keys. WcmHelpMap.getQualifiedHelpURL(...) returns the fully qualified URL of the help file to WcmController.getHelpURL(...), which returns it to WcmController.onHelp(...) .

  6. WcmController.onHelp(...) redirects the help file URL to the client browser, which displays the help topic in a secondary window.

how help pages are called

Help Mapping File

To locate a context-sensitive help file, the controller framework uses a help mapping file called "help_map.properties", located in the <app_root>/WEB-INF directory. The help mapping file consists of key/value pairs. The controller framework uses a key based on the name of the current JSP page to look up the name of the context-sensitive help file associated with the JSP page. For example, in the following key/value pair, if the controller framework were searching for the help key on the left (browseDocuments), then it would include the help file value on the right (browseHelpTopic) in the URL returned to the session requesting help. (Note that the key and value can be the same (browseDocuments=browseDocuments)).

browseDocuments=browseHelpTopic

This topic discusses key/value pair rules, default behavior for missing help keys, and reserved keys used to specify the help root path and the extension of the help files.

NOTE  The name and path of the help mapping file are hardcoded in the com.filenet.wcm.toolkit.server.util.WcmHelp class. To specify a different name and location for your help mapping file, you must modify the WcmHelpMap source.

Key/Value Pair Rules

For key/value pairs in help_map.properties, the following rules apply:

JSP Directory Help File Directory Key / Value Pair
Workplace <help_root>/ae_help/workplace help_key = help_file_value
Workplace
  /operations
<help_root>/ae_help/workplace
  /operations
operations/help_key = operations/help_file_value
Workplace
  /eprocess/common/html/ootb
<help_root>/ae_help/workplace
  /eprocess/common/html/ootb
eprocess/common/html/ootb/help_key =
eprocess/common/html/ootb/help_file_value
Key/Value Pair Examples

The following examples illustrate the rules for entering key/value pairs. The examples are from the help_map.properties file included with the FileNet P8 Workplace application.

Default Behavior for Missing Help Keys

If the controller framework cannot find a specified help key in the help mapping file, it will search for the help file based on the name of the help key. For example, if the help key is "operations/WcmAddFavorite", the framework will search for a "WcmAddFavorite.htm" file in the "operations" directory.

NOTE   You can leverage this default behavior for missing help keys to minimize the number of key/value pairs in the help mapping file. Given that the framework looks for a context-sensitive help file based on its help key string, you only need to enter key/value pairs for help files with names different from their corresponding JSP pages. In addition, you can immediately identify a help file named after its corresponding JSP page.

Reserved Keys

The help mapping file, help_map.properties, includes the following reserved keys:

Help Location Options

You can include your context-sensitive help as part of your application, or you can install your help as a separate Web application, as is the help for the FileNet P8 Workplace application. In either case, you must configure your Web application with the location of the help, or place the context-sensitive help in a "help" directory (<app_root>/help).

The controller framework concatenates the following settings to determine the location of context-sensitive help:

If the value of the documentationServer key is...

http://helpServer:8080/ecm_help

...and if the value of the helpRootPath key is...

csHelp

...then the resulting concatenation of the two values will be:

http://helpServer:8080/ecm_help/csHelp

If you don't set the documentationServer key, the controller framework defaults to the application root of your application plus the value of the helpRootPath key; that is, http://<host:port>/<app_root>/ + <helpRootPath_value>.

If you don't set the helpRootPath key, the controller framework defaults to the value of the documentationServer key plus "/help"; that is, <documentationServer_value> + /help.

If you don't set either key, the controller framework defaults to the application root of your application plus "/help"; that is, http://<host:port>/<app_root> + /help.