Created by: gwideman, Nov 1, 2010 7:08 pm
Revised by: gwideman, Apr 12, 2011 8:25 pm (27 revisions)

Introduction

This page describes my approach to implementing a site Table-of-Contents for Wikispaces. This addon includes:

  • An expandable/collapsible treeview to display the site-wide TOC
  • Good control of the position of pages in the site TOC
    • Hierarchy: parent heading or page with child pages
      • Any number of levels.
    • Ordering among sibling pages
    • Intervening fixed section headings
  • Simple management of the items and their positions
    • Controlled by a single page
    • Easily edited in Visual or Wikitext editor
  • Additional related features:
    • Auto sync: When a page loads, the treeview automatically opens branches to show the item of the current page, and its siblings
    • Previous/Next links optionally at top and bottom of page
    • Separate maintenance page to check that existing pages are in the TOC, and that TOC links point to existing pages

The effect can be seen on this site, in the left sidebar.

Background: an approach to managing navigation among pages

A site which offers a collection of pages must deal with how to facilitate navigation among them. There tend to be two main relationship to take into account:

  • Parent-child relationship: Some pages are subordinate to some more general page, or simply subordinate to some larger topic headng.

  • Order among "sibling" pages: Some pages present a sequence of topics which are best visited in a particular order.

Some wiki or wiki-like systems already implement the parent-child relationship as a property of each page, and this provides a basis for a navigation tree as a "free" side effect. However, I have not see a system that successfully handles the issue of the ordering of sibling pages. It is almost never sensible to just order sibling pages alphabetically, and setting a "comes after" or "comes before" relationship is sure to break as other pages are added.

The conclusion from this is that it makes considerable sense to implement a navigation scheme based on simply manually listing the hierarchy and order of pages, and this is the scheme adopted here. Furthermore, this allows listing in the hierarchy additional pages not a part of the site per se, omitting pages not ready for consumption, or even listing pages twice.

Simple ongoing management of Site Table-of-Contents

After the Site TOC components have been installed (details below), management of the items and their positions in the TOC tree revolves around a single ordinary wiki page (SiteTOCMaster). On this page you arrange the desired links in one or more bullet lists, possibly with intervening headings. Here is the actual SiteTOCMaster page for the current site: SiteTOCMaster.

Once you accumulate a large number of pages, it can be challenging for the TOC maintainer to keep track of which pages have indeed been added to this TOC list. To help with that, a second "list of all pages" page is a very useful maintenance aid: List of all pages

That page presents two lists: the list of all pages on the site, and the TOC list. The items are colored to indicate which ones appear on both lists, and which ones are found only in one list or the other. From this you can quickly determine which pages have yet to be added to the TOC, and which TOC items fail to point to an actual page (perhaps you deleted or renamed the page).

Technical documentation


Overview of addon components

More complete instructions appear in sections below, but first here is a preview of what is involved.

The main addon is implemented via the following components:

  • addonSiteTOC.js Code which implements the expandable tree behavior
  • addonSiteTOC.css Style for tree and related TOC elements
  • SiteTOCMaster page: User maintains one or more bulleted lists on this page to specify hierarchical list of items to appear in the table of contents.
  • addonSiteTOC.nav page: This page serves to includes the SiteTOCMaster page, provide a heading, and wraps the whole thing in a div (id="gwsitetoc") that the javascript will recognize and transform into the expandable tree.
  • Images:Small images for expand, collapse and bullet, for the treeview

The above items are incorporated into a site using revisions to the following existing wikispaces components

  • space.menu page: In the usual space.menu page, include the addonSiteTOC.nav page
  • Site theme: Revise the theme so as to load the CSS and javascript, and to specify the position of Next/Prev navigation features.

Component relationships


The components of the SiteTOC addon are shown in the following figure:

img-sitetoc-001.gif
(Note: the expand/collapse images shown here are representative. You could use triangles, or other symbol images.)

Installation


1. Obtain files:


  • addonSiteTOC.css and addonSiteTOC.js Look in left sidebar Site Contents > Addon Components > Site TOC. for the css and js files used on this site. You may want to change the styles in the css file, but it is good as a starting example.

  • Save these Images:
    • gwtoc_bullet.gif gwtoc_bulletsq.gif
    • gwtoc_closed.gif: gwtoc_closed.gif
    • gwtoc_opened.gif: gwtoc_opened.gif

2. Add to the theme file:

Before starting, back up a copy of your current theme to a file on your local machine.

At the end of the head region (JS/CSS [1] in the figure):
<link rel="stylesheet" type="text/css" href="/file/view/addonSiteTOC.css" />
At the beginning of the body region (JS/CSS [2] in the figure).
<script src="/file/view/addonSiteTOC.js"></script>
If you want to add the Prev/Next navigation feature, then also modify the "wikiBody" area of the theme to include one or both of the tables (shown in the example below), which become the targets in which the javascript places the Next/Prev links.
  <div id="wikiBody">
    <$WikiNotices$>
 
    <table class="gwsitetoc_navtable_top">
      <tr>
      <td class="gwsitetoc_navprev">&nbsp;</td>
      <td class="">&nbsp;</td>
      <td class="gwsitetoc_navnext">&nbsp;</td>
      </tr>
    </table>
 
    <$WikiPageMenuPermissionIcon$>
    <$WikiPageMenuTitle$>
    <$WikiPageMenuEntries$>
 
    <div class="wikiBox">
      <$WikiContent$>
    </div>
 
    <table class="gwsitetoc_navtable_bottom">
      <tr>
      <td class="gwsitetoc_navprev">&nbsp;</td>
      <td class="">&nbsp;</td>
      <td class="gwsitetoc_navnext">&nbsp;</td>
      </tr>
    </table>
 
  </div>
