• View
• Edit
• History
• Attach
• Print
• Backlinks

SlimTableOfContents

Questions answered by this recipe

Can I have a Table Of Contents that works together with the SectionEdit recipe?

Description

With a single markup this recipe adds a simple or numbered table of contents to the current page.
The TOC contains the headings of the page and its (:include:)d pages.
When JavaScript is enabled the TOC can be toggled from open to closed.

Activation

Download slimtoc.zipΔ and unzip it.
The archive contains two files:

slimtoc.php

Script file contains markup and functions.
Move or copy it to your cookbook directory

slimtoc.css

Stylesheet for the TOC.
Create a slimtoc subdirectory in your pub/ folder and move or copy the file into that folder.

Hint for WikiFarms: The script tries to find the stylesheet in the local pub/slimtoc/ folder; if that fails it will look for it in the farm's pub/slimtoc/ directory ($FarmD/pub/slimtoc/). If the slimtoc.css can't be found it will write the default styles into the HTML <header>.

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

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

The recipe requires

• cookbook SignalWhenMarkup otherwise the numbered TOC can't calculate its numbers correctly when disturbed by (:toc:)s in (:markup:).
• cookbook MarkupToUnstyled to retrieve the - properly unformatted - text of the headings for the TOC.

So please install those recipes too.

Usage

Simple TOC

To create a simple table of contents just put a

(:toc:)

directive on the page.

TOC will include all headings down to level $TocLevelMax (default=4, meaning !!!!, configurable)
The headings with the highest level won't be indented even if the highest present heading has only !!two exclamation marks. Headings from lower levels will be indented appropriately.
The script compensates <ul> / indents for missing levels.

Numbered TOC

To create a numbered table of contents use the

(:#toc:)

directive - toc with a # in front.

Numbers will be applied to all headings down to level $TocLevelMax (default=4, meaning !!!!, configurable)
The headings with the highest level will receive Number 1, 2 etc. even if the highest present heading has only !!two exclamation marks. Headings from the next lower level get the 1.1, 1.2, 2.1 etc. etc.
The script compensates for missing levels.

Configuration

These can be set as usual in local/config.php (before including the script):

CSS Styling

If you want to change the styling - edit slimtoc.css or override the styles within your own custom CSS in pub/css/local.css.

Hint: Don't search for graphics producing the triangles in the TOC's header - they are created via border-style and <span>s.

Notes

The recipe

• creates one TOC at the position of the first (:toc:) statement it detects. The TOC will contain all page headings from that point onwards.
• excludes headings inside of (:markup:) from the TOC.
  An exception are (:markup:)s containing (:toc:) directives - an extra TOC will be created for the (:markup:) with headings token from the (:markup:) sequence. For each (:markup:) separately.
• is compatible with SectionEdit
• mutually excludes other TOC-recipies like Page Table of Contents or Numbered Headers

The recipe requires cookbook SignalWhenMarkup otherwise the numbered TOC can't calculate its numbers correctly when disturbed by (:toc:)s in (:markup:).
And it requires cookbook MarkupToUnstyled to retrieve the - properly unformatted - text of the headings for the TOC.

Todos/MayBes

Enhance the (:toc:) markup with options for

• caption
• level
• startclosed Yes... PLEASE!
• "back-to-toc" Links

Release Notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

• (2009-02-26) use MarkupToUnstyled for proper TOC items
• (2009-02-01) Initial version

See Also

Tables of content:

Contributors

Comments

See discussion at SlimTableOfContents-Talk

Why do you check ($currlevel > $lastlevel) near line 300 in slimtoc.php? The script seems to work just fine without the entire block. The way it is now, if someone has, say, a !!header and then a !!!!header, you get something like this:

• Header
  • • Header

as opposed to

• Header

  • Header

This seems counterintuitive, but maybe I am missing some other need for this code...

April 19, 2009 --Peter Kay

Guess it's because I don't like <dl>'s. If the checking code is omitted pmwiki mixes <dl>'s into the TOC's <ul>'s. And then you get things like this:

• Header level 1

  • Header level 3
    • Header level 4

• Header level 1
  • Header level 2
    • Header level 3
      • Header level 4
  Same levels should have the same formatting / indent / square-style.
  By the way: Why would you omit a level? I sometimes jump from h1 to h3 when I don't like the styling of h2 - with an ugly feeling of disturbing the logic of my document - Tontyna May 08, 2009, at 03:42 PM

  Aaah - I hadn't noticed that you get different styles at the same level if you use the <dl> notation; thanks for pointing it out. I was paying so much attention to the extra hanging dot, I never noticed. I suppose I could have it both ways if I were to specify style in a css file with something like style="two-deep", etc. As to skipping levels? People do it all the time if they don't like how one level looks, or they forget what level they're on, etc. I'm afraid the non-computer people I know don't care very much about "document logic"! :) --Peter Kay