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".
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:
Note that your application can override the default help page name by calling WcmController.setHelpPage(...).
getHelpURL(...):
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(...) .
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.
For key/value pairs in help_map.properties, the following rules apply:
browseDocuments=browseHelpTopic#middle
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
/operationsoperations/help_key = operations/help_file_value Workplace
/eprocess/common/html/ootb<help_root>/ae_help/workplace
/eprocess/common/html/ootbeprocess/common/html/ootb/help_key =
eprocess/common/html/ootb/help_file_value
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 ExamplesThe 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.
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).
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>
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.
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.
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.
The help mapping file, help_map.properties, includes the following reserved keys:
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:
documentationServer
key in
<AE_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/ecm_help
Note that a file separator ("/") is not required at the end of the value.
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/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.