Viewing Documentation with a Tree Control

Writing Documentation with a Tree Control

Linking to the Tree Control Sources

Positioning the Tree Control in an HTML Document

Constructing the Tree Control

Adding Content for No-Script Browsers

Viewing Documentation with a Tree Control

A tree control will typically be displayed in an HTML frame at the left of the browser window. Its appearance should be familiar to most users. For example, it might look like this:

In the above display,

• the plus sign + is a clickable icon which expands node 2 so that its list of children becomes visible.
• the minus sign - is a clickable icon which collapses node 3 so that its list of children becomes hidden.
• the hyperlink [link to this page] causes the browser to reload with a url pointing to the current location in the documentation.

To understand the need for [link to this page], note that when a user follows a link which loads a new document into the content frame, the url displayed in the browser's address bar is generally not updated and the state of the tree control remains the same. (See Example.) Without [link to this page], it would be difficult or impossible to bookmark or publish links to internal sections of documentation using a tree control.^[1] For additional discussion, see the Rationale ('Completely Addressable').

Writing Documentation with a Tree Control

Creating a web page containing a tree control is easy. This tutorial describes the process in detail. An alternative to following these instructions is to use the template menu.html.

The process involves five steps:

1. Add a link to the tree control sources (see Linking to the Tree Control Sources).
2. Add a span element with id attribute tree_control at the position within the body of the HTML document where the tree control is to be displayed (see Positioning the Tree Control in an HTML document).
3. At the same location, add a noscript element to contain HTML for browsers with scripting disabled (see Positioning the Tree Control in an HTML document).
4. Add a script to the head of the HTML document which:
   1. creates an instance of the JavaScript class tree_control,
   2. adds tree_nodes corresponding to the sections and subsections of the library being documented,
   3. sets its dump_html property to true, and
   4. invokes its member function draw.
   (See Constructing the Tree Control.)
5. Display the page in a script-enabled browser, paste the contents of the browser window into the body of the noscript element from item 3, and comment out the line setting the dump_html property to true (see Adding Content for Script-Disabled Browsers).

Linking to the Tree Control Sources

To link to the tree control source code and stylesheet, add script and link elements to the head of the HTML document like so:

    <script language='JavaScript' src='path to tree.js'></script>
    <link rel='stylesheet' type='text/css' href='path to tree.css'>

Positioning the Tree Control in an HTML document

At the position in the HTML document where the tree control should be displayed, add span and noscript elements as follows:^[2]

    <span id='tree_control'></span>
    <noscript> 

        content for script-disabled browsers will go here 

    </noscript>

Constructing the Tree Control

One creates a new instance of tree_control like so:

    var tree = new tree_control("content");

Here "content" is the name of the HTML frame in which urls associated with the tree_control will load.

One may add tree_nodes to an instance of tree_control using its member function add, as follows:

    tree.add("Chapter 1", "chapter1.html");
    tree.add("Chapter 2", "chapter2.html");
    tree.add("Chapter 3", "chapter3.html");
    tree.add("Chapter 4", "chapter4.html");

Here "Chapter 1" et al. are the text labels to be displayed by the tree_control, and "chapter1.html" et al. are the urls to be loaded into the content frame when the labels are clicked. Each tree node must have a label but need have no associated url. When displayed, the above tree control will look something like this:

To create a multi-level control, one can modify the above code as follows:

    var tree = new tree_control("content");
    tree.add("Chapter 1", "chapter1.html");
    tree.add("Chapter 2", "chapter2.html");
    var chapter3 = new tree_node("Chapter 3", "chapter3.html");
    chapter3.add("Section A", "chapter1.html#sectiona");
    chapter3.add("Section B", "chapter1.html#sectionb");
    chapter3.add("Section C", "chapter1.html#sectionc");
    tree.add(chapter3);
    tree.add("Chapter 4", "chapter4.html");

When displayed fully expanded the above control will look something like this:

Another way to polpulate a tree_control is as follows. The member functions add of tree_control and tree_node return the added tree_node, and each tree_node has a member functions parent returning its parent node. Therefore, the above construction could be reduced to two statements:

    var tree = new tree_control("content");
    tree.add("Chapter 1", "chapter1.html").parent()
        .add("Chapter 2", "chapter2.html").parent()
        .add("Chapter 3", "chapter3.html")
             .add("Section A", "chapter1.html#sectiona").parent()
             .add("Section B", "chapter1.html#sectionb").parent()
             .add("Section C", "chapter1.html#sectionc").parent().parent()
        .add("Chapter 4", "chapter4.html");

The entire script creating a tree_control might look like this:

    <script language='JavaScript'>
    <!--

    var tree = new tree_control("content");
    tree.add("Chapter 1", "chapter1.html").parent()
        .add("Chapter 2", "chapter2.html").parent()
        .add("Chapter 3", "chapter3.html")
             .add("Section A", "chapter1.html#sectiona").parent()
             .add("Section B", "chapter1.html#sectionb").parent()
             .add("Section C", "chapter1.html#sectionc").parent().parent()
        .add("Chapter 4", "chapter4.html");

    tree.dump_html = true;
    tree.draw();

    // -->
    </script>

Adding Content for No-Script Browsers

To ensure that the tree control is usable on browsers which do not support JavaScript, or for which JavaScript has been disabled, view the HTML document constructed thus far in a modern graphical browser with scripting enabled. The browser window will display literal HTML representing a static view of the tree control. Copy the text from the browser window into the noscript element inserted above. Finally, comment out the line which sets the dump_html property as follows:

    //tree.dump_html = true;

^[1]Internet Explorer's 'Add to Favorites' command saves the url of the document displayed in the content frame, but not the state of the tree control (obviously) or the current position with the document in the content frame. Some other browsers update the address bar to display the url of the document in the content frame. Neither behavior is completely adequate.

^[2]It would be elegant if we could replace the above HTML with

    <noscript id='tree_control'></noscript>

Revised 22 July, 2004

© Copyright Jonathan D. Turkanis, 2004

Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)