Revision [4376]
This is an old revision of TableofcontentsAction made by JavaWoman on 2005-01-10 10:56:41.
Table of contents Action
See also:
Documentation: TableofcontentsActionInfo.What
Many people wish for an easy way to build a table of contents for a page - preferably by simply including an action tag. Some of our "colleague" Wikis already have such a thing, and there has been some pressure to adopt their code (which should be somewhat easy if it's another WakkaWiki clone). A prime example of a good and user-friendly table of action can be see in Wikipedia (example), which has a nice feature of allowing the visitor to show or hide its contents with a single mouseclick (provided they have JavaScipt enabled).Why
When you look at long Wiki pages, the need for a table of contents becomes immediately apparent: when a lot of scrolling is needed to see all of the page's content, it also becomes hard to get an overview of what is on the page, and to find your way back to a section you've seen before. A table of contents block at the top of the page, linking to the page's sections using the headings as link text, fulfills both needs. It is even more helpful if such a table of contents can show the hierarchical structure of the page (as in the Wikipedia example).Not surprisingly, a few proposals are already floating around in this site, such as:
Specifications
Before rushing to adopt one of these proposals (or something else yet again), let's see what a Table of contents action actually should do to fulfill all these needs. We'll have a few essentials, and a few would-be-nice items. To start this, let's look in more detail at a few examples.Example 1: WikiNi
Example pageDescription:
Proposal(s) only, apparently. The apparently most worked-out solution has these properties:- Link targets are formed by an anchor with the heading text as its content and a name (note there's a comment about name being deprecated in XHTML)
- The anchor name is a just a number, derived by consecutively numbering all headings in a page (there is also a proposal of using the heading texts instead)
- A Table of contents is produced by including an action in the page (while the targets are produced by the Formatter)
- Since the table of contents is produced by an action, it appears in the page at the location where the action is included
- Table of contents consists of a flat list containing links with as link description the actual headings of the page (i.e., complete hn elements)
Pros and cons:
Example 2: Wacko Wiki
Example page (http://wackowiki.com/WackoDocumentation/WackoFormatting?v=na#h7705-11)Description:
Pros and cons:
Example 3: Wikipedia
Example pageDescription:
- Link targets are formed by a paragraph containing an (empty) anchor with both name and id in front of a heading
- Anchor name and id (identical, as they must be) derived from the text of the heading
- A table of contents is automatically generated (condition?)
- It appears after the introductory text of a page
- Table of contents consists of a single-cell layout table where the hierachical display is accomplished by nesting divs; items are dynamically and hierarchically numbered; link descriptions are formed by the texts of the actual headings
- Initial state of the TOC is fully shown, this state can be toggled to (and from) "hidden" by means of a JavaScript function
Pros and cons:
Example 4: DokuWiki
Example pageDescription:
- This can be suppressed by ading a special code in a page
- Link targets are formed by a an (empty) anchor with a name in front of of a heading
- Anchor name is derived from the text of the heading
- If there are more than 3 headings in a page, a table of contents is automatically generated
- It appears as a side bar at the top of the page (it's a div at the start of the page content)
- Table of contents consists of a hierarchical (unordered) list; link descriptions are formed by the texts of the actual headings
Pros and cons:
What else?
How
CategoryDevelopment