8 Adding Online Help for Console Extensions

The Administration Console help viewer is an Oracle WebLogic Portal Web application that uses an implementation of JavaHelp 2.0, an open source help system.

This chapter tells how to create help for a console extension and merge that help into the main Administration Console help system.

Summary of Steps

The main steps required for creating console extension help topics are as follows:

Create a Javahelp helpset, including the HTML topic files and the Javahelp control files.
Establish context-sensitive links from the console extension to help topics.
Deploy the help system with the console extension.

Create the Helpset

You can create a Javahelp system using the Javahelp software. Alternatively, you can use any help authoring tool that creates Javahelp. See the documentation for Javahelp or the documentation for your authoring tool for complete instructions.

For more in formation about JavaHelp and to download the Javahelp software, see JavaHelp System at http://java.sun.com/javase/technologies/desktop/javahelp/.

Helpset Files

The following files are required by the Administration Console help system. These files together are called a "helpset."

Topic files (.html)

These HTML files contain the help content. You can use any editor that can create HTML files to create these files.
Helpset file (.hs)

This XML file defines the helpset for the extension, including information such as the name and location of the map file, helpset title, etc.

For a console extension helpset, the name of the Helpset file must start with the name of the extension. For example, the name of the Helpset file for the Jolt console extension is jolt.hs. (The Jolt console extension is a standard extension the Administration Console.) For localized helpsets, append the locale information to the end of the name of the extension, for example, jolt_en_US.hs.
Mapping file (.jhm)

This XML file maps context help IDs to help topics.
Table of contents file (.xml)

This XML file defines the table of contents for the help.

The following files are optional:

Index file (.xml)

This XML file defines the index for the help.
Full text search database

These database files are generated using the Javahelp software or a Help authoring tool that creates Javahelp:

There are further considerations for merging helpsets and for providing localized helpsets. See Directory Structure for Merging Extension Help and Localizing Helpsets.

Merging Helpsets

The table of contents and the search database for a console extension's helpset are automatically merged into the main Administration Console help, provided that the extension's helpset is organized and named properly. Extension helpsets are merged only when the help is deployed on the same server instance as the Administration Console.

The Administration Console's helpset file sets the merge type to the Javahelp AppendMerge type. That type defines how console extension helpsets are merged into the main console help.

See "Merging Helpsets" at http://docs.sun.com/source/819-0913/author/merge.html for more information about Javahelp merging. See also How Helpsets Are Merged for more information about how helpsets are merged in WebLogic Server.

Directory Structure for Merging Extension Help

For an extension's help to be merged with the main console help, the help files must be organized as follows. The name of the directory containing the helpset files must be bea-helpsets.

...\console_extension\bea_helpsets\extension_name_locale.hs
...\console_extension\bea_helpsets\locale\extension_name-map.jhm
...\console_extension\bea_helpsets\locale\extension_name-toc.xml
...\console_extension\bea_helpsets\locale\extension_name-search\search database files
...\console_extension\bea_helpsets\locale\topics_dir\HTML topic files...
...\console_extension\bea-helpsets\locale\topics_dir\images\Graphic files...
...\console_extension\PortalConfig\...
...\console_extension\WEB-INF\...
...\console_extension\Other extension source directories...

Note:

The HTML topic files and graphic files may be located in multiple directories and subdirectories, but they all must be under ...\console_extension\bea_helpsets\locale\.

For example:

...\my_ext\webapp\bea_helpsets\my_ext_en_US.hs
...\my_ext\webapp\bea_helpsets\en_US\my_ext_map.jhm
...\my_ext\webapp\bea_helpsets\en_US\my_ext_toc.xml
...\my_ext\webapp\bea_helpsets\en_US\my_ext-search\search database files...
...\my_ext\webapp\bea_helpsets\en_US\pagehelp\HTML topic files...
...\my_ext\webapp\bea_helpsets\en_US\taskhelp\HTML topic files...
...\my_ext\webapp\bea-helpsets\en_US\taskhelp\images\Graphic files...
...\my_ext\webapp\jsp\...
...\my_ext\webapp\PortalConfig\...
...\my_ext\webapp\WEB-INF\...

Localizing Helpsets

Multiple localized helpsets can be simultaneously included in help. The help viewer uses the same strategy used by java.util.ResourceBundle for locating locale-specific help files. The help viewer expects the following directory structure under the bea-helpsets directory for your extension:

...\extension_name_locale_1.hs
...\extension_name_locale_2.hs
...\extension_name_locale_3.hs

...\locale_1\map.jhm
...\locale_1\toc.xml
...\locale_1\search\Search db files...
...\locale_1\topics\HTML topic files...
...\locale_1\topics\images\Graphic files... (optional)

...\locale_2\map.jhm
...\locale_2\toc.xml
...\locale_2\my_search\Search db files...
...\locale_2\topics\HTML topic files...
...\locale_1\topics\images\Graphic files... (optional)

...\locale_3\map.jhm
...\locale_3\toc.xml
...\locale_3\search\Search db files...
...\locale_3\topics\HTML topic files
...\locale_3\topics\images\Graphic files... (optional)

For example, see Figure 8-1.

Figure 8-1 Directory Structure for Localized Help

Description of "Figure 8-1 Directory Structure for Localized Help"

If the help content for the locale specified in the browser is not found, the help viewer displays the content from the default folder.

How Helpsets Are Merged

Administration Console helpsets are parsed and helpset objects are created and cached the first time a user requests help from the help viewer. The help viewer searches the server extension and domain extension folders for extension helpsets and merges them with the Administration Console helpsets. The console looks for extensions in these locations:

WL_HOME/server/lib/console-ext
WL_HOME/server/lib/console-ext/autodeploy
DOMAIN_HOME/console-ext

Helpsets are merged according to the following rules:

If console help and extension help exist for the user-requested locale, the extension help is merged with the console help.
If console help and extension help do not exist for the user-requested locale, console help in English is displayed. The help viewer searches for extension help for the English locale and, if found, the extension help is merged with the console help.
If console help for the user-requested locale exists but extension help for that locale does not exist, the help viewer searches for the extension help for the English locale, and if found, the extension help is merged with the console help.
When searching for an extension's helpset for a particular locale, the help viewer looks for a helpset for the language, country, and variant. If all three are not found, the help viewer looks for the language and country. If that is also not found, the help viewer looks for the language, as shown in the following list.
1. language + "_" + country + "_" + variant
2. language + "_" + country
3. language

Provide Support for Context-Sensitive Help

Users request help from the Administration Console by clicking he Help link in the content header menu at the top of the Administration Console. That link displays the help topic for the current page.

To provide context sensitive help for console extension pages, you must

Provide Help IDs for books, pages, or targets within pages.
Map Help IDs to Help Files in the Javahelp map (.jhm) file.

At this time, console extension developers cannot provide links in the How do I... pane on the left side of the Administration Console or More Info... links in the configuration and monitoring pages on the right side.

Provide Help IDs

Each Portal page or book can have a help ID, and targets in pages can have help IDs. You must specify helpids or helpurlpatterns.

helpid

Specify the help context for portal pages and books by specifying a help ID and a bundle name using a meta-tag with the name helpid. Separate the help ID and the bundle name with a semicolon (;). Alternatively, portals and books can inherit the context from ancestor pages or books.

Help IDs can contain only alphanumeric characters, hyphens (-) and underscores (_). Any other characters are rejected, and a generic error message is displayed.

The help Web application reads the help ID and bundle name from the helpid meta-data. If the page or book does not set a helpid, the help application recursively searches parent pages and books to get a helpid. The helpid from the closest parent is used.

The overall Home book for the Administration Console has a helpid, which ensures that if a helpid for a context is not found, the default help page for the console is displayed. The helpid value is assigned to a JavaScript variable, bea.wls.console.pageHelpKey.

When the Help link in the content header is clicked, the helpid is passed as a query parameter to the help Web application. The help Web application uses the helpid to query the helpset mapping (.jhm) file and returns the help resource.

The following example shows how the helpid is assigned for the Configuration > General tab of the Settings for JoltConnectionPool page of the Jolt console extension. This snippet is taken from the JoltFullFeatures.book file.

<netuix:page markupName="page" 
   markupType="Page"
   definitionLabel="JoltConnectionPoolConfigGeneralTabPage"
   title="tab.general.label" presentationClass="page-content">
<netuix:meta name="helpid" 
   content="Jolt.jolt.joltconnectionpoolconfiggeneral.title;jolt"/>

helpurlpattern

The Administration Console provides an alternate method for invoking help. A general help URL pattern can be defined using helpurlpattern meta-data tag in portal pages and books. The value of the pattern can contain variables that can be substituted in any page/book using a netuix meta tag. For example, set the value of helpurlpattern meta-tag as follows:

<netuix:meta name="helpurlpattern" content=
 "/consolehelp/console-help.portal?_nfpb=true&_pageLabel=page&helpId=${helpid}"/>

and then specify the helpid value using <netuix:meta> tag.

<netuix:meta name="helpid" content="applications.CreateDeploymentPlan"/>

The helpid variable in the URL pattern is substituted by the value provided in the helpid meta-tag.

The helpurlpattern can be specified in any page or book. If not specified, the parent pages and books are searched recursively to find a helpurlpattern. The helpurlpattern from the closest parent is used. Once a pattern is found, any variable substitution values that are defined in the current page or book are applied to the URL pattern to arrive at a valid URL.

The helpurlpattern is convenient way when you want to provide an alternate URL for an extension's help. Consider an extension named my_extension. You wants to direct a request for help to a Web page. The extension my_extension defines the helpurlpattern in the root page or book as follows:

<netuix:meta name="helpurlpattern"
   content="http://my_web_site.com/my_product/docs/${product_name}/index.html"/>

A product_name meta-tag can provide a value for substitution.

<netuix:meta name="product_name" content="my_extension"/>

The resulting help link points to http://my_web_site.com/my_product/docs/my_extension/index.html.

Map Help IDs to Help Files

Map the help IDs defined in portal pages and books to the HTML help topic files in the Javahelp map (.jhm) file. For example, the following element in the map file associates the help ID domainconfig to the topic file domainConfig.html, which is located in the Pages directory.

<mapID target="domainconfig" url="Pages/domainConfig.html"/>

The path to the specified topic file is relative to the location of the map file, which is in the locale directory. See Directory Structure for Merging Extension Help.

Rebranding Help

The help Web application can be rebranded by providing a Look and Feel (LAF) and targeting it to the help Web application's portal (console-help.portal). An extension LAF can rebrand the help Web application only if it is deployed on the same server instance as the Administration Console Web application. For information about changing the look and feel, see Chapter 5, "Rebranding the Administration Console."

Deploying Help

Extension help is merged onto console help only if the help Web application is deployed on the same server instance as the console. It will not merge if the help Web application is deployed on a different server instance.

Similarly, help Web application are rebranded only if the help Web application is deployed on the same server instance.