Revision [4482]
This is an old revision of TableofcontentsAction made by JavaWoman on 2005-01-11 19:26:03.
Table of contents Action
See also:
Documentation: TableofcontentsActionInfo.Last edited by JavaWoman:
code blocks mentioned
Tue, 11 Jan 2005 19:26 UTC
code blocks mentioned
Tue, 11 Jan 2005 19:26 UTC
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 JavaScript 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:
- AndreaRossato's TableOfContentsPseudoAction (note: code removed! license issue; but see CoMaWiki example below...)
Analysis
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.To get an idea of how a table of contents may be produced, let's look in more detail at a few examples from other Wiki engines. None of the examples presented below requires the user to manually add link targets in the code; they are all automatically created in some way. The examples do differ in whether a table of contents (making use of these link targets) is created automatically, or whether the user has to "request" it by inserting an action code or some kind of tag; where a TOC is generated automatically, this may happen only under certain conditions, or may be suppressed by the user by means of a special tag (i.e., the opposite of requesting it). Another possible difference is whether link targets are produced even when no table of contents is generated.
Example 1: WikiNi
Description:
Proposal(s) only, apparently. The proposed 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:
pro:
(Can't really find any)
con:- Anchor names are deprecated (but just numbers cannot be used as IDs!)
- Using actual headings in the table of contents makes for a confusing (and not very accessible) page structure by effectively creating the same structure twice, once without content and once with; it seems headings in the TOC are used mostly for appearance, disregarding their role as major structural elements
- Using consecutive numbering makes the link targets very susceptable to changes in a page's structure and effectively prevents reliable linking into a page from another (or from an external site)
Example 2: Wacko Wiki
Description:
- Link targets are formed by a an (empty) anchor with a name in front of of a heading
- Anchor names are derived by consecutively numbering all headings in a page, preceded by a letter and (apparently) the page ID
- A Table of contents is produced by including an action in the page
- 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 (actually a series of divs)
- The table of contents (itself in a div) is enclosed in a fieldset which provides a legend "on" the box
Pros and cons:
pro:- Using a fieldset with legend is a nice idea to mark up the TOC
- Anchor names are deprecated
- Using consecutive numbering makes the link targets very susceptable to changes in a page's structure and effectively prevents reliable linking into a page from another page (or from an external site)
- While the fieldset markup creates a nice presentation (and syntactically is no problem), its status with respect to semantics and accessibility is not clear: the fieldset element is intended (as its name suggests) to group form controls - not a menu of links.
Example 3: Wikipedia
Description:
- 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
- If an article has at least three headings, a table of contents will be automatically generated. This cannot be suppressed.
- It appears after the introductory text of a page
- Table of contents consists of a single-cell layout table where the hierarchical 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:
pro:- Anchor names are deprecated but ids are included as well - this is apparently done to ensure compatibility with a wide range of browsers
- The ability to hide the TOC (provided JavaScript is enabled) is very nice
- Anchor names are deprecated
Example 4: DokuWiki
Description:
- 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; this can be suppressed by ading a special code in a page
- 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:
pro:con:
- Anchor names are deprecated
Example 5: CoMaWiki
Example page and an example of a variant (The same code is used in UniWakka - see notes on TableOfContentsPseudoAction.)
Description:
- Link targets are formed by an (empty) anchor with an name in front of a heading
- Anchor names are derived by consecutively numbering all headings in a page, preceded by a fixed string
- The table of contents is generated by inclusion of an action in the page
- Since the table of contents is produced by an action, it appears in the page at the location where the action is included; regardless, all headings are included, even the ones appearing before the location of the action code
- Both table of contents links and headings may be hierarchically numbered by using a variant of the action
- While it visually seems like a hierarchical list, it is actually a flat list, with styled indents to create the appearance of a hierarchy
- The table of contents (itself in a div) is enclosed in a fieldset which provides a legend "on" the box
Pros and cons:
pro:- Using a fieldset with legend is a nice idea to mark up the TOC
- Anchor names are deprecated
- Using consecutive numbering makes the link targets very susceptable to changes in a page's structure and effectively prevents reliable linking into a page from another page (or from an external site)
- TOC is only visually a hierarchical but not structurally - this presents an accessibility problem
- TOC numbering (optional) is nice but no option to number only the link texts but not the headings themselves; also the numbers don't appear in Preview mode when editing - only when the page is stored
- While the fieldset markup creates a nice presentation (and syntactically is no problem), its status with respect to semantics and accessibility is not clear: the fieldset element is intended (as its name suggests) to group form controls - not a menu of links.
Specifications
Now let's see what we need, and try derive some specifications based on our analysis. We'll have a few essentials, and a few would-be-nice items.One unescapable essential is that a table of contents needs link targets - and these must come into existence somehow. Headings, forming the basic structural element of (HTML) pages, are the natural candidates for such link targets (a table of contents can then make use of the text of these headings as link descriptions). Other potential targets, useful in documentary type of content, are (data) tables and images (graphs, screen shots...); code blocks are yet another candidate for targets.
Essentials
What else?
How
CategoryDevelopment