PmWiki | Cookbook / HandyTableOfContents

Summary: Handy Client-side Table of Contents

Version: 20070218

Prerequisites: PmWiki version 2.1.27

Status: beta

Categories: TOC, Markup

Questions answered by this recipe

How can I create a table of contents for included files? How can I create a table of contents for a page whose content is generated via pagelist?

Description

Most of the existing table-of-contents recipes have this limitation: they can only generate a table of contents from the information in the source of the page they're used in. If data is included later (either with (:include :), or, even more tricky, with IncludeUpload) then they don't have the data to base the table-of-contents on.

This recipe solves that problem by generating the table-of-contents with JavaScript, which is run after the page has finished loading, so all the data is there.

Of course, the downside is that it requires JavaScript to be turned on; which many users and browsers may not. Caveat emptor.

Notes

Activation

To activate this recipe, unzip the archive; this will create a handytoc-(version) directory; you then need to move or copy the contents of this into your pmwiki directory. The directory contains:

cookbook/handytoc.php: File contains markup and functions.
pub/handytoc/: Directory contains CSS and JavaScript files.

Add the following line to your local/config.php:

include_once("$FarmD/cookbook/handytoc.php");

Usage

The simplest usage is to just put the (:htoc:) directive on the page where you want to have a table-of-contents.

You can add a title to your table of contents simply by adding it to the directive:

(:htoc This is my table of contents:)

There are also options.

Option	Example	Description
start	start=2	What level of header the table of contents starts at
end	end=3	What level of header the table of contents ends at
ignoreh1	ignoreh1=true	The ignoreh1= option can be either true or false. If true, then if there is only one H1 header in the content, then it will be ignored. If false, it won't be (providing that the start option equals 1).
class	class=htoneline	set the class name for the div that the table of contents is inside. Useful for additional CSS styling for different kinds of ToCs.

Examples

(:htoc start=2:)

The above will start with h2 headers.

(:htoc end=3:)

The above will end at h3 headers.

Note that if there are no H1 headers inside the content at all, then the table-of-contents will start at level 2 automatically, even of the headers are in an odd order.

Configuration variables

These can be set in local/config.php

Name	Description	Default
$HandyTocStartAt	Define the (default) level the table-of-contents starts at	1
$HandyTocEndAt	Define the (default) level the table-of-contents ends at	6
$HandyTocIgnoreSoleH1	If 'true', then if there's only one h1 header in the content, it will be ignored.	'true'
$HandyTocPubDirUrl	Url of directory where the HandyToc css and js files are	`$FarmPubDirUrl`/handytoc

CSS Styling

The table of contents is put inside a div with id='htoc', and the table-of-contents title (if there is one) is put in a H3 header. While the recipe comes with its own CSS styling (in pub/handytoc/handytoc.css) this can be overridden with your own custom CSS in pub/css/local.css

If the "class=" option is used, then the class is set for the same div; that is, it will be

    <div id="htoc" class="classname">

so keep that in mind when using this option.

There is also a .htoneline (handy-toc one line) class in the CSS file, which can be used (with the "class=" option) to make the table-of-contents all on one line, with | separators between each item. This is useful for pages where the headers are, say, single letters of the alphabet (as may happen with indexes). The CSS for this, however, may not work in less-advanced browsers.

Limitations

This does not have a show/hide button like some of the other TOC recipes; if it's defined for that page, then it's there all the time. If you want to show and hide the toc, you can use the Show Hide recipe with markup such as the following:

(:showhide init=hide div=htoc lshow='Show Table of Contents' lhide='Hide Table of Contents':)

Note that this recipe will not work if the skin you are using does not have  markup in it.

Release Notes

(2007-02-18) Added "class=" option, and .htoneline CSS class
(2007-02-17) Put the JavaScript calls into $HTMLFooterFmt only if the markup is present.
(2007-02-11) Added $HandyTocIgnoreSoleH1 and ignore=h1
(2007-02-08) Now only looks inside #wikitext (page content); also fixed problems with different header levels in random order. Now XHTML compliant!
(2007-02-07a) fixed overlooked bug (forgot to rename something)
(2007-02-07) Initial version

HandyTableOfContents