AutoTOC

Summary: Unobtrusive Automatic Table of Contents Version: 20111019 Prerequisites: Status: Beta Maintainer: Petko Categories: Menus, TOC, Layout, WikipediaSuite Users: (view? / edit) Discussion: AutoTOC-Talk?

An Automatic Table of Contents for wiki pages. If JavaScript is enabled in your browser, you should see it below this paragraph.

Description

testtesttest
testtesttest
testtesttest

For an intranet wiki, I needed a really basic, simple and fast Table of contents, that:

  • works in all existing pages without the need to edit them and add some markup,
  • works even when the headings in the page are not in a logical hierarchy,
  • works even when the headings in the page come from included pages or from pagelists,
  • works with the TOC block either in the wiki page, or in the SideBar,
  • can be disabled on some pages,
  • can be moved to a different place in a page,
  • can be shown or hidden by the users and their preferences can be remembered,
  • wouldn't risk to break some complex local recipes on that wiki.

AutoTOC was inspired by the tables of contents in Wikipedia:

  • a page with less than 3 headings is usually short and doesn't need a TOC
    • it is possible to force a TOC for 1-2 headings with a special markup
    • it is possible to disable the TOC for 3+ headings with a special markup
  • the TOC is automatically inserted right before the first heading in the page and after the short introduction / summary
    • it is possible to place the TOC anywhere in a page with a special markup.

Installation

  • Copy autotoc.php Δ to your pmwiki/cookbook directory.
  • Copy autotoc.js to your pmwiki/pub directory.
  • Add to config.php such a line:
    if($action=='browse') include_once("$FarmD/cookbook/autotoc.php");

Usage

  • A reader can show or hide the Table of contents with a show/hide link. The TOC state (open or closed) will be remembered when the reader opens another page.
  • A page with 3 or more headings will have the Table of contents inserted right before the first heading.
  • The wiki markup (:toc:) at the beginning of a line places the table of contents there, even if there are less than 3 headings.
  • The directive (:notoc:) disables the Table of contents.

Configuration

To select the levels of the headings included in the Table of Contents, set in config.php, before including the recipe, such a line:

  $AutoTocMaxLevel = 3; 

Setting 3 will mean !, !! and !!! headings will appear in the TOC; default is 6, ie. ! to !!!!!!.

To select the minimal number of headings in a page which enable Tables of contents, set in config.php, before including the recipe, such a line:

  $AutoTocNbHeadings = 4; 

Default is 3 headings, a page with fewer headings than this number will not display a TOC unless it has the (:toc:) markup.

If you want TOCs appearing not automatically on all pages, but only in pages with the (:toc:) markup, set the $AutoTocNbHeadings variable to a very big number like 999.

Internationalization

International wikis can translate? the following strings, eg. in a French XLPage:

  'Contents' => "Sommaire",
  'show' => "afficher",
  'hide' => "masquer",

Notes

The browser of the visitor needs JavaScript to be enabled.

Change log / Release notes

  • 20111019 : fix bug with tables
  • 20111018 : headings inside (:markup:) blocks are now skipped from the table of contents.
  • 20111008 : generated anchors changed from numeric incremental to a simple encoding of the heading text, outlined at PITS:00955, for example #Installation.
  • 20111007 : fix HTML validation bug.
  • 20111006 : fix indentation to the lowest common level of headings in the page.
  • 20111005 : added $AutoTocNbHeadings.
  • 20111004 : first public release, ready to be tested.

See also

Contributors

Recipe written and maintained by Petko.

Comments

See discussion at AutoTOC-Talk?

Tes~t with tab'les

testtesttest
testtesttest
testtesttest

Another table

ab
 0: 00.00 MarkupToHTML begin
 1: 00.12 FPLTemplate: Chain begin
 2: 00.12 FPLTemplate: FPLTemplateLoad
 3: 00.13 FPLTemplate: FPLTemplateDefaults
 4: 00.13 FPLTemplate: FPLTemplatePageList
 5: 00.13 MakePageList pre
 6: 00.13 PageListSources begin
 7: 00.13 PageStore::ls begin SQLite
 8: 00.13 PageStore::ls merge SQLite
 9: 00.13 PageStore::ls end SQLite
10: 00.13 PageStore::ls begin wiki.d/$FullName
11: 00.14 PageStore::ls merge wiki.d/$FullName
12: 00.14 PageStore::ls end wiki.d/$FullName
13: 00.14 PageStore::ls begin $FarmD/shared.d/$FullName
14: 00.14 PageStore::ls end $FarmD/shared.d/$FullName
15: 00.14 PageStore::ls begin $FarmD/wikilib.d/$FullName
16: 00.14 PageStore::ls merge $FarmD/wikilib.d/$FullName
17: 00.14 PageStore::ls end $FarmD/wikilib.d/$FullName
18: 00.14 PageListSources end count=532
19: 00.14 PageListTermsTargets begin count=532
20: 00.14 PageIndexGrep begin
21: 00.15 PageIndexGrep end
22: 00.15 PageListTermsTargets end count=0
23: 00.15 PageListSort pre ret=4 order=name
24: 00.15 MakePageList items count=0, filters=PageListTermsTargets
25: 00.15 MakePageList post count=0, readc=0
26: 00.15 PageListSort begin
27: 00.15 PageListSort sort
28: 00.15 PageListSort end
29: 00.15 MakePageList end
30: 00.15 FPLTemplate: FPLTemplateSliceList
31: 00.15 FPLTemplate: FPLTemplateFormat
32: 00.15 MarkupToHTML begin
33: 00.15 MarkupToHTML end
34: 00.15 FPLTemplate: Chain end
35: 00.15 MarkupToHTML end
36: 00.16 MarkupToHTML begin
37: 00.19 MarkupToHTML end
38: 00.19 MarkupToHTML begin
39: 00.20 MarkupToHTML end
40: 00.20 now