generated-toc: Generate a Table of Contents with the DOM
It's often useful for a long page to contain a table of contents, to make it easy for people to jump to the bit they care about. Here's a way of making your page automatically have one which is correct and up-to-date: generate a table of contents with JavaScript.
How to use the script
Actually setting this up is simple. You need to download the JavaScript library and then include it in your pages, like this:
<head>
...
<script type="text/javascript" src="generated_toc.js">
...
</head>and then you need to add to your page, where you'd like the Table of Contents to appear:
<div id="generated-toc"></div>Just those three steps. Download the library; make reference to it in your page; tell the library where you want the ToC to appear.
What does it actually do?
Well, the ToC at the top of this page is generated with the library. You'll
need to click "show table of contents" to see it. What it actually does is look
at all the headings in your document (<h1> to <h6>)
and create a link to each one in the ToC, making it easy for your users to jump
to a particular part of the document. This is, of course, a good reason to
use properly structured HTML (rather than making a "heading" by doing something
like <b><big>My Heading</big></b>, not that
any of my readers would ever do anything like that, of course).
The ToC is a set of nested lists, so a h3 will appear further
indented than an h2, indicating the structure of your document
as part of the ToC.
Is that all?
Well, there are some extra niceties.
Hidden by default
The ToC initially appears hidden, with a show table of contents link in its place. Clicking the link reveals the ToC.Remembering the status
If you do show the ToC, the script remembers this with a cookie, so the next time you return to this document, the ToC will be shown by default.
"Skip" link for AT users
The script adds a skip table of contents link, which
skips over the ToC; this is for accessibility purposes, so screen-reader users
and similar don't have to listen to the ToC getting read out on each page. This
link is given a class of hidden, meaning that you can
hide it in your stylesheet if you don't want it visible to users not using
assistive technologies.
Start from a certain heading level
By default, the script looks at all headings in the page. On this
page, for example, that would include the main (<h1>) heading,
"Generate a Table of Contents with the DOM". Since that wouldn't be all that
useful, we'd like to skip it. This page does this by adding
class="generate_from_h2" to the
<div id="generated-toc">, which tells the script "only include
h2 and below headings in the ToC -- skip h1s". This
useful trick allows you to "tune" which headings should be considered as part
of the ToC and which not.
Administrative details
An attempt to answer the question: what do I have to do in order to get my hands on this glorious JavaScripty goodness?
Where can I use this script?
Like all of my DOM scripts, generated-toc is 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.
Does it cost money?
You don't have to pay for this. I believe in Free Software; writing this and seeing people use it is its own reward. Of course, if you're determined to give me money then I'm not going to stop you. You can send money to my PayPal account with the button below.
I've found a problem in generated-toc. How can I tell you about it?
Firstly, thanks for using this script; sorry it's not doing quite what you want! If you've run into a problem with this, do please contact me and tell me about it, and I'll add it to the list to be fixed.
But I need my problem with generated-toc fixed! Can I pay you to fix it?
Yes. This script gets worked on in my spare time, between paid work, which means that development might not be as fast as you like. If you really want something fixed, you can jump it up my priority list by waving money at me. Best thing to do is to contact me and we can talk about rates and so on.
Many thanks to the organisation that funded my work on this project. They're supporting freedom on the web: this is a good thing indeed.
One chap has taken this script and made a few alterations to it to work better for him: see his work at http://smokyflavor.wikispaces.com/generated-toc and use that if you need some of the extras!
Stuart Langridge, July 2007, February 2008