Level: Introductory Daniel Worden (dworden@worden.net), Author
20 Feb 2004 This article takes you through the features of a common help framework for Web-based applications that are deployed to the IBM® Integrated Solutions Console Version 5.0.1. It explains how the Integrated Solutions Console Toolkit supports the development and deployment of online user assistance for administrative components. Examples of help screens for Integrated Solutions Console components at each level are shown, as well as a brief treatment of how they are created and packaged using the WebSphere® Portal, WebSphere Studio Application Developer, and WebSphere Studio Device Developer after successfully installing the Console Toolkit.
Goals of Integrated Solutions Console help
One of the key goals of the Integrated Solutions Console within the IBM Autonomic Computing Tookit is to provide a consistent view and common interface tool for Web-based administration, including help. While users of desktop applications are used to a common approach to accessing help, there has been no standard way of providing online user assistance for Web-based applications. Until now.
Help is an important part of any product or visible component. Users prefer to work with applications that provide satisfactory assistance when and as needed. The primary goal is to provide user direction on how to accomplish a specific task. A help system should be well-organized and present users with a clear path to the information they need. In desktop applications this can be achieved through context-sensitive help, by providing intuitive and advanced search capabilities, or both.
The Integrated Solutions Console Toolkit provides the mechanism to deliver on the objectives for a help system by including the infrastructure for developing help plugins for Integrated Solutions Console components. The principles for developing help for an Integrated Solutions Console component are the same as for developing help for any user interface. Online user assistance for the Integrated Solutions Console is consistent from one application to the next and based on established standards so users already know how to get help when they use a new component or suite of components. With the help framework incorporated into the Integrated Solutions Console, this can now be done in an integrated structure. This approach offers the advantages of being accessible through a Web browser and consistent across all products being administered through the console.
By providing an open framework for help and systems documentation, the Integrated Solutions Console can consolidate general product help and customer specific instructions. All Integrated Solutions Console components, including help, consist of at least one portlet and a descriptor. Portlets containing help automatically display an icon in the form of a question mark on the title bar when they are executed within the Integrated Solutions Console.
Portlet help
When a user clicks on the question mark icon, a help window opens with the content specific to that portlet, as shown in Figure 1.
Figure 1. The Integrated Solutions Console with portlet help activated
Portlet developers might also link their portlets to help using the ISChelp class, which is provided with the Integrated Solutions Console Toolkit. The ISCHelp API is used in conjunction with the doHelp method of the Portlet API. When help mode is
enabled using this class, the question mark icon is displayed on the deployed components portlet in a manner consistent with all portlet help.
Detailed instructions for using this method, and the Javadoc for the ISCHelp class are available within the InfoCenter of your Integrated Solution Console after installation.
Console help
At the highest level, the Integrated Solutions Console toolbar has a help link that opens a separate browser window containing all the Integrated Solutions Console help plugins. This is installed on the WebSphere Portal Server where that instance of the Integrated Solutions Console runs. The console help includes a navigation tree and pane for displaying text and graphics. An example of the Integrated Solutions Console help is shown in Figure 2.
Figure 2. Integrated Solutions Console help navigation tree and content pane
Here the user can access full text search on selected books as well as print capabilities. The Integrated Solutions Console basics help plugin is made available as part of the initial installation. For a more detailed treatment of Integrated Solutions Console component development, see the tutorial, "Creating an Administrative Suite within the Integrated Solutions Console" (see Resources for a link.)
Component developers are responsible for creating help for their specific components. Individual user settings supported by the Integrated Solutions Console help system include use of user system colors and keyboard navigation. The Integrated Solutions Console provides a standard banner, skin, portal theme, navigation controls, and common layout definition. Recommended practices for writing user assistance are available from IBM.
Additionally, page help can be made available to describe how all of the portlets related to a particular task work together.
Page help
Integrated Solutions Console components must contain at least one portlet, but will frequently consist of several portlets that work together to perform useful application administration functions. To provide an online explanation for many portlets, the Integrated Solutions Console help framework supports page help. Clicking the help link on the page title bar accesses this level of help. If help has not been created for that page, the title bar only provides a close window option.
Field help
Although field-level help might be supported in future versions of the Integrated Solutions Console, portlet help is currently the lowest level description supported by the Integrated Solutions Console. To define individual fields and valid values for them within the help framework, you add the explanation at the bottom of the portlet help screen.
Planning your content
As an important first step, you should define your table of contents for your help document. This is used as the basis for your navigation tree. For simplicity, you should limit the number of nested items to no more than four. Expanding the tree past that number requires the user to scroll. Additionally, the complexity of the navigation tree is described through an XML file (toc.xml) that must be packaged with the help plugin when it is deployed.
When you design the help information for an Integrated Solutions Console component, outline the organization of the topics that you want to include in the navigation tree. Topics not listed in the help navigation tree are not included in the search index, but there is a mechanism for adding such topics to the search index by placing the non-listed topics in a separate directory and specifying that directory in the plug-in descriptor file. If you need to use this mechanism for your help plugin, create the separate directory prior to authoring, and add the files that will not be listed in the navigation tree to the directory as you create them. Detailed instructions on how to do this are available in the Integrated Solutions Console Infocenter (see Resources).
Creating content
Help content can include plain text, HTML 3.2 and 4 as well as Adobe Acrobat PDF formatted documents. All graphic formats that can be displayed in a Web browser are supported, including JGP and GIF. Links to external Web sites are supported within help and by default open in the content pane when activated. Hover help or microhelp at the field level is not supported.
Integrated Solutions Console is enabled for multiple languages. Users access help in the language they prefer when the translated content is included in the appropriate directories.
Packaging a help plugin
To run under the Integrated Solutions Console, a help plugin must include content and two configuration files: toc.xml and plugin.xml. As mentioned earlier in this article, the toc.xml describes the table of contents for the help pages and is displayed on the console screen as an expanding and collapsing navigation tree. The toc.xml code is shown in the source window of a WebSphere Studio Application Developer workstation in Figure 3.
Figure 3. The toc.xml
For Integrated Solution Console Version 5.0.1, the help subsystem is based
on Eclipse 2.1.1 technology. The help subsystem must be running before the
user a can access the help. Each console installation includes the Eclipse
help subsystem. The plugin descriptor (the plugin.xml file) provides language information for the help plugin name and the provider name. As shown in the example below, the language-dependent strings are placed in a separate properties file
(plugin.properties) to facilitate translation.
The plugin.xml associated with a help plugin required by the Eclipse framework provides the information Eclipse needs to access the help content when executed from within the Integrated Solutions Console. The plugin.xml is shown in Figure 4.
Figure 4. The plugin.xml
Listing 1: Sample of plugin.properties file
help_plugin_name = Worden Test Help
provider_name = Worden
|
This passes variables needed by plugin.xml to establish which language of help should be used. English language is the default.
The content and configuration files for the help plugin are added to the
Web archive (.war) file for the corresponding Integrated Solutions Console
component. IBM recommends using WebSphere Studio Application Developer or WebSphere Studio Site Developer
for developing Integrated Solutions Console components. The WebSphere Studio environment allows you to
import the help plugin files into the corresponding Component project. The help plugin files are placed in the /help/plug-in_name subdirectory of the Component archive
(.war) file, where plugin_name is the name of the help plugin.
If the Console component has more than one help plugin, create a separate directory for each.
Deploying help
Help plugins are implemented as part of the deployment of an Integrated Solutions Console component. This process is described in detail through the tutorial "Creating an Administrative Suite in the Integrated Solutions Console" (see Resources for a link) and includes an example of how help is created, deployed, and accessed.
The Integrated Solutions Console Toolkit includes a set of WebSphere Studio plugins that support the creation of Integrated Solutions Console components that can and should include help. Additionally, a Portal Server Toolkit and Portal Server run time are provided, along with the Eclipse help framework. These are set up on the Integrated Solutions Console host server as part of the Autonomic Computing Toolkit host installation process.
The Portal Toolkit, when added to WebSphere Studio, contains a template for creating portlet help. By editing this template you create the portlet level help content that accompanies that component. The template is shown in Figure 5.
Figure 5. Portlet help template used to generate portlet help within WebSphere Studio
An example of what this portlet help page looked like after deployment, when activated from within the Integrated Solutions Console, was shown in Figure 1.
The Integrated Solutions Console leverages the Portlet Help API and combines page, portlet, and console help in a consistent manner from a single point of contact for all deployed components.
Summary
At the outset, the Autonomic Computing Toolkit provides administrative functions through the Integrated Solutions Console. For customers who use the Integrated Solutions Console platform, customizing help to promote a common environment for documentation of administration functions is one more way to take advantage of the Integrated Solutions Console.
Web-based applications make life easier for administrators and users who might not always be at a particular desk. One deficiency long associated with thin client applications has been the lack of a feature rich interface. With the Integrated Solutions Console help framework, IBM provides a path to consolidating multilayer, context sensitive help for administrative functions across many products.
Resources
- For more information on Integrated Solutions Console help, see "Portlet Development Best Practices and Coding Guidelines."
- For an introduction to the capabilities of the Integrated Solutions Console and how to create components to run in it, see the developerWorks tutorial, "Create an Administrative Suite within the Integrated Solutions Console."
- For information on building Eclipse help, see "Documenting your project using the Eclipse help system" (developerWorks, January 2004).
- Download the Autonomic Computing Toolkit, which includes the Solution Installation and Deployment Technology, Integrated Solutions Console, Log/Trace Analyzer, Adapter Rule Builder, Autonomic Management Engine, and Resource Model Builder tools.
- Download the Business Workload Manager Prototype, which includes the Application Response Measurement API.
- Download the Agent Building and Learning Environment 2.0 for building intelligent agents.
- Download the Emerging Technologies Toolkit for a look at upcoming tools and technologies.
- Check out more emerging tools on alphaWorks.
- Find more autonomic computing resources at the Autonomic Computing content area at developerWorks.
About the author  | | | Daniel Worden, a Studio B author, has 20 years of experience in systems, database administration, and operational management. He is the author of five technology books, whose work has been translated into Chinese and Japanese. As IBM San Francisco partner number 46, his firm received the FastStart award in 1998 for their Java application built with the SF framework. Over the past two years he has led the design and development of a Food Trading and Tracking utility with WebSphere, DB2, and Domino. Daniel is currently working on Storage Networks -- From the Ground UP for Apress. He can be reached at: dworden@worden.net. |
Rate this page
| 
