Enable a help system within the Integrated Solutions Console

Introduction

The Integrated Solutions Console (ISC) is a single framework that can host all the administrative console functions built by IBM server, software, and storage products in a way that allows customers to manage solutions rather than specific products. Administrative console functions range from setup and configuration to solution run time monitoring and control.

Eclipse is an open standard for developing Java technology-based user interfaces and user assistance. The Eclipse help system is a component of the Eclipse Platform that is used for displaying, browsing, searching, and printing online documentation. See Resources for more information on Eclipse.

The Integrated Solutions Console Version 5.0 help architecture is based on Eclipse Version 2.1.1 . The run time installation of the Integrated Solutions Console includes the Eclipse help infocenter run time, a help plug-in that provides help for the Integrated Solutions Console framework, and a help plug-in that provides help on creating console components.

To enable help for a console component, you must create a help plug-in, and package the plug-in within the console component .war file. When the console component is deployed to the ISC framework, its help plug-in is added to the installed base console help collection. This article describes how to build and package help for a console component.

Back to top

Eclipse Overview

Eclipse is, according to its Web site (see Resources), "a kind of universal tool platform - an open extensible IDE [Integrated Development Environment] for anything and nothing in particular."

Eclipse can be used to create development environments and tools for almost anything. One of the components of the Eclipse platform is the Help component, which provides a user assistance mechanism, including the ability to browse help online, to perform a search, and to provide context-sensitive help.

Although the Eclipse help system supports three product scenarios, the ISC framework uses the Eclipse infocenter scenario. The Eclipse infocenter scenario allows access to the help system over the Internet or a company's intranet. The application accesses the documentation by calling a URL, and the help system is shown in a Web browser. All features except infopops and active help are supported in the infocenter scenario.

Back to top

Help implementation in Integrated Solutions Console

The Integrated Solutions Console architecture defines four types of help: console, page, portlet, and field. ISC V 5.0 provides console level help, portlet level help, and page level help. Field-level help is a well-known requirement for future releases of ISC. See Resources for an article explaining the help levels.

The Integrated Solutions Console ships with two installation paths: developer and embedded. The developer installation is intended for ISC component developers and includes a WebSphere® Studio Application Developer (Application Developer) plug-in to help create console components. It also includes console component samples, instructions, and guidance to help in the creation of console components.

The embedded version is designed for deployment in a customer environment, and is ready to be embedded in a product.

Figure 1 shows two bookshelves in the navigation frame. The Eclipse infocenter uses a bookshelf to represent the contents, which then contains links to collections of online documentation. Clicking one of the links takes you to the navigation tree for that collection.

The Integrated Solutions Console Developer Infocenter bookshelf is a help set for the console component developer and is available with the developer installation version.

The ISC Basic bookshelf is the help set for the console user, but is available on both ISC installation versions. This help set includes help for the ISC framework and the ISC components that are plugged into the framework.

Back to top

Developing help contents for the Integrated Solutions Console

This section discusses how to create the help plug-in for a console component (see Resources for more information). Developing the help contents requires the following steps:

1. Create a plug-in ID.
2. Create a plug-in directory.
3. Create the plugin.properties file.
4. Create the plugin.xml file.
5. Create help content files.
6. Create TOC files (XML definitions of navigation trees).
7. Enable support for multiple languages.
8. Enable the search for your plug-in.

You'll create a sample plug-in later in the article. (The attached zip file has the sample plug-in.) You can use any text editor to create the help plug-in, or you can use Application Developer to create the help plug-in (see Resources for a link).

Your sample plug-in will have a bookshelf called "Help Sample," which will have more subtopics under it as shown in Figure 2.

The Eclipse platform is structured around the concept of extension points. Extension points are well-defined places in the system where other tools (called plug-ins) can contribute. Your help plug-in uses the "org.eclipse.help.toc" extension point, which is explained in step 3.

Step 1: Create a plug-in ID

The plug-in ID must be unique. In a console environment where different products deploy components to the same console installation, it is essential that the components do not conflict with components already deployed in the console. To avoid this conflict, each console component has a unique identifier called Component UID. More information on how to select a component UID for your component can be found at the Integrated Solutions Console Developer Infocenter (see Resources).

