Web Help - Server-Side Scripted Site

Server-Side Scripted Site

If the server supports server-side scripting, such as PHP, one approach is to assemble the pages from separate source files containing the topics, and the common elements such as the table of contents, index, etc.^[1]

A similar approach is possible if the content is in a content-management system.

From the user's point of view the help site consists of a number of separate pages with URLs such as:

/help?nav=contents&topic=03

or:

/help/contents/03-Associates.html

The demo uses the second of these formats. Click here to open the demo in a new window:

Server-Side Scripted Site Demo

Pros

JavaScript only required for highlighting index entries.
Works with old Web browsers.
Browser next and previous buttons supported.

Search-engine friendly.

Cons

Needs server-side scripting.

Structure

The files needed for this version of the help depend on the scripting used, but will typically be something like this:

Filenames	Description
01-Intro.html, 02-Site.html, etc.	The source HTMLfor each topic.
nav.html	The source table of contents.
ind.html	The source index.
header.html	The source header.
basic.css, divs.css, hilite.js	CSS and JavaScript definitions.

The design is based on four divs:

Each link in the table of contents is a simple link to the appropriate topic file:

<a href="02-Site.html">Adding sites</a>

Contents highlighting

The table of contents entry corresponding to the current file is given the class on to highlight it:

<a class="on" href="01-Intro.html">Introduction</a>

Index

For information about how the index entries are inserted in the topic files see Index Entries. Links in the index include a hash tag to the "a name=" anchor:

<a href="01-Intro.html#a01-2">Ad formats</a>

Index highlighting

To highlight a reference in the text when we link to it from the index we set the class to hi.

This could be done by the server-side script. Alternatively it can be achieved by a call to a JavaScript routine HighlightIndex() in the body onload event:

<body onload="HighlightIndex(document.location);">

We also need to add a call to the same routine in the onclick event of each index entry, to cater for the situation where the page is already loaded and the onload event doesn't get called:

<a href="01-Intro.html#a01-2" onclick="HighlightIndex(this);">Ad formats</a>

Here's the definition of HighlightIndex():

var yellow = '';

function HighlightIndex(id) {
  if (yellow != '') { 
    document.getElementById(yellow).className = '';
  }
  yellow = id.hash.substr(1);
  document.getElementById(yellow).className = 'hi';
}

This first removes any previous highlight, in case we are linking to a different location on the page that's already loaded. It then highlights the index entry corresponding to the hash part of the current URL. The id of the currently highlighted anchor is stored in the global variable yellow.

Cross references

Cross references within files and between files work automatically using standard "a href=" links.

^ I am grateful to Rob Meek for suggesting this option.