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:

Event is targeted to the WcmController.onHelp handler.
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(...).
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(...).)
WcmController.onHelp(...) calls getHelpURL(...), which initiates the work of getting the context sensitive help URL for the current page.
getHelpURL(...):
- checks the <AE_deploy_path>/FileNet/Config/AE/bootstrap.properties for the server location of the help. If a server location has not been set, the server (host:port) location of your web application is assumed.
- creates a help key based on the help page and help context.
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(...) .
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:

For the help key, specify the JSP file that invokes the components that the help file describes. Exclude the "jsp" extension. (If your application uses WcmController.setHelpPage to override the JSP file name, then specify the override value.)

For the help file value, exclude the extension, for example, "htm".

The default help file extension is "htm". If you use a different extension for your help files, you must specify it with the helpExtension reserved key in help_map.properties, as described in Reserved Keys.
Named anchors are supported in Web Application Toolkit version 3.0 and later. Therefore, if you want client browsers to jump directly into a specific section on a page, you must include the anchor name in the key/value pair, for example:
```
browseDocuments=browseHelpTopic#middle
```
If necessary, include the subdirectory of the help file to correspond with the subdirectory of the JSP page in the key/value pair. For the help key, the specified JSP subdirectory must be relative to the application root directory. For the help file value, the help subdirectory must be relative to the root path of the help files, as specified in the helpRootPath reserved key in help_map.properties. See Reserved Keys.

In the FileNet P8 Workplace application, the application root directory is Workplace, and the default help root path is <help_root>/ae_help/workplace. Using directories from the FileNet P8 Workplace application as examples, the following table shows the relationship between the JSP directory, the corresponding help file directory, and the associated key/value pair.

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

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

If necessary, include a help context in the help key. For some JSP pages, the help key must be qualified with a help context as follows:
```
JSPpage_helpContext
```
where:

JSPpage is the name of the JSP file, as described above.

helpContext is a substring that is only required when the JSP file invokes a container class for multiple UI modules, each rendering a different view and, therefore, a different help link. The helpContext substring must be preceded by the underscore delimiter ( _ ). In the FileNet P8 Workplace application, numerous container classes are used, such as for the information and wizard pages.

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.

WcmAuthor=helpTopicFile
This key maps to the help topic describing the Authoring page in the FileNet P8 Workplace application. The help key is "WcmAuthor", the name of the JSP file. Because WcmAuthor.jsp resides in the Workplace directory, no subdirectory qualifier is needed for the help key or the help file value (the help file must exist in the <help_root>/ae_help/workplace directory).
WcmAuthor=helpTopicFile#anchorName
The value to this key includes an anchor name, which will be included in the fully qualified URL redirected to the client browser. Of course, for the anchor name to be effective, the help topic file must include a named anchor that matches the anchor name in the key value. For example, if the anchor name in the key value is "label", the help topic file must include a named anchor called "label":
```
<a name="label">Start of text to be displayed by browser.</a>        
```
wizards/WcmAddFolder_WcmFolderSelectionWizardPage=wizards/helpTopicFile
This key maps to the help topic for selecting a parent folder, which is one wizard page for creating a new folder. The JSPpage substring of the help key is "wizards/WcmAddFolder", where "wizards" is the subdirectory location of the JSP page, "WcmAddFolder". The helpContext substring of the help key is "WcmFolderSelectionWizardPage", the contained class that renders the page for selecting a parent folder.

Note that the help topic file must reside in the wizards subdirectory relative to <help_root>/ae_help/workplace.
properties/WcmMoreObject_WcmPropertiesInfoPage=properties/helpTopicFile
This key maps to the help topic for viewing document properties, which is one of multiple information pages for a selected document. The JSPpage substring of the help key is "properties/WcmMoreObject", where "properties" is the subdirectory location of the JSP page, "WcmMoreObject". The helpContext substring of the help key is "WcmPropertiesInfoPage", the contained class that renders the page for viewing document properties.

Note that the help topic file must reside in the properties subdirectory relative to <help_root>/ae_help/workplace.

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:

helpRootPath specifies the help root path of the context-sensitive help files. As described in How a Help File is Retrieved, the controller framework uses the value of this key to calculate the fully qualified URL of a help file. The fully qualified path is the concatenation of http://<host:port>/<app_root>/ plus <help_root>, as described in Help Location Options.
helpExtension specifies the file extension of your help files. If you don't set this key, the controller framework defaults to the "htm" extension. This extension is supported in Web Application Toolkit version 3.0 and later.

Help Location Options

You can link either to the online version of the information center on www.ibm.com or to a local copy of the information center that you install and deploy. Internet access is required for the ibm.com information center. See Installing IBM FileNet P8 Platform documentation for more information.

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

The documentationServer key in <Application_Engine_deploy_path>/FileNet/Config/AE/bootstrap.properties file. The value must specify the http protocol, the host, and the port. For example:
```
documentationServer=http://helpServer:8080/p8docs/topic/com.ibm.p8.doc
```
Note that a file separator ("/") is not required at the end of the value.
The helpRootPath key in the <app_root>/WEB-INF/help_map.properties file. For example:
```
helpRootPath=csHelp
```
Note that a file separator ("/") is not required at the start of the value.

If the value of the documentationServer key is:

http://helpServer:8080/p8docs/topic/com.ibm.p8.doc

and if the value of the helpRootPath key is:

csHelp

then the resulting concatenation of the two values will be:

http://helpServer:8080/p8docs/topic/com.ibm.p8.doc/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.