TOCJS and TOCJSBIS Plug-ins

Overview

These plug-ins are very popular in the DITA community; we even use them on the DITA Technical Committee for our DITA 1.2 specifications.

Figure 1. OASIS DITA Technical Specification in tocjs

• tocjs: The tocjs plug-in was developed by Shawn McKenzie, currently working at Sophos in beautiful Vancouver, BC (Canada). The tocjs plug-in executes after the standard DITA-OT XHTML transform, so each tocjs TOC entry knows the name of its target XHTML topic.
• tocjsbis: The tocjsbis plug-in was written by Nadege Quaine and adds the important feature of topic synchronization, i.e. the highlighted topic entry in the TOC updates in sync with the topic being displayed in the contents frame. The plug-in achieves synchronization by adding a unique ID to each XHTML output topic (<meta content="id-tocjsbis_about" name="DC.Identifier" /> ) and by synchromizing the TOC entry against that topic ID. If you have generated HTML output from RoboHelp or WebWorks Publisher, this technique should be familiar.

If you are generating HTML output of any sort from your DITA sources, you should test one or both of these plug-ins. I use tocjsbis in my context-sensitive Help builds where I work. To the extent that the tree control in tocjs and tocjsbis are based on the Yahoo tree control library, you can customize the way that the final TOC tree displays and behaves in your Help system. They can be tricky, but customizations work.

Setup and configuration

The tocjs and tocjsbis plug-ins are free downloads from the Yahoo DITA-OT site.

http://tech.groups.yahoo.com/group/dita-users/files/Demos/

Figure 2. tocjs Download

After you have unzipped these archives to a local directory, you can browse the documentation to get a feel for what tocjs offers and how you can install it in your DITA-OT directory.

Figure 3. tocjs Installation

The pre-built documentation for tocjs lives in the /docs subdirectory.

Figure 4. tocjs Documentation

Installing tocjs or tocjsbis is very straightforward.

1. Copy the un-achived tocjs or tocjsbis subdirectory into the demo subdirectory of your DITA Open Toolkit directory.

   
   
   

2. Open a shell command window from your DITA-OT directory.
3. Enter the following command to integrate the new plug-in or plug-ins with your current DITA-OT environment.

   ant -f integrator.xml

4. Change directory into the demo/tocjs or demo/tocjsbis subdirectory and enter the following command to build the sample DITA topics.

   ant -f demo/tocjs/buildsample.xml sample2tocjs

5. Load the newly generated demo\tocjs\out\sample\frameset.html file in your browser.

If you are considering customizations to tocjs or tocjsbis, consult the documentation for the Yahoo UI tree control at the following URL.

http://developer.yahoo.com/yui/treeview/

Figure 5. Yahoo UI Library

That is about all that is involved with installing and configuring tocjs and tocjsbis.

Authoring

These plug-ins piggy-back whatever investment you have already made in authoring your DITA topics and map files. Beyond setting up a new ant script for tocjs or tocjsbis, there is nothing additional required.

Integration

The tocjs and tocjs plug-ins present few integration problems or opportunities, especially as regards managing context sensitivity between Help output and the calling software application. Many DITA Help writers customize the frameset.html file that ships with the tocjs plug-in to personalize or brand the final product. Here's what Shawn McKenzie does with tocjs on his Sophos corporate website.

Figure 6. Sample tocjs Documentation

Wrapping other navigational devices around the tocjs output is not difficult. I add the conventional tabs for tri-pane Help systems.

Figure 7. Integrated tocjsbis

In terms of translation, note that all the text strings associated with entries in the TOC tree are stored in one file named toctree.js. These files can be localized, for sure, but they are not very friendly. To make life easier on our sisters and brothers in L10N, you can post-edit this toctree.js file to swap JavaScript resource strings for literal strings.

Output

Here again is a link to a live demo of tocjs running at Sophos.

http://ca-repo1.sophos.com/docs/ws1000/

Summary

If you are comfortable customizing XHTML output to build an HTML-based help system, you should consider tocjs and tocjsbis. They are sufficiently lightweight to work in Help systems or web-based portals.