Create a documentation plug-in

IBM Business Monitor, V8.0.1 > Reference > Developing for Monitor dashboard spaces > Create widgets
Create a documentation plug-in

You can provide users of your widgets with help files.
You can put these files anywhere, but if you want to integrate them within the help, create a documentation plug-in.

When you create help files for your widget, you can store the files separately or integrate them into the help. In either case, you can use the widget registration file to point to the main help file for the widget.
The help runs as a web application in the BSpaceHelp.ear file. The BSpaceHelp.ear file contains a pointer to the location of the help content, which is the profile_root/config/BusinessSpace/help/eclipse/plugins folder.
If you decide to integrate with the help, the widget help files must be placed in a documentation plug-in that is in the help content location. The steps in this procedure describe how to create a documentation plug-in. For more information about creating a documentation plug-in, see http://www.ibm.com/developerworks/opensource/library/os-echelp/.

Procedure
Create a folder to contain your plug-in content and name it to match the name of your plug-in. The name of the plug-in must end with .doc and can have a version number.
For example, com.ibm.wbpm.bspace.main.doc_7.5.0.
Tip: Add a version number to the end of the plug-in folder name to make updating the plug-in easier. The help system compares version numbers when it encounters plug-ins with the same base name and displays only the contents of the plug-in with the highest version.
Create the plugin.xml file to define the plug-in. Set the attributes for the plugin and toc elements. In the plugin element, the name attribute is the text that the help system displays to the user. In the toc element, the file attribute identifies the file that contains the navigation structure.
The DTD for the elements and attributes used by the help is:
<!ELEMENT plugin (extension*)>
<!ATTLIST plugin
  name               CDATA #REQUIRED
  id                 CDATA #REQUIRED
  version            CDATA #REQUIRED 
>

<!ELEMENT extension ANY> 
<!ATTLIST extension point              CDATA #REQUIRED 
 >
Create a navigation file and name it to match. The name of the file must match the file attribute in the plugin.xml file.
In the navigation file, create the navigation structure using topic elements. The following example is part of the navigation for the framework content plug-in.
<?xml version="1.0" encoding="utf-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Business Space powered by WebSphere" topic="concepts/bspace_concepts_main.html">
   <topic label="Business Space overview" href="concepts/bspace_concepts_main.html">
      <topic label="Business spaces" href="concepts/bspace_concepts_openbspace.html"/>
      <topic label="Widgets" href="concepts/bspace_concepts_widgets.html"/>
      <topic label="Showcases" href="concepts/bspace_concepts_showcases.html"/>
   </topic>
</toc>
Copy the content files into the same folder as the plugin.xml and the navigation file.
Compress the content files into a doc.zip file. The compressed file must be named doc.zip. The help system cannot read content in a file with a different name.
If you want to support additional languages, create an NL fragment. An NL fragment is a set of plug-ins that contains translated files that correspond to the files in a base set of plug-ins.
Create the fragment folder, rename it to match the documentation plug-in, and append .nl to the end of its name.
For example, com.ibm.wbpm.bspace.main.doc.nl.
Add an nl folder and then, for each language that you are supporting, create a subfolder with the code for the language.
Within each language subfolder, create a translated version of the navigation file and compress the translated content files into a doc.zip file. If a translated file does not exist in the doc.zip, users will see the English file as a default.
In the root of the fragment plug-in, add a fragment.xml file. The DTD of the fragment.xml file is:
<?xml encoding="US-ASCII"?> 
<!ELEMENT fragment>
<!ATTLIST fragment
  name                CDATA #REQUIRED
  id                  CDATA #REQUIRED
  version             CDATA #REQUIRED
  plugin-id           CDATA #REQUIRED
  plugin-version      CDATA #REQUIRED
>
The NL fragment folder now has a fragment.xml file and an nl folder. Within the nl folder is a folder for each supported language that contains a translated TOC file and a doc.zip containing translated files.
If you are updating an existing documentation plug-in and it does not have a version appended to its name, clear the help cache.

Stop the server.
Delete only the folders in the profile_root\temp\ Node_name\ server_name\ BusinessSpaceHelpEAR\BusinessSpaceHelp.war\eclipse\configuration folder. Do not delete the files in this folder.
Restart the server.

If you are just installing or updating a documentation plug-in (that is, you are not also installing or updating a widget):

At a command prompt, change directories to the profile_root/bin or cluster_root/bin directory.
Enter wsadmin.bat -conntype NONE and then enter the appropriate command:

For installing the widgets into a stand-alone environment:

Jython command:AdminTask.updateBusinessSpaceWidgets('{-nodeName node -serverName server -helpplugins fullpath}')
Jacl command: $AdminTask updateBusinessSpaceWidgets {-nodeName node -serverName server -helpplugins fullpath}

For installing the widgets into a clustered environment:

Jython command: AdminTask.updateBusinessSpaceWidgets('{-clusterName cluster -helpplugins fullpath}')
Jacl command: $AdminTask updateBusinessSpaceWidgets {-clusterName cluster -helpplugins fullpath}

Fullpath is the name and location of the documentation plug-in created.
For information on updateBusinessSpaceWidgets, see updateBusinessSpaceWidgets command: .
Enter Exit
Restart the server or cluster.
What to do next
See Packaging and deploying custom widgets for information on how to install the documentation plug-in.

Create widgets

Related concepts:
Anatomy of a widget

Related tasks:
Create widgets using basic tools
Create widgets using Rational Application Developer
Create widgets
Registering custom widgets using catalog files
Packaging and deploying custom widgets