TableofcontentsAction:Wikka

Table of contents Action

Navigating a page

A long Wiki page can be hard to navigate. For the reader to navigate a page easily, a number of things are needed:

A quick way to determine what a page is about

A clear page structure with sections labeled with headings

A means of quickly going to a section of interest

A way of finding your way back to a section you've seen before

Some of this simply depends on how the page is written: the writer should keep the reader in mind who sees the page for the first time! A good page title, supplemented with a short introductory text helps with point 1. A clear hierarchical page structure (created by sectioning and preceding the sections with headlines) will make the page easily scannable when scrolling through it - that takes care of point 2.

But even on a page that is clearly labeled and sectioned, just getting an overview by scrolling and scanning can be hard work, and the longer the page is, the harder it becomes to find your way back to a particular section you'd noticed or just want to read again.

Navigation help

While our first two points, showing what a page is about and giving the page a clear stucture, obviously depend on writing, navigating a page can be greatly helped when it has an in-page Table of contents (TOC). In general, a TOC appears near the top of the page and contains a list of section headings that serve as links to those sections. It is even more helpful if such a table of contents can show the hierarchical structure of the page and in that way gives a clear overview without even needing to scroll through it.

In order to accomplish this, some of our "colleague" Wiki engines provide a way to (semi-)automatically create a table of contents. In some of them, this happens completely automatically, in others the page author must include a code or tag in the page to trigger this process. A prime example of a good and user-friendly table of contents can be seen in Wikipedia (example); it has a nice feature of allowing the visitor to show or hide its contents with a single mouseclick (provided they have JavaScript enabled).

WikkaWiki does not have such a feature. Apart from not being able to construct a TOC automatically, even doing it manually is not (yet) possible since that requires a method of section linking which we don't have either: you need link targets, as well as a linking syntax to allow this.

The need to be able to construct a TOC in WikkaWiki clearly exists though, since a few proposals for WikkaWiki are already floating around in this site, such as:

AndreaRossato's TableOfContentsPseudoAction (note: code removed! license issue; but see CoMaWiki example below...)

DotMG's AnchorAction

FatherNitwit's SimpleTableOfContents

Also there has been some pressure to adopt the code from another engine (which should be somewhat easy if it's another WakkaWiki clone).

Analysis

Before rushing to adopt one of these proposals (or something else yet again), let's see what a Table of contents action actually can (or should) provide to serve as a good page navigation tool. To get an idea of how a table of contents may be produced, and how they work, let's look in some 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 (which would enable section linking within a page and from other pages, whether or not there is a TOC).

Example 1: WikiNi

Development page

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

Example page | reference

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

con:

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)

unclear:

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

Example page | reference

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

Having at least four headers on a page triggers the TOC to appear in front of the first header (or after introductory sections).

It can be put somewhere else with a special tag, or suppressed with a special tag

Headings can be kept out of the toc by using HTML markup instead if Wiki markup

When a TOC is suppressed, you can make one manually (which implies targets are generated independently)

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

con:

Anchor names are deprecated

Example 4: DokuWiki

Example page

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

con:

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

unclear:

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

CategoryDevelopmentActions CategoryUserContributions

Comments

Comment by GeorgePetsagourakis

2005-01-10 13:36:51

this I think requires a major rethinking and poss rewriting of the Category system so that it is efficient and so that it presents the ability for further possiblities and a cleaner code within the core ...

The wikka_pages mysql table should be better structured to accomodate this imho ...

Comment by JavaWoman

2005-01-10 16:19:55

George,
As we've already discussed on the #wikka channel, this page is about generating in-page tables of contents - based on the structure of the page itself.

While I agree we need an overhaul of our category system (see CategorySystemOverhaul), that doesn't interact in any way with page-level TOCs which are needed as well - a sitemap type of functionality (where the Category system would come into play) is something else entirely, though...

Comment by NilsLindenberg

2005-02-01 14:35:31

