Building a TOC with more information

  • Tip Category - Using Extensions
  • Tip Added By - StefanAlthoefer - 10 Jan 2010 - 13:44
  • Extensions Used - FilterPlugin
  • Useful To - Beginners
  • Tip Status - New
  • Related Topics -

Problem

Then and now I have any kind of ToDo/Bug Lists to maintain, which are not under control of any action- or bug-tracker. E.g. after a meeting with a customer I document the discussed issues in T/Foswiki. But if it becomes a longer topic it becomes hard to get an overview about current state of all issues.

Context

This tip presents a technique to generate a table of contents with more information then just the headings. It uses the FilterPlugin to build such a table.

Solution

Here is how it looks like (simulated):

Grafik1

Detailed explanation follows below.

Writing content

Each level-2 heading in the document is followed by some extra information right after the heading. This looks as follows in TML:

---++ Analog Input Performance
#AnalogInputPerformance
| Bob Peace | %WIP% |

The first line is the normal level-2 heading. The second line is an anchor as described in TextFormattingRules (Just a # with a unique WikiWord). Finally the third line is a small table of two columns where the first one is the person responsible and the second column is the state. I prefer to use icons from DocumentGraphics for the state.

In this case I created a shortcut for the %ICON{}% syntax by adding the following line to Main.TWikiPreferences:
   * Set WIP = %ICON{"wip"}%

Building the table of contents

FilterPlugin is now utilized to search the document for all level-2 headings and build a table of them.

The whole thing looks like this:
%EXTRACT{topic="%TOPIC%" expand="off" 
pattern="^---\+\+ (.+?)[\r\n]+#([a-zA-Z0-9_]*?)[\r\n]+\| (.+?) \| (.+?) \|" 
format="| [[#$2][$1]] | $3   | $4   |$n"
header="| *Topic*  | *Responsible*  | *State* |$n"
}%

The option expand="off" forces FilterPlugin to process %TOPIC% before any TML processing. Therefore it sees the raw TML markup. If you don't use this, then FilterPlugin sees the expanded HTML syntax, which is harder to process.

The pattern utilizes Perls non-greedy (or minimal-matching) quantifiers. The slice ^---\+\+ (.+?)[\r\n]+ is interpreted as follows: Match ---++ at the beginning of a line followed by characters as long as one or more \r or \n characters appears. Literally meant plus signs ( +) and vertical bars ( |) have to be quoted in the pattern as they have special meaning.

Everything in the pattern that is enclosed in brackets ( (...)) is saved for later use.

The format parameter of %EXTRACT% specifies the output to be produced for any pattern match. In this case it just builds a table row with the previously match data:
  • $1: The level-2 heading text
  • $2: The anchor (so we can jump to the heading by clicking)
  • $3: The responsible person
  • $4: The state

Known Uses

Known Limitations

See Also

BestPracticeTipsForm edit

Category Using Extensions
I Attachment Action Size Date Who Comment
demo_screenshot.pngpng demo_screenshot.png manage 38 K 10 Jan 2010 - 13:27 StefanAlthoefer  
Topic revision: r1 - 10 Jan 2010, StefanAlthoefer
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