The Integrated Solutions Console uses a naming convention for help plug-in IDs that assures the uniqueness of the plug-in ID. The plug-in ID must be the component UID followed by .help.doc. In the sample provided, the component UID is com.ibm.sample; therefore, the help plug-in ID is com.ibm.sample.help.doc. The component UID is a unique identifier for an ISC component. For more information on this refer to Integrated Solutions Console Developer Infocenter.

Step 2: Create a plug-in directory

After identifying your plug-in ID, create a directory with the same name. This plug-in directory hosts all the help documents and the meta information in XML markup. In the example, the plug-in directory name is com.ibm.sample.help.doc.

Step 3: Create the plugin.properties file

This file is not required, but it is recommended. It contains key-value pairs that can be referenced inside of the plug-in descriptors. Listing 1 shows a simple example:

       
   // Sample plugin.properties file
    help_plugin_name =  sample plugin
    provider_name = Integrated Solutions Console
   

The plugin.properties file provides a technique for externalizing strings from the plugin.xml file (discussed in step 4). For example, you can externalize the strings in the plugin.xml file by replacing the string with a key. The plugin.properties file can be translated for different languages.

Step 4: Create the plug-in descriptor (plugin.xml) file

Next, create a plugin.xml file called com.ibm.sample.help.doc\plugin.xml. This file defines the extension point that lets Eclipse know that this is a help plug-in. Listing 2 shows a sample of the plugin.xml.

   <plugin
     name = "%help_plugin_name"
     id = "com.ibm.sample.help.doc"
     version = "5.0"
     provider-name = "%provider_name" >
     <extension point="org.eclipse.help.toc" >
    <toc file="toc.xml" primary="true"/>
     </extension>   
     </plugin>   
     

In Listing 2, the name attribute is the name of your help plug-in and the provider-name is the name of the plug-in provider. You can specify the values in plugin.xml, or reference it from the plugin.properties file. In the sample above, values for help_plugin_name and provider_name keys are defined in the plugin.properties file and are referenced in the plugin.xml.

The ID attribute is the identifier for this plug-in, which is your component UID followed by .help.doc. The version attribute can be the version of your product.

The extension point attribute defines the extension point as org.eclipse.help.toc, which lets the Eclipse help system know that this is a help plug-in. The toc file attribute is the file that describes the structure of the navigation tree. You can have more than one entry in the toc file attribute. the primary attribute specifies whether the toc.xml file is a primary table of contents and is meant to be the master table of contents. Or, it will not be the primary table of contents and will be integrated into another table of contents.

Step 5: Create help content files

Create all the help content files (HTML, GIF, JPEG, and so on) in a subdirectory below your plug-in directory. In the sample file, there is a directory called com.ibm.sample.help.doc/helpsample that contains all the help contents.

The help content files can be delivered in a zip file to avoid problems that might occur when a large number of files are present. In our sample plug-in, the help contents are placed in a subdirectory called helpsample. Alternatively, we could have zipped our help content files in a zip file called doc.zip. This zip file must mimic the file structure underneath the plug-in directory. In our case, it must contain the subdirectory helpsample, with all the contents underneath helpsample

When resolving file names, the help system looks in the doc.zip file for documents before it looks in the plug-in directory itself.

Step 6: Create TOC files (XML definitions of navigation trees)

Create com.ibm.sample.help.doc\toc.xml file, which defines the structure of the navigation tree. Listing 3 shows a simple case, where the entire navigation tree is defined in one XML file. If you want to create the navigation for your console component as a single tree, add primary="true" to your plugin.xml toc declaration as shown in the sample plugin.xml file in Listing 2.

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Help Sample">
	<topic label="Sample1" href="helpsample/sample1.htm"/>
	
    <topic label="Sample2" >
	    <topic label="Sample2 Help" href="helpsample/sample2.htm"/>
     </topic>
	<topic label="Sample3" href="helpsample/sample3.htm">
		<topic label="Sample3_1" href="helpsample/sample3_1.htm" />
		<topic label="Sample3_2" href="helpsample/sample3_2.htm" />
		<topic label="Sample3_3" href="helpsample/sample3_3.htm">
			<topic label="Sample3_3_1" href="helpsample/sample3_3_1.htm" />
		</topic>
		<topic label="Sample3_4" href="helpsample/sample3_4.htm" />
	</topic>
    
	</toc >
  