Nother example: http://www.calitrix.de/EinfacheFormatierungen

Comment by nme-nxg-pr3.tpgi.com.au

2005-02-16 06:34:33

I have tried almost every php based Wiki around. I have been looking for a Wiki that supports a Table of Contents. DokuWiki is simple & Quick. MediaWiki is has the Hide ToC and {NoToC} features which are Great!. WakoWiki is also very simple. The bottom line for me is;

1) Base the ToC on the Headings is H1, H2, H3, make the depth of the ToC a default i.e. ToC by default is 3 headings deep or {{ToC depth="4"}} as a page based override.

2) Global config should include {ToC} On or Off

3) Optional turn off {NoToC} for each page

4) Media Wiki also supports {compactToC} which is also a good feature.

Comment by cpe-70-112-172-161.austin.res.rr.com

2005-03-26 02:47:07

Another approach:
(a) use DIVs for sections in page structure, not Hn
(b) allow sections to be expanded and collapsed, usnig CSS display: none and some Javascript that keys of class=collapsed | expanded.
(c) can still build TOC either from Hn or DIVs with class=collapsed | expanded.

// Usage:
// <div class="collapsed" | "expanded">
// ...first child with non-whitespace text element will get +- image tag.
// ...subsequent children will show/hide
// </div>
// After loading, first-child has onclick + :before display of +/- icon
// ...all other children are hidden or unhidden by click

function getElementsByClass(classname){
var allElements=document.all? document.all : document.getElementsByTagName("*")
var customCollection = []
var inc=0
for (var i=0; i<allElements.length; i++){
if (hasClass(allElements[i], classname))
customCollection[inc++]=allElements[i];
}
return customCollection;
}

function hasClass(node, classname) {
return (node.className.search(classname) != -1)
}

function addClass(node, classname) {
node.className += (" " + classname + " ")
}

function replaceClass(node, oldclass, newclass) {
if (hasClass(node, oldclass)) {
node.className = node.className.replace(oldclass, newclass);
}
else { addClass(node, newclass); }
}

function toggleExpanded(node) {
hasClass(node, "expanded") ? replaceClass(node,"expanded","collapsed") : replaceClass(node,"collapsed","expanded");
var first = node.firstChild;
if (!first) { return; }
for (var child = first.nextSibling; child; child = child.nextSibling) {
if (hasClass(node, "collapsed")) {
replaceClass(child, "revealed", "concealed");
}
else {
replaceClass(child, "concealed", "revealed");
}
}
}

addEvent(window,"load",initCollapsibleBlocks);

function addEvent(o,e,f) {
if(o.addEventListener) { o.addEventListener(e,f,true); return true; }
else if(o.attachEvent) { return o.attachEvent("on"+e,f);}
else { return false;}
}

function initCollapsibleBlocks() {
var collapsed = getElementsByClass("collapsed");
var expanded = getElementsByClass("expanded");
init_collapsible_block_list(collapsed, "concealed");
init_collapsible_block_list(expanded, "revealed");
}

function init_collapsible_block_list(blocks, reveal_or_conceal) {
for (var bi=0; bi < blocks.length; bi++) {
var block = blocks[bi];
var first = block.firstChild;
if (first) {
first.onclick = toggleExpandedClosureOn(block);
}
for (var ci=1; ci < block.childNodes.length; ci++) {
var child = block.childNodes[ci];
addClass(child, reveal_or_conceal);
}
}
}

function toggleExpandedClosureOn(element) {
var toggler = function() { toggleExpanded(element); }
return toggler;
}

Comment by RodMcFarland

2007-06-25 20:37:29

I made one, but it was kind of messy. It operates semantically (i.e. it takes Hn as the actual heading level). See it in action at [[http://wiki.lidc.sfu.ca/TechoneWebct this page]], for example. It operates essentially by running the page through the formatter, then parsing the headers out of it and inserting a TOC where the ""{{toc}}"" action is.

Wikka : TableofcontentsAction