Creating 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 Business Space help, you must create a documentation plug-in.

1. 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.
2. Create the plugin.xml file to define the plug-in. Set the attributes for the plugin and toc elements. The following example is from the main content plug-in for the Business Space documentation:

   <?xml version="1.0" encoding="utf-8"?>
   <!-- © Copyright IBM Corporation 2011-->
   <?eclipse version="3.0"?>
   <plugin id="com.ibm.wbpm.bspace.msin.doc" 
   		name="Business Space help"
   		provider-name="IBM"
   		version="7.5.0">
   	<extension point="org.eclipse.help.toc">
   		<toc file="bspace_main_toc.xml" primary="true"/>
   	</extension>
   </plugin>

   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 Business Space help is:

   <!ELEMENT plugin (extension*)>
   <!ATTLIST plugin
     name               CDATA #REQUIRED
     id                 CDATA #REQUIRED
     version            CDATA #REQUIRED 
   >
   
   <!ELEMENT extension ANY> 
   <!ATTLIST extension point              CDATA #REQUIRED 
    >

3. Create a navigation file and name it to match. The name of the file must match the file attribute in the plugin.xml file.
4. 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"?>
   <!-- © Copyright IBM Corporation 2011-->
   <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>

5. Copy the content files into the same folder as the plugin.xml and the navigation file.
6. 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.
7. 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 (in English for Business Space)
   1. 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.
   2. Add an nl folder and then, for each language that you are supporting, create a subfolder with the code for the language.
   3. 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.
   4. In the root of the fragment plug-in, add a fragment.xml file. For example,

      <?xml version="1.0" encoding="UTF-8"?>
      <?eclipse version="3.0"?>
      <fragment
          name="Business Space NL Support"
          id="com.ibm.wbpm.bspace.main.doc.nl"
          version="7.5.0"
          plugin-id="com.ibm.wbpm.bspace.main.doc"
          plugin-version="7.5.0"
      >
      </fragment>

      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.
8. If you are updating an existing documentation plug-in and it does not have a version appended to its name, clear the help cache.
   1. Stop the server.
   2. 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.
   3. Restart the server.
9. If you are just installing or updating a documentation plug-in (that is, you are not also installing or updating a widget):
   1. At a command prompt, change directories to the profile_root/bin or cluster_root/bin directory.
   2. 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 that you created.

      For information on updateBusinessSpaceWidgets, see updateBusinessSpaceWidgets command.

   3. Enter Exit
   4. Restart the server or cluster.