Note: Your theme may have the wikibody section organized somewhat differently. The important thing is to get the gwsitetoc_navtable_top and/or gwsitetoc_navtable_bottom tables placed where you want them.

3. Create TOC Master page

SiteTOCMaster: On this page, create a bulleted list containing links to other pages. These links will appear in the TOC
See example in the current site: SiteTOCMaster

addonSiteTOC.nav: Here create a div (id="gwsitetoc") wrapped around a head, and an include for SiteTOCMaster.
Example:
[[media type="custom" key="7087327"]]**Site Contents**
[[include component="page" page="SiteTOCMaster" ]]
[[media type="custom" key="7087329"]]
...where the "Other html" widgets ( media... ) contain:
<script type="text/javascript">
 document.write('<div id="gwsitetoc">');
</script>
and
<script type="text/javascript">
 document.write('</div>');
</script>

4. Include addonSiteTOC.nav in space.menu


Use an "include other page" widget to include addonSiteTOC.nav into the space.menu page.

5. "List of all pages" maintenance page


This page is an important aid for maintaining the TOC. See the example here: List of all pages. This is really quite a simple page, but it's slightly tricky to explain how to construct it.

First a sketch of the structure:


List of pages for admin purposes
... blah blah
[ ] Color on/off
"List of existing pages"
"Table of contents tree"
[div id="gwsitetoc_check_pagelist"]
Include wikispaces all-pages list
[/div]
[div id="gwsitetoc_check_toc"]
Include SiteTOCMaster page
[/div]
Include widget to run the javascript for the functions on this page.

Unfortunately, we have to resort to some snippets of javascript to include the div and /div tags. So the upshot of all this is that there are several widgets on this page which you have to compose manually. So here are the full details:

The overall page:
==List of all pages for admin purposes==
With color enabled:
* Green means this item was found in the other list
* Red means this item was not found in the other list
 
|||| [widget 1 color] ||
||~ List of all existing pages ||~ Table of contents tree ||
|| [widget 2 div id="gwsitetoc_check_pagelist"] {UNBREAK}
[[include component="pageList" hideInternal="true" homeAtTop="on" limit="1000"]] {UNBREAK}
[widget 3 /div] || {UNBREAK}
[widget 4 div id="gwsitetoc_check_toc"]  {UNBREAK}
[[include component="page" page="SiteTOCMaster"]] {UNBREAK}
[widget 5 /div] ||
 
----
 
Test Site TOC widget:
[[widget 6 page functions]]
 
----
 

NOTE: I have broken some of the lines here for readability. To restore, remove and unwrap each of the {UNBREAK}s. The resulting table should contain three-rows. (Again, see the example page.)

Here are the javascript widgets:
Widget 1: color
---------------
<form action="http://somesite.com/xyz" method="post"><input type="checkbox"
name="check1" value="Check1" checked="checked"
onclick="gwsitetoc_checker_colorenable(this.checked);" /> Color enable</form>
 
Widget 2: div id="gwsitetoc_check_pagelist"
---------------
<script type="text/javascript">
  document.write('<div id="gwsitetoc_check_pagelist" class="gwsitetoc_check_colorenable">');
</script>
 
Widget 3: /div:
---------------
<script type="text/javascript">
document.write('</div>');
</script>
 
Widget 4:
---------------
<script type="text/javascript">
  document.write('<div id="gwsitetoc_check_toc" class="gwsitetoc_check_colorenable">');
</script>
 
Widget 5: /div
---------------
<script type="text/javascript">
document.write('</div>');
</script>
 
Widget 6: page functions
---------------
<script type="text/javascript">
  jQuery(function($) {
    gwsitetoc_checker_docready($);
  });
</script>
 
Note: The form section is not actually used to submit anything, just to contain the checkbox. The "somesite.com" is a fake URL to satisfy the required syntax.

Maintenance

As pages are added or removed from the site, the site maintainer will edit the SiteTOCMaster page accordingly.

This task is made easier using the "List of all pages" maintenance page, which provides two useful features:
  • It compares the existing SiteTOCMaster page to the complete list of all pages in the site.
  • When the site maintainer is editing the SiteTOCMaster page, the "List of all pages" can be a source of links to copy/paste to the TOC.

Feature documentation

(This is an older summary. Might not be needed any more.)

The Table-of-Contents treeview

  • Basically the treeview contains SiteTOCMaster's list, with added classes and CSS
  • Can expand and collapse
  • Javascript sets tree to open to current page
    • Current "path" indicated by different style (eg: bold)

SiteTOCMaster page

Edit this page to edit the list which will appear in the TOC treeview.

Previous/Next

Implementation: Done
Requirements: Provide target tables in theme.

"List of all pages" maintenance page

Implementation: Done
  • Compares list of all site pages to listing on SiteTOCMaster
    • Pages that are in the TOC and exist, green in both lists.
    • Pages in one list but not the other: red
      • In TOC not in actual pages = broken link
      • In actual pages not TOC = page not listed in TOC
      • Still to implement: Mark pages that appear more than once in TOC

Breadcrumbs

Implementation: To-do (not high priority, since its function overlaps with the auto-sync of the TOC tree.)
Requirements:
  • Get xxx > xxx > this-page from SiteTOCMaster data
  • Small text size, stuff each title into cell and wrap. (Consider ellipses?)



Page Info
Image prefix: img-sitetoc-nnn.gif/jpg