Adding a Table of Contents to Web-based Help
By Dave Gash, HyperTrain dot Com
Contents
Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.
Introduction 
This article discusses the "Table of Contents" (TOC) navigation device, historically a standard feature of client-based Help, and presents various methods for implementing it in web-based Help systems.
To get the most from the article, you should have a basic understanding of HTML tags, attributes, and values, and some exposure to JavaScript, although direct coding experience is not required.
You may download the example files at any time, and I encourage you to run them as you follow the narrative below. Two notes about the example: (1) There are radio buttons in the TOC that switch between two different versions—you'll see those right away; and (2) Both versions are set up to call the same page (DummyTarget.htm) from every link (so I didn't have to prepare dozens of target pages), but that page changes its background color every time it loads to give the appearance of different pages, so don't let that freak you out.
Start the example system by running "index.html" in Internet Explorer 5.x or 6.x, or in Netscape 6.x or 7.x. Now you might infer from this short list that I haven't tested the code in eighty-seven versions of fourteen different browsers, and don't really care to.
And you'd be right. Hey Sparky, get a decent browser, okay?
Background
Pity the poor old Table of Contents. It's been in online Help systems for years, is used by millions of people every day, and yet still is maligned by users and authors alike. Let's face it, nicer things have been said about Saturday Night Live spinoff movies, and it's just not fair. The TOC was and is one of the most useful access devices in Help, despite what some pundits would have us believe.
You want proof? Take a look at the results of a recent WinWriters QuickPoll (shown below) wherein 74% of respondents said the TOC was "indispensable" or "very important" to their Help systems! Does this sound like a navigation element that no one has used in fifteen years? Didn't think so. Armed with this knowledge, then, let's take a look at the TOC, from both design and implementation angles, and see why—and how—to make good use of it in our web-based Help systems.
First of all, we should remember what a TOC is. It looks like an outline, walks like an outline, and quacks like an outline, so it must be an outline; and it is. The TOC is a high-level access device, and it's useful because it provides a visual representation of the physical structure of the information it accesses. We all know that readers still love a paper book; in electronic documents, navigation devices like TOCs, indexes, and browse sequences (linear page-turning) are well loved by users because they're familiar. There's no learning curve, no surprises, no head tilting or eyebrow scrunching. We've seen these elements before, so we already know how to use them and what to expect from them. Like it or not, electronic emulation of paper-based access devices is hot stuff in the user's world.
Let's also remember what a TOC isn't. It isn't a list of every stinkin' page in the Help system! One of the most common mistakes made by Help authors is listing everything in the TOC. That's just not necessary, and it's not what the TOC is for. The TOC is a jumping-off point, a way to locate and access major chunks of information. Once users arrive at a section they're interested in, there are plenty of other access devices—jumps, popups, browse sequences, related topics, expanding hotspots, image maps, and so on—they can use to move about within the section or to get more detailed information. Take a look at the two partial TOCs below; the one on the left sticks out like a Jerry Springer guest will all her teeth, while the one on the right groups the data into distinct collections and simply provides "starter" links to each group. This allows users to locate the section they want quicky and easily, and then use other access devices for low-level navigation.
While we're on the subject, let's also mention another common mistake, nesting a TOC too deeply. Mrs. Sharp, my high school English Composition teacher, was so old she lost to Mark Twain on "Star Search," but she impressed a few important points on me, one of which was that an outline shouldn't be more than four levels deep: Roman numerals, capital letters, Arabic numerals, little letters, and that's it. This is an excellent rule of thumb for outlines, and it applies equally well to TOCs. For example, the outline format and its TOC equivalent below are both maxed out in terms of data accessibility; if you think you need more levels of detail than this, then you're cramming too much stuff into too small a space. Just like Anna Nicole Smith.
Another structural mistake often made by authors is grouping elements by attributes rather than by object. That is, in scanning a TOC, users are generally focused on the thing they're interested in, not on the type of thing. This is an easy error to make, but not necessarily an easy one to spot. For instance, Gibson, Fender, and Ovation each manufacture guitars, mandolins, and banjos. The following partial TOCs therefore look almost identical; even though they group the data differently, they have the same visual structure and the same number of levels. Yet, the TOC on the right is actually far more effective in helping the user locate information because it groups the data by object, thus creating a distinct collection of "all guitars" instead of an indistinct collection of "all instruments made by Gibson."
So ok, that's enough "why"; let's do some "how," shall we?
The Plan
The Table of Contents is basically a holdover from the (good old) WinHelp days. The original RTF-based WinHelps—the 16-bit version for Windows 3.x and the 32-bit version for Windows 95—didn't have one at all. The one in WinHelp 4 for Windows 98 worked reasonably well, but was sort of an afterthought, shoehorned in at the last minute to provide some TOC functionality. TOC support of any kind is of course a viewer issue, so only when Microsoft's HTML Help came along did users find a reasonably well-integrated TOC in their Help systems.
That worked fine for a while, but then we all started wanting Help on the Web, and wham, we're right back where we started. Because browsers aren't Help viewers, there's no built-in facility for displaying or managing a TOC. Browsers don't have proper panes where different chunks of information can be displayed in the same window, like the client area of a viewer application, so the question is: "What can we use to get the familiar look and feel of an integrated TOC inside a browser window?" And the answer is: "Frames!"
Now don't go all glassy-eyed on me just because I said the f-word. Frames are not the horrid, despicable bane of browserdom as we've all heard from, well, the same people who say nobody uses TOCs. (Interesting coincidence, don't you think?) It's all right, you can relax; a frame won't eat your liver with some fava beans and a nice Chianti, it's just a convenient way to separate the browser window into manageable areas, okay? Let's use a couple of them to reserve spaces for the TOC and the Help topics, so the browser window initially looks like this:
Naturally, we'll need a TOC of some kind (patience, it's coming) in the left-hand frame, and some topics to put in the right-hand frame, so the completed site in the browser might look like this:
Son of a gun, looks sort of like a Help system, doesn't it?
Now if you're ahead of me on this, and you probably are, you're realizing that the main trick here isn't setting up the frames, nor putting the TOC and the start topic into the correct frame, it's making sure that the topics the TOC jumps to actually end up in the topic frame. And you're exactly right, that's the trick—so let's see how it's done!
The Code
The Frames
When we're talking about HTML, we should of course always be thinking "containers," the paired tags that make up most HTML constructs. Just as <HEAD></HEAD>, <BODY></BODY>, <P></P>, and so on are containers, so are framesets and frames. All we need to prepare the browser window for the TOC and topic areas is one frameset and two frames, coded like this.
<frameset cols="25%,*">
<frame src="toc.htm" name="toc"></frame>
<frame src="welcome.htm" name="topics"></frame>
</frameset>
As you can see, the <frameset></frameset> container holds the two <frame></frame> containers. The value of the <frameset> tag's cols (columns) attribute specifies that for the two frames defined in the frameset, the first one should take up a specific portion ("25%") of the available horizontal space in the browser window, and the second one should get whatever horizontal space remains ("*"), or... um, er, okay, so math isn't my strong suit.Gimme a break, will ya?
You can also see that the <frame></frame> containers themselves don't actually "contain" anything between the start and end tags; much like an <img></img> container, all the work is done inside the start tag, so the end tag is optional. Also like <img></img>, the real content of the container is brought in via a src (source) attribute; in this case, the file "toc.htm" is loaded into the left frame, while "welcome.htm" is loaded into the right frame. In particular, note that each frame also has a name attribute; these unique identifiers allow us to specify either frame as the destination, or target, location of subsequent page loads.
One last point about this code that may not be obvious: This is virtually the entire code for the Help system's start page! No <HEAD></HEAD>, <BODY></BODY>, or other content tags are required, because this page exists only to set up the frames and load other files into them. If it is named, for example, "index.html", and exists on a web server somewhere, you need only point a browser to the domain name to establish the frameset and load "toc.htm" and "welcome.htm" into the appropriate frames. And voilá (that's French for "Dang, Bubba!"), instant Help system.
The TOC, Take One
Bet you thought we'd never get here, right? Well, with the preceding info under your belt, you're now prepared to face the code for the TOCs. That's right, I said "TOCs," plural, because we're going to look at two different methods for producing a TOC in that left-hand frame: a Java applet solution, and a Dynamic HTML (DHTML) solution. Because the Java applet approach is more straightforward, let's examine it first and save the DHTML for later.
First of all, let's make sure we know what we're talking about when we say "Java applet." Java applets are real little programs written by real little programmers—they are not readable by you, me, or any carbon-based unit; they are not modifiable or changeable by us or our users; and they are absotively, posilutely not JavaScript! Yes, the names are unfortunately similar, but that's where it ends, and as Martha "Who, me?" Stewart would say, "It's a good thing." As technical authors, you will undoubtedly write a lot of JavaScript over the course of your career, but you will most likely never write a Java applet as long as you live. Okay so far? Let's move along.
There are literally thousands of free and cheap Java applets available on the Web (not to mention all the commercial products), written specifically for creating TOCs. Although I've tried more of those applets than Michael Jackson has had noses, this is not the place to compare features or extol the virtues of one over another, so I'm just going to pick one that works pretty well and go with it. Ah, here's a little outline applet I've had for some time, and it works fine; like me, it's small, simple, and easy to manipulate.
Now remember, the code to call the applet won't go in our starter file, "index.html", but rather in the file that's loaded into the left frame (called simply "toc.htm" above). Let's call this version "tocapplet.htm" to distinguish it from the DHTML version we'll do later. Here is the applet code, followed by its explanation.
<applet code="Outline.class" width=300 height=465>
<param name="bgcolor" value="#ffffff">
<param name="forecolor" value="#000000">
<param name="textcolor" value="#000000">
<param name="linkcolor" value="#0000ff">
<param name="selectcolor" value="#0000ff">
<param name="iconfile" value="icons.gif">
<param name="datafile" value="toc.xml">
<param name="target" value="topics">
</applet>
The applet itself is, of course, a container, and so starts and ends with <applet> and </applet>. The applet code resides in the "Outline.class" file, and for this application we're going to allow it an area 300 by 465 pixels. Note: "Outline.class" calls two support files, "Folder.class" and "FolderData.class", but only "Outline.class" is referenced by the applet tag's code attribute.
Inside the container is a series of parameter lines, each one a separate <param> tag, and each containing two attribute/value pairs, name and value. These parameters are not positional, so they may occur in any order. Here's how they control the applet.
- bgcolor — The color of the window behind the outline; any valid hexadecimal color value
- forecolor — The color of the connecting lines; any valid hexadecimal color value
- textcolor — The color of unselected, non-link text (books); any valid hexadecimal color value
- linkcolor — The color of the underscored link text; any valid hexadecimal color value
- selectcolor — The highlight color for selected non-link text (books); any valid hexadecimal color value
- iconfile — The name of a file containing the four possible icons (see below)
- datafile — The name of a file containing the outline structure (see below)
- target — The name of a target frame for all jumps from the outline (see below)
The first five color parameters are pretty much self-explanatory; you can use them to create any color scheme you like (but let's not get crazy about it, okay?). The last three parameters beg a bit more explanation.
The iconfile is a .GIF exactly 64 pixels high and 16 pixels wide. Basically, it's the four possible 16 by 16 pixel icons, stacked vertically. The icons are, in top-down order: Open book, closed book, bottom-level page, and top-level root. There's nothing special about this image, but remember because it's a .GIF, you may set a transparent color so the background color of the applet shows through unused parts of the icons. Here's an example "icons.gif" with the transparent color set to red. Naturally, you can change the name of this file or the images in it to suit your own requirements.
The datafile is an XML-format file containing the actual outline structure. The structure is coded as nested containers that describe the hierarchy. For a deep outline, the code can get kind of busy, but it's really pretty straightforward (especially if you indent your code, hint hint!); each folder element has a text element associated with it, and an optional href element. The text element contains the text the user sees in the outline, and the href element contains the name of the page to be displayed when the link is clicked, just like the href attribute of an <a> tag. Folders with href elements are jumps, while folders without href elements are books, and so nesting the appropriate folder types achieves a multi-level effect, as shown below.
And finally, a really simple but really important parameter: target. As promised earlier, this is how the TOC keeps itself in one frame and displays the topics in another. The value of the target parameter is the name of a frame to which all links from the outline will be directed. This name must match one of the names in your predefined frameset—in our case, the right-hand one, called "topics"—or it'll work about as well as a road crew at rush hour.
And that's about it for the applet code. The applet does all the work; all we supply is the XML file with the TOC structure, and off it goes. We'll discuss implementation later, but for now I think we're done with the Java applet TOC; let's move along to the DHTML version!
The TOC, Take Two
It would probably be wise to start this section the same way we started the last one, by making sure we know what we're talking about. We hear about Dynamic HTML (DHTML) all the time, and most folks tend to think of it as a set of markup tags or a programming language. In fact, it's neither—and both. DHTML is actually just a set of techniques, combining the basic page markup language of HTML, the elements in the page's Document Object Model (DOM), the style characteristics of those elements as defined by the Cascading Style Sheet (CSS) specification, and some JavaScript routines to manipulate those elements and their characteristics. To put it a bit more succinctly, the "formula" for DHTML might look like this:
DHTML = HTML + DOM + CSS + JS
Kinda looks like you just poured a can of alphabet soup onto the page, doesn't it?
Anyway, that's the idea. Read the formula from right to left: When you use JavaScript code to access the Cascading Style Sheet characteristics of a document's elements through the Document Object Model of the HTML page, you're employing DHTML techniques. Trust me, it's way simpler than it sounds. In fact, the only thing that makes DHTML complicated at all is the Document Object Model and its differences from browser to browser. If all browsers used the same DOM, then writing DHTML would be easier than spotting Al Gore at a Marilyn Manson concert, and where's the sport in that?
The DHTML technique we're going to use to achieve the expanding/collapsing TOC effect is based on a CSS property called "display", which controls whether an element is visible on the screen. The values for the property are "none", which tells the browser to hide the element, and "" (null), which tells the browser to display the element. An added benefit of this property is that when an element is not displayed it takes up no room on the page and allows the remainder of the page to shift up. Conversely, when an element is displayed it makes room for itself and allows the rest of the page to shift down, thereby avoiding any empty space in the browser window. Pretty cool, and exactly what we need to show and hide the different levels of our TOC.
When you think about it, a TOC is a lot like a series of nested lists, as shown in the outline example above. Gosh, wouldn't it be nice if we could just code our TOC as a bunch of nested unordered list (<ul></ul>) containers? Wow, wouldn't unordered lists be a familiar and convenient mechanism for this type of structure? Gee whillikers, Beav, wouldn't it be swell... Um, sorry, got carried away. Of course unordered lists would be just the ticket, but we'd have to control when they're visible (and not), and we'd have to replace those ugly little bullets with more TOC-like images. As I'm sure you've guessed by now, we can accomplish both those tasks through styles. Here's the style code for our DHTML TOC; let's see what it does.
<style>
#headeritem {cursor:pointer; cursor:hand;
font-size:12px; list-style-image:url(closedbook.gif)}
#nestedlist {font-size:12px; list-style-image:url(topic.gif)}
a:visited {color:#0000ff}
</style>
Inside the style container, attributes are set for two specific identifiers: headeritem and nestedlist. The headeritem properties will be assigned to a list item (<li>) tag that contains (is the header for) a nested list, while the nestedlist properties will be assigned to an unordered list tag (<ul>) that is a nested list. For both types of identifiers, new bullets (list-style-image) are specified—a closed book icon for the headeritems and a topic page icon for the nestedlist (jump) items.
Although headeritems won't be true links, we still want users to know they can be clicked, so we set the cursor property to both pointer (Netscape's value) and hand (IE's value); interestingly, each browser's cursor setting is ignored by the other, so we can code them both on one line and each browser will pick up only its own value. Pretty nifty, eh? (Don't get too excited; this trick doesn't work for everything, as we'll see in a minute.) We can also set the font size here, or any other attributes we like; I've specified 12-pixel type so the TOC text isn't too big.
The last line doesn't really affect the lists, just the visual appearance of the links at the bottom level. Browser links (<a> tags) usually change color after they're clicked, or "visited." For regular Web pages, that's fine, but for a TOC we'd like them to stay blue all the time, so we simply set the color for visited links to blue (#0000ff) to maintain a consistent look in the TOC. The only thing we really lose by using list tags is the cute little dotted lines that connect the TOC entries, but for the enormous convenience of coding the TOC as nested lists, I can live with it; how about you?
And that's the entire style definition. Before we look at the JavaScript code that controls the lists, I think we should look at the lists themselves. Here's a set of nested unordered lists that produces the same section of TOC as the XML example above. Of course, like a good little coder, I've indented my HTML so it's easier to read.
<ul>
<li id="headeritem">Stringed Instruments</li>
<ul id="nestedlist" style="display:''">
<li id="headeritem">Guitars</li>
<ul id="nestedlist" style="display:none">
<li id="headeritem">Gibson</li>
<ul id="nestedlist" style="display:none">
<li><a href="es335-345.htm">ES-335/345</a></li>
<li><a href="sgclassic.htm">SG Classic</a></li>
<li><a href="lespaul.htm">Les Paul</a></li>
</ul>
</ul>
</ul>
</ul>
Speaking of unordered lists, let's use one to look at this code one level at a time.
- The outermost list only has one list item ("Stringed Instruments"), and its id is set to "headeritem". As we saw above, that makes it a TOC book with the closed book icon.
- The next thing is another list, with its id set to "nestedlist". Note that this list has its display style set to ' ' (null) so it will display the first level of books, while the other nested lists have their display style set to "none" so they don't display initially. An id of "nestedlist" would normally cause items in this list to have the topic icon, but...
- Notice that the first (and in this example, the only) item in this list ("Guitars") is of type "headeritem", which causes it also to have the closed book icon.
- Next, another "nestedlist" is defined, and its first and only item ("Gibson") is also a "headeritem".
- Finally, there is the bottom-level "nestedlist" with the actual links, where the list items carry no id, but are instead simple <a> tags with href attributes and link text. Then, of course, the unordered lists are closed with </ul> tags.
To me, this is simplicity itself. I've seen lots of DHTML outlines, and this one is definitely my fave for ease of setup and modification. Once your lists are defined, it's really easy to make changes without horking up the entire TOC. Before heading into the JavaScript that processes the lists, let's look at this code and its resulting TOC segment as we did for the Java applet earlier.
Because the DHTML TOC is just a bunch of unordered lists, both browsers indent the nested ones automatically, which certainly adds to the convenience factor. However, the default indent in each browser is really a bit too much for a TOC, where you want the levels to be fairly tight horizontally. If the indent is too big, the TOC expands out too far to the right, which makes it sloppy and hard to follow. (Insert your own David Lynch movie joke here.) It's easy to add a style definition to control the indentation, but of course IE and NS do it differently. I mentioned earlier that the little style trick of including both IE and NS values doesn't always work, and this is one such place, so the first piece of JavaScript we should look at addresses that problem.
var ns6 = document.getElementById && !document.all;
var ie4 = !ns6;
if (ie4) document.write("<style>#nestedlist {margin-left:18px}
</style>");
else document.write("<style>#nestedlist {margin-left:-14px}
</style>");
This is the simplest of simple sniffer scripts. The first line identifies NS 6 and up, and the second line assumes everything else is IE 4 and up by negating whatever the first line turns out to be. I did say earlier that this method is for those browsers, remember? After these two lines execute, either ns6 is true and ie4 is false, or vice versa, no exceptions. Then the third and fourth lines (the if/else) write a single style tag either bumping the margin to the right for IE, or bumping it to the left for NS. Of course, you may play with these values to get whatever indentation level suits you. Next, there's this little guy:
document.onclick = checkcontained;
Naturally, we want the items in the list to be processed (expanded, collapsed, or jumped from) any time the user clicks them. Sure, we could set onclick event handlers for every object in every list, but not only would that be a lot of work, the onclicks would soon pile up hub-deep to a Ferris wheel. Instead, this single line sets the onclick event handler for the entire document, causing any click in the TOC frame to execute a function called checkcontained, which figures out which item was clicked and processes it. Note the parentheses-less syntax, which differs from the standard syntax used if the function were called directly (e.g., "checkcontained()").
And frankly, the only thing left to look at is that function itself. See, I told you this was a pretty straightforward technique. The checkcontained() function is basically in two parts; let's look at them separately. Here's part one:
function checkcontained(e)
{
var iscontained=0;
curitem=ns6 ? e.target : event.srcElement;
while ((ns6 && curitem.parentNode)
|| (ie4 && curitem.parentElement))
{
if (curitem.id=="headeritem" || curitem.id=="nestedlist")
{
iscontained=(curitem.id=="headeritem") ? 1 : 0;
break;
}
curitem=ns6 ? curitem.parentNode : curitem.parentElement;
}
// ...
The first thing I should explain about this function is the use of the "shortcut" if/else syntax. If you haven't seen this before it looks kind of strange, but once you catch on to it you'll love it. Take the line that begins with "curitem=ns6", for instance. The goal of this line is to set the object variable curitem to the object the user clicked (called the event target). Problem is, NS's and IE's DOMs reference this object differently; NS calls it e.target, while IE calls it event.scrElement. So we need an if/else to test a sniffer variable and then reference the item using the correct DOM naming convention for the browser we're in. Normally, we'd code that like this:
if (ns6)
{
curitem = e.target;
}
else
{
curitem = event.srcElement;
}
Or, to save a few characters, we could also code it like this:
if (ns6) curitem = e.target;
else curitem = event.srcElement;
But there's a much simpler way to code the same condition, which looks like this:
curitem = ns6 ? e.target : event.srcElement;
All three are exactly equivalent, but the last one is cleaner and more efficient; here's how it plays. The question mark is basically the "if", and the colon is basically the "else". So if the condition to the left of the question mark is true, the value preceding the colon is assigned to the variable; if the condition is false, the value following the colon is assigned to the variable. See? Instant if/else, in one easy assignment. Hey, you may as well get used to it, because it's used throughout this function. You'll thank me for this someday. No, really, you will.
The functions, er, function depends entirely on the value of the variable iscontained, and this part of the code sets that variable. The "while" loop looks at the clicked element and "backs up" to its parent element, again using different addressing syntax for NS and IE. If the clicked element's parent is a "headeritem" list item or a "nestedlist" list, then a final check is made, which sets the variable iscontained to 1 (true) for headeritems or 0 (false) for nestedlists and then exits the while loop either way. (Hey, there's that shortcut if/else code again. Handy, isn't it?) However, if the parent item is not a headeritem—in other words, it's just a regular list item—then the while loop continues to back up until it finds the clicked element's parent list. At this point we know whether the clicked element is a contained header or a regular list item, and so we're ready to act accordingly, through the following code:
// ...
if (iscontained)
{
var itemcontent=ns6 ? curitem.nextSibling.nextSibling
: curitem.all.tags("UL")[0];
if (itemcontent.style.display=="none")
{
itemcontent.style.display="";
curitem.style.listStyleImage="url(openbook.gif)";
}
else
{
itemcontent.style.display="none";
curitem.style.listStyleImage="url(closedbook.gif)";
}
}
} //end of function
Notice that this second segment is all one big if block: If the variable iscontained is false, then the clicked element is just a plain old list item with a link, and the function bails out and lets the browser handle the link. If iscontained is true, though, we want to grab the clicked element's content, toggle its display setting, and change its bullet (book icon). The only thing that makes this tricky at all is that the text of the list item and its bullet type are two separate page elements, so we have to set one style attribute for each. Using the by-now-painfully-familiar (and if not, you haven't been paying attention) shortcut if/else to get the right DOM reference syntax, we set an object called itemcontent to, well, the item's content (the next nested list), which is what we want to control. Finally, a straightforward if/else (regular syntax this time) checks the current display style of the list. If it's "none" (hidden), we set it to "" (visible) and replace the bullet of its parent item with the openbook icon; if it's "" (visible), we set it to "none" (hidden) and replace the bullet of its parent item with the closed book icon.
And lastly but not leastly (huh?), as we did for the Java applet version, let's see how the DHTML version of the TOC keeps itself in one frame and displays the topics in another. A single line of HTML accomplishes that, and here it is:
<base target="topics">
The <base> tag is a handy little guy that lets you specify the target for all links in a document. (Well, all links that don't specify their own targets, at least.) Like <br> and <hr>, it's an "empty" tag, so there is no </base> end tag. Normally placed in the document's <head> section, that's all it takes to direct our TOC jumps into the right-hand frame. Slicker than Vaseline on a brass pole, eh? (Oh yeah? Well if you didn't get it, then why are you laughing?)
And that's it for the code. Now in case you're feeling like this was more convoluted than the series finale of The X-Files, let's review how simple it really was: All it took was (1) a couple of style definitions to set the initial look for the lists, (b) a few id settings on standard unordered lists and items so they can be identified, and (iii) one small function to toggle the visibility and icons. Not much overhead, frankly, for such a flexible menu system.
Implementation
In "The Plan," we saw how these techniques might look in a browser; in "The Code," we saw the inner workings of two different approaches. If you followed along with this article and ran the example files, you should by now have a good mental picture of how the TOC should look and act, and also of how much time I spend playing with browsers and code. This means that about now, you're probably thinking either "Hey, I'd sure like to use one of those TOCs in my help systems." or "Wow, Dave should really get out of the house once in a while." Well, I'm here to tell you there ain't gonna be none of that, so let's close up by learning exactly how to implement either method in our own web-based Help.
Here are two sets of instructions, one for the Java Applet version, and one for the DHTML version. Customization notes are included as appropriate.
Adding the Java Applet TOC
Follow these steps to implement the Java Applet TOC.
- Place the files Folder.class, FolderData.class, icons.gif, index.html, Outline.class, toc.xml, and tocapplet.htm in your output folder (the one that gets FTP'd to your server). In index.html, specify your own start page as the value of the second frame's src attribute.
Customization — In icons.gif, modify the images as desired, or in tocapplet.htm, replace the file entirely by changing the value of the iconfile parameter.
- In tocapplet.htm, remove the form with the radio buttons, marked with HTML comments <!-- *** Remove this form *** --> in the code.
Customization — Modify any of the color value parameters as desired; modify the font face or size as desired.
- Edit toc.xml to reflect your TOC structure, following the nested <folder> layout; specify <text> and <href> containers as appropriate.
Customization — In tocapplet.htm, replace the file entirely by changing the value of the datafile parameter.
Adding the Dynamic HTML TOC
Follow these steps to implement the Dynamic HTML TOC.
- Place the files closedbook.gif, index.html, openbook.gif, tocdhtml.htm, and topic.gif in your output folder (the one that gets FTP'd to your server). In index.html, specify "tocdhtml.htm" as the value of the first frame's src attribute and your own start page as the value of the second frame's src attribute.
Customization — Modify the three image files as desired, or in tocdhtml.htm, replace them entirely by changing their names throughout.
- In tocdhtml.htm, remove the form with the radio buttons, marked with HTML comments <!-- *** Remove this form *** --> in the code.
Customization — Modify the font face or size as desired.
- In tocdhtml.htm, edit the lists to reflect your TOC structure, following the nested <ul> layout; specify <a> links and link text as appropriate.
And we're done!
Thank You...
...for reading this article! I hope you enjoyed the techniques presented here, and that you find them practical and useful in your own Help systems. Don't forget to download the example files if you have not already done so, and please feel free to contact me any time with questions or comments. I'm always glad to hear from you!
Copyright 2002, Dave Gash
Dave is the owner of HyperTrain dot Com, a Dallas firm specializing in hypertext training for Help system developers. A veteran software professional with over twenty years of development, documentation, and training experience, Dave is well known in the Tech Pubs community as an interesting and animated technical instructor. When he's not on the road doing training or chained to his PC developing new courses, Dave is a frequent speaker and presenter at Help-related conferences and seminars in the US and abroad.
Copyright © WinWriters. All Rights Reserved.
Joe Welinske: jw@winwriters.com
Last modified on
|
|
