Please note that this code has now been superseded by a more up-to-date version: see Unobtrusive DHTML for more details.

aqTree2: explorer-style trees from unordered lists

Could be just the thing for that anal retentive client who insists that all 500 pages of his site be linked from the nav bar.
Jeffrey Zeldman
(hmph, weirdly named, is it? I spent a whole three minutes thinking that name up, I'll have you know)

What it is

Below is an unordered list, which will be converted by the included JavaScript library into an explorer-tree structure if you've got a browser capable of doing it.

This is the unconverted list:

<ul class="aqtree2">
    <li>Sublist 1
    <ul>
        <li><a href="#">List item 1.1</a></li>
        <li>Sublist 1.2
        <ul>
            <li>List item 1.2.1</li>
            <li>List item 1.2.2</li>
            <li>List item 1.2.3</li>
        </ul>
        </li>
        <li>List item 1.3</li>
        <li>List item 1.4</li>
    </ul>
    </li>
    <li>List item 2</li>
    <li>Sublist 3
    <ul>
        <li>List item 3.1</li>
        <li>List item 3.2</li>
        <li>Sublist 3.3
        <ul>
            <li>List item 3.3.1</li>
            <li>Sublist 3.3.2
            <ul>
                <li>List item 3.3.2.1</li>
                <li>List item 3.3.2.2</li>
            </ul>
            </li>
            <li>List item 3.3.3</li>
        </ul>
        </li>
    </ul>
    </li>
    <li>Sublist 4
    <ul>
        <li>Sublist 4.1
        <ul>
            <li>List item 4.1.1</li>
            <li>List item 4.1.2</li>
        </ul>
        </li>
        <li>Sublist 4.2
        <ul>
            <li>List item 4.2.1</li>
            <li>List item 4.2.2</li>
        </ul>
        </li>
    </ul>
    </li>
</ul>

How I do it

So, how do I get this fine new effect? Well, you need to do three things:

  1. The first thing is to make sure that your list is valid (X)HTML. This means that a UL contains only LIs.
    That's right. It doesn't contain other ULs, it doesn't contain text. <li> tags and that is all. This is very important.
    So, how do I nest ULs, I hear you ask? Like this:
        <ul class="aqtree2">
        <li>Some text here
        <ul>
            <li>Some text here</li>
            <li>Some text here</li>
        </ul>
        </li>
    </ul>
    See that? Each UL contains only LIs and that's it. Text nodes and ULs are all contained within LIs. You must do this or aqTree2 will not work.
    If you've got a sublist inside a UL, then all the other stuff in that UL becomes the list header. (See the "Sublist X.Y" texts in the above example; that text becomes the link to the submenu.)
  2. Secondly, make your top-level UL of class aqtree2. The LIs within this top-level UL are the ones that are initially displayed.
  3. Thirdly, include the aqtree2 JavaScript file that does the work. Add the following line to the HEAD of your HTML file:
    <script type="text/javascript" src="aqtree2.js"></script>
  4. You may also customise the plus, minus and bullet images as follows (include this code in the HEAD of your page, after you include the aqtree2.js file):
    <script type="text/javascript">
    aqtree2_expandMeHTML = '<img src="http://www.kryogenix.org/code/browser/aqtree/plus.gif" />';
    aqtree2_collapseMeHTML = '<img src="http://www.kryogenix.org/code/browser/aqtree/minus.gif" />';
    aqtree2_bulletHTML = '<img src="http://www.kryogenix.org/code/browser/aqtree/bullet.gif" />';
    </script>
     The variables can be set to any HTML you choose (so they could just be '+', '-' and '·', for example; they don't have to be images).

And that should be it.

A note on browser compatibility:
I've personally tested this in IE5.5/Win, Mozilla 1.0.0/Linux, and Konqueror 2.2.2/Linux, and it works fine. Opera (all versions) fails completely, probably due to its lack of DOM support. K-Meleon 0.6.5 is OK. IE6sp1/WinXP is fine but with a report of screen flicker. I've also had reports that IE5.1.2/Mac crashes (erk!) on leaving the page. I'm interested in other browser success/failure reports; let me know at the contact address below.

[Back to the browser experiments] - [Back to kryogenix.org]

sil@kryogenix.org