TIP TableOfContentsPlugin is not installed on Foswiki.org.

TableOfContentsPlugin

Yet another TOC plugin

Description

The %TOC macro, which is a part of the Foswiki core, has been updated to use a real HTML parser to extract headings. That way, a %TOC can be placed in any place you want, such as in a view template or the sidebar of a topic. The standard implementation of %TOC wouldn't allow for this.

The new %TOC is not a complete replacement due to the fundamental difference in operations. The original features, such as rendering a %TOC for a distant topic not directly part of the current page, are missing and may never be implemented.

The plugin will replace the %TOC macro with its own version by default. To use both implementations simultaneously, the $Foswiki::cfg{TableOfContentsPlugin}{ReplaceOriginalTOC} setting can be disabled. The new implementation will be accessible as the %TOC2 macro.

Syntax

Parameter Description Default
header string to be prepended to the result  
format format string for each heading found, see format tokens below
   $indent* <a href="$params$anchor">$text</a>
separator string to be placed between each line of the toc \n
footer string to be appended to the result  
depth maximum depth of headings being displayed, a zero means unrestricted 0
title toc title  
pattern regular expression that headings must match to be included in the output  
global boolean switch to enable "global" vs "local" rendering; in global mode will the toc render entries for the complete document; in local mode will it pick up where a previous toc left off thus rendering partial tocs local

The format string may contain the following tokens:

  • $indent: indentation based on the heading level of a toc entry
  • $text: text of the toc entry
  • $anchor: anchor of the heading to navigate to
  • $params: url params of the page request

Any standard escapes are available as well such as $percnt, $dollar, $n etc.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

NameVersionDescription
HTML::TreeBuilder>=5Required

Change History

30 Apr 2024 keep img tags part of a heading in the toc entry
01 Feb 2024 initial release
I Attachment Action Size Date Who Comment
TableOfContentsPlugin.md5md5 TableOfContentsPlugin.md5 manage 186 bytes 30 Apr 2024 - 11:13 MichaelDaum  
TableOfContentsPlugin.sha1sha1 TableOfContentsPlugin.sha1 manage 210 bytes 30 Apr 2024 - 11:13 MichaelDaum  
TableOfContentsPlugin.tgztgz TableOfContentsPlugin.tgz manage 7 K 30 Apr 2024 - 11:13 MichaelDaum  
TableOfContentsPlugin.zipzip TableOfContentsPlugin.zip manage 11 K 30 Apr 2024 - 11:13 MichaelDaum  
TableOfContentsPlugin_installerEXT TableOfContentsPlugin_installer manage 4 K 30 Apr 2024 - 11:13 MichaelDaum  
Topic revision: r2 - 30 Apr 2024, MichaelDaum
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy