Automatic table of contents for RDA Toolkit workflows

Below is described a way to add tables of contents to RDA Toolkit workflows automatically, i.e. without manually adding anchors and creating a list. You can see an example of it action on this workflow (although of course I can’t guarantee that this workflow will always be around or look like this).

It uses some Javascript but requires no knowledge of it as it can be dropped in. It is 95% a script written by Stuart Langridge (@sil) with some minor amendments to get round some strange internal linking behaviour and to provide links to the top of the document throughout the workflow.

Instructions follow and some caveats are below.

  1. Open an RDA Toolkit workflow for editing
  2. Click on Source
  3. Insert the following snippet of HTML where you want the table of contents to appear:
    <div class="generate_from_h2" id="generated-toc"><a name="top"></a></div>
  4. If you have access to a local web server:
    1. Copy the Javascript file generate_toc_rda.js and put it somewhere sensible.
    2. At the very end of the workflow, put the following HTML snippet, changing the URL to where your copy of generate_toc_rda.js now lives:
      <script type="text/javascript" src="http://www.myserver.org/pathto/generate_toc_rda.js"></script>
  5. If you don’t have access to a local server:
    1. At the very end of the workflow, put the following HTML snippet:
      <script type="text/javascript">
    2. Copy the complete contents of the Javascript file generate_toc_rda.js and paste it on the next line. There will be a lot of it.
    3. On another line underneath, i.e. right at the end, put the following snippet of HTML:
      </script>
  6. Save the workflow.
  7. Click on the workflow in the Toolkit to refresh it.
  8. Buy Stuart some beer next time you see him, e.g. some gueuze, or give him some custom.

Caveats: it is not official and while the script was designed to work on any web page, these things always depend on the approach taken by the encompassing page to be logical and consistent over time, and this can be particularly unpredictable in a CMS, which the Toolkit basically is. I am also unsure of the publisher’s attitude towards dropping Javascript into workflows, although cannot see why there should necessarily be objections to this. Lastly, using this approach also means  removing any existing apparatus of table of contents or links to the top. It would be advisable to back up everything, including the source of generated tocs, although in the worst case, it would probably be possible to move the contents of a workflow to an external file, run the toc script on it, then re-import the HTML source.

Please do let me know if you try this and how you get on. I might be amenable to making changes to it, time and circumstances allowing. Stuart released the original toc script “under an X11 licence. What this boils down to is: do what you like with it. You can use the script in commercial environments, you can use it on your intranet, you can use it anywhere you like.” Sounds good to me too.