In this example, toc is the container element where topics are defined. A topic can be:

• A simple link to the content as shown as example Sample1 in Listing 3
• A hierarchical grouping of subtopics, as shown as example Sample2 in Listing 3
• Both, as shown as example Sample3 in Listing 3

When used as a link, the argument to href is assumed to be relative to the current plug-in. The label attribute appears in the navigation pane on the help browser.

You can also have a fully qualified link to refer to any content on the Web as shown in Listing 4.

      <topic label="ReferenceDoc" href="http://www.example.com/referenceDoc.html"/>
     

Using only one TOC file is simple, but not very dynamic. Some core complex scenarios are given in Building a help navigation tree for a console suite.

Step 7: Enable support for multiple languages.

If your console component supports multiple languages, the help plug-in must be translated into those languages and packaged in a specific directory structure in order for the Eclipse help run time to pick up the correct files for a particular language. With this in mind, you should set up the following directory structure:

• com.ibm.sample.help.doc/ - place all the the English files under this subdirectory.
• com.ibm.sample.help.doc/nl/ - this is empty.
• com.ibm.sample.help.doc/nl/ll/ - place the translated files for the language identifier (ll) under this subdirectory.
• com.ibm.sample.help.doc/nl/ll/CC/ - place the translated files for the language identifier (ll) and country code (CC) under this subdirectory.

As mentioned previously, ll is the language identifier and CC is the country identifier. With this directory structure, for example, you would place all the Traditional Chinese content files under com.ibm.sample.help.doc/nl/zh/TW and all the Japanese content files under com.ibm.sample.help.doc/nl/ja.

You can zip the translated content files (HTML, PDF, images, and text) into a file called doc.zip and place them inside each nl/ll/CC directory. Also, place the translated navigation XML files and plugin.properties files inside the directory. At run time, the help system picks up the correct version using the client's locale setting. If the help system is not able to find a file for a particular locale, the help system picks up the English copy by default.

Step 8: Enable search for your plug-in

The Eclipse help system comes with its own search capabilities, which are based on the Lucene search engine (see Resources). The search facility generates a full-text search index for the documentation the first time the user runs a search. Currently, the search parsers support only HTML content files. The index is updated if a help plug-in is added, removed, or if the version number is changed in the plugin.xml file. The generated index files for each language are located in the [your_isc_root]\Runtime\PortalServer\ISCEclipse\workspace\.metadata\.plugins\org.eclipse.help\nl\ll_CC directory. If you are developing content and want to force an index regeneration without updating the plug-in's version number, you can simply delete the contents of the subdirectory org.eclipse.help.

Only those topics that are explicitly listed in the navigation TOC file are included in the search index. Sometimes, there are files that are not listed in the navigation TOC file, but are accessed only by links from other files. In this case, there is a mechanism for adding these files to the search index. To do this, create a separate directory and add to that directory the files that are not listed in the navigation tree. Specify that directory under extradir attribute in the plugin.xml file.

The extradir attribute specifies the relative directory name for the additional documents that are associated with the table of contents. All help documents in this directory, and all subdirectories, are indexed and accessible through the documentation search, even if the topic elements in the TOC file do not refer to these documents. For example, if you create a directory as com.ibm.samples.help.doc/MoreSamples, then you would specify the extradir attribute as shown in Listing 5.

  <toc file="toc.xml" primary="true" extradir="MoreSamples"/>
 

If you point to a topic from the TOC, and the topic is also part of the directory specified in the extradir attribute of the plugin.xml file, it is indexed twice. If TOC files point to a topic multiple times, it is indexed only once.

Now your help plug-in with the com.ibm.sample.help.doc ID includes the plugin.xml, the plugin.properties file, toc.xml, and the help contents. When the help plug-in directory is created, you must create references from portlets and pages included in your console components, which is discussed in next two sections.

Next, the help plug-in must be packaged as a part of the console component .war file. Packaging and deployment is described in Packaging and deployment of help contents. After it is deployed, the help navigation pane reflects the toc.xml that you created.

Back to top

Referencing help files from portlets

You can reference a portlet-level help in the help plug-in using the ISCHelp API in conjunction with the doHelp() method of the portlet API. You must first enable the portlet help mode in the portlet.xml file, and then use the doHelp() method to implement the portlet help. When help mode is enabled, the help icon is displayed on the portlet title bar. When this icon is clicked, a separate browser window opens that displays the help topic you specified in the doHelp() method.

The Integrated Solutions Console Toolkit includes samples that illustrate referencing help. The samples are located at your_isc_root\dev\ directory, where your_isc_root is the root directory for your Integrated Solutions Console installation.

In the portlet, import the com.ibm.isc.api.help.ISCHelp class and implement the doHelp() method in the portlet. Inside the method, specify the help topic as a string. The syntax for specifying an Eclipse help topic is plug-inID/file_path/file_name, where plug-inID is the plug-in ID specified in the plugin.xml file, file_path is the sub-directory path (if any), and file_name is the name of the help content file. In Listing 6, it is "com.ibm.sample.help.doc/helpsample/sample2.htm." Call the method ISCHelp.ConsolePortlethelp, passing in the PortletRequest, PortletResponse, and the topic

-------------
-------------
import com.ibm.isc.api.help.ISCHelp;

-------------
-------------
public void doHelp (PortletRequest request, PortletResponse response)
throws PortletException, IOException
{
private String topic="com.ibm.sample.help.doc/helpsample/sample2.htm";
ISCHelp.ConsolePortlethelp(request, response,topic );
}

-------------
-------------
   

Back to top

Referencing help files from pages

This section describes the way to reference the appropriate page-level help files from the corresponding Integrated Solutions Console pages. The link is created in the component descriptor. Listing 7 shows a sample component.xml file.

<?xml version="1.0" encoding="UTF-8"? >
<component xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="isc.xsd"
     uid="com.ibm.sample" version="1.0" suiteID="suite.sample" suiteversion="5.0">
  <component-title>
   <title locale="en">Sample Component </title>
  </component-title>
  <suite-title>
    <title locale="en">Sample Suite </title>
  </suite-title>
  
  <content-hierarchy>
    <content-type name="workItemPage" supported-markup="html">
               
          <page uid="com.ibm.sample.workpage_1" PgHelpPluginID="com.ibm.sample.help.doc"
 PgHelpFilePath="helpsample/sample3.htm" > 
            
            <title locale="en">Sample Portlet </title>            
            <page-layout>
               <row>
                    <portlet ref="com.ibm.sample.1.HelpSample"/ >
                </row>
            </page-layout>
          </page>
       </content-type>
  </content-hierarchy>

</component>
   

The help plug-in ID and the help page are defined as attributes to the page element.

• PgHelpPluginID identifies the help plug-in that contains the page help. The value in this example is "com.ibm.sample.help.doc"
• PgHelpFilePath identifies the path relative to the plug-in directory and the file name for the page help file. In the example, it is "helpsample/sample3.htm"

Back to top

Packaging and deployment of help contents

The help plug-in is packaged as a part of the console component .war file as shown in Listing 8.

   Console component archive  root
/html                                              public html files
/images                                            public image files
 /help/com.ibm.sample.help.doc                     public eclipse formatted help
/(other)                                           other public console component content
/WEB-INF                                           private content
/WEB-INF/component.xml                             console component information
/WEB-INF/lib                                       console component libraries
/WEB-INF/classes                                   console component portlets, and other classes
/WEB-INF/(other)                                   other private console component content
   

Once packaged, you can use the iscdeploy tool to deploy the console component. This tool copies the console help plug-in to the correct location in the base Eclipse help system install.

You can read more about the iscdeploy tool at the Integrated Solutions Console Developer Infocenter.

Back to top

Building a help navigation tree for a console suite

Using only one TOC file is simple, but not very dynamic in the sense that if you have a suite of console components, you might not want to have just one help plug-in with one toc.xml file. Here we consider the case where Suite A needs to be deployed in the console framework, and Suite A is comprised of multiple selectable components. For simplicity, we consider four components.

So, what we really want to do is to create a navigation tree for Suite A by merging together trees from individual help plug-ins that might not be installed in a given instance of the console. There can be many ways to handle this case. Described below in detail is one way to handle this scenario. More on this can be found in the articles published at Eclipse Web site (see Resources).

A console component can specify another console component as its prerequisite. In this case, the prerequisite component must be deployed before this component is deployed. Otherwise, this component cannot be deployed. Also, once deployed, the prerequisite component cannot be undeployed unless all the components to which it is a prerequisite get undeployed. This is explained in more detail at the Integrated Solutions Console infocenter.

Assumption: Suite A needs to install four console components

• com.ibm.prod1
• com.ibm.prod2
• com.ibm.prod3
• com.ibm.prod4

To do this, this product would install a console component com.ibm.prod0. The help plug-in of this component would contain the plugin.xml as shown in Listing 9.

    <plugin name="%help_plugin_name" id="com.ibm.prod0.help.doc" 
    version="1.0" provider-name="%provider_name">
    <extension point="org.eclipse.help.toc">
       <toc file="MasterTOC.xml" primary="true" /> 
    </extension>
 </plugin>    

This help plug-in contain MasterTOC.xml as shown in Listing 10.

 <?xml version="1.0" encoding="UTF-8" ?> 
 <?NLS TYPE="org.eclipse.help.toc"?> 
 <toc label="Product A">
   <topic label="Task1" href="Task1.htm" /> 
   <topic label="Task2" href="Task2.htm" /> 
   <topic label="Topics for Prod1">
     <anchor id="prod1" /> 
   </topic>
   <topic label="Topics for Prod2">
     <anchor id="prod2" />
   </topic>
   <topic label="Task3" href="Task3.htm">
      <topic label="Task3_1" href="Task3_1.htm" /> 
      <topic label="Task3_2" href="Task3_2.htm" /> 
      <topic label="Task3_3" href="task3_3.htm">
         <topic label="Task3_3_1" href="Task3_3_1.htm" /> 
      </topic>
   </topic> 
   <topic label="Topics for Prod3">
      < anchor id="prod3" /> 
   </topic> 
   <topic label="Topics for Prod4">
      <anchor id="prod4" />
   </topic>
   <anchor id="prod5" /> 
   <anchor id="prod6" /> 
  </toc>
   
   

This MasterTOC.xml can directly define labels with corresponding help. What this also does is to provide anchors for four more help plug-ins:

• com.ibm.prod1.help.doc
• com.ibm.prod2.help.doc
• com.ibm.prod3.help.doc
• com.ibm.prod4.help.doc

Additionally, the MasterToc.xml can provide extra anchors for future use. For these future anchors the MasterToc.xml does not define the topic label (for example, anchors defined for prod5 and prod6).

The help plug-ins for the components to be deployed subsequently would refer to the anchors defined in the master plugin.xml. One thing to keep in mind is that none of the components (com.ibm.prod1, com.ibm.prod2, com.ibm.prod3, com.ibm.prod4 or subsequent future components of this suite) should require com.ibm.prod0 as a prerequisite. This is because there can be a scenario (Scenario C) where there can be a requirement to modify the MasterTOC.xml. This requires you to undeploy the component that includes the MasterTOC.xml, modify the MasterTOC.xml, and then redeploy it. As described previously, a prerequisite component cannot be undeployed unless all the components that have it as a prerequisite also get undeployed.

Consider the following scenarios.

Scenario A

User wants to install Suite A.

The user installs console component com.ibm.prod0 with:

• the help plug-in called com.ibm.prod0.help.doc
• the MasterTOC.xml within com.ibm.prod0.help.doc

The user then installs console component com.ibm.prod1 with:

• a help plug-in called com.ibm.prod1.help.doc.
• a link tag, link_to="../com.ibm.com.ibm.prod0.help.doc/MasterTOC.xml#prod1", defined inside the toc.xml of this help plug-in. This link tag helps the toc.xml within the com.ibm.prod1.help.doc help plug-in to link to its anchor in the mastertoc.xml file. An example is shown in Listing 11.

       < ?xml version="1.0" encoding="UTF-8" >
       < toc=label="Prod1 Help"
        link_to "../com.ibm.prod0.help.doc/MasterTOC.xml#prod1" >
        < topic label="Help Topics for Prod1" href=prod1help.htm" >
        --------
        --------
        --------
        </topic >
        < toc >
        

The user then installs the console component com.ibm.prod2 with:

• a help plug-in called com.ibm.prod2.help.doc
• a link tag, link_to="../com.ibm.com.ibm.prod0.help.doc/MasterTOC.xml#prod2" defined inside the toc.xml of this plug-in

Similarly, the user deploys com.ibm.prod3 and com.ibm.prod4, with help plug-ins as com.ibm.prod3.help.doc and com.ibm.prod4.help.doc.

At the end of this exercise the you get a navigation tree that is a merged from help plug-ins included in separate console components.

Scenario B

The user already has Suite A deployed. Now, the user wants to deploy two more components for Suite A: com.ibm.prod5 and com.ibm.prod6.

The user prepares the component com.ibm.prod5, along with the help plug-in as com.ibm.prod5.help.doc. In the toc.xml, the user links to the anchor prod5 in the MasterToc.xml. Similarly, this is done for com.ibm.prod6.

Scenario C

The user already has Suite A and two components from Scenario B installed and wants to install two more components for Suite A.

Note that the MasterTOC.xml does not have any extra anchors. In this case, the user must update the console component whose help plug-in includes MasterToc.XML with the following steps:

1. Undeploy com.ibm.prod0 component.
2. Modify the MasterTOC.xml to add more anchors.
3. Deploy the component com.ibm.prod0 with the help plug-in called com.ibm.prod0.help.doc.

Scenario D:

The user wants to undeploy component com.ibm.prod4:

The undeploy tool is aware of the name of of the help plug-in, so this tool deletes the plug-in called com.ibm.prod4.help.doc from the [eclipse_Home]/plugin directory. Note that because the anchors for this in the MasterTOC.xml was defined as shown in Listing 12, the subtree with the label com.ibm.prod4 in the navigation tree is still there, but the tree is not clickable.

<topic label="Topics for Prod4">
  <anchor id="prod4" />
  </topic>

Back to top

Summary

The Integrated Solutions Console promotes a consistent environment of authoring help for the administrative functions. This article described the use of the Eclipse help system to host the different types of help needed by a console framework.

Back to top

Download

Information about download methods

Resources

• See "Help in the Integrated Solutions Console " (developerWorks, February 2004) for an explanation of each level of help within the ISC, and how to use Application Developer to create the help plug-in.
  
  
• Read more about Eclipse.
  
  
• The Eclipse help system comes with its own search capabilities, which are based on the Lucene search engine.
  
  
• To learn how you can use the Integrated Solutions Console to administer different products using a single Web-based console, see the tutorial "Create an administrative suite" (developerWorks, February 2004).
  
  
• Read how to merge together trees from individual help plug-ins that might not be installed in a given instance of the console at the Eclipse Web site.
  
  
• More information on how to select a component UID for your component can be found at the Integrated Solutions Console Developer Infocenter. The Developer Information Center can be accessed by going to http://<your_server_name>:8430/help on the machine where you have installed the Integrated Solutions Console Toolkit.
  
  

About the authors

Comments

Back to top

Trademarks

Table of contents

• Introduction
• Eclipse Overview
• Help implementation in Integrated Solutions Console
• Developing help contents for the Integrated Solutions Console
• Referencing help files from portlets
• Referencing help files from pages
• Packaging and deployment of help contents
• Building a help navigation tree for a console suite
• Summary
• Download
• Resources
• About the authors
• Comments