HTML_TreeMenuXL

An Enhanced Version of HTML_TreeMenu

Chip's Home > WebTools > MenuTools > HTML_TreeMenuXL    

Page Revision History

  • 2002-12-02 minor patches (XL2.0.2).
  • 2002-11-15 minor patches (XL2.0.1).
  • 2002-11-14 Major Update (1.1.0/XL2.0) based on TreeMenu 1.1.0.
  • 2002-11-08 Update (1.1a) Smarter path handling on includes. Change image dirnames.
  • 2002-11-07 New Release (1.1). Add ListboxMenus and property list interface. Added expansion and highlighting of selected branches, image size control and style sheet overrides.
  • 2002-11-02 TreeMenuXL Initial Release (1.0), based on TreeMenu 1.0.4
TreeMenuXL Page Contents
Introduction to HTML_TreeMenuXL
Using HTML_TreeMenuXL
Basic TreeMenus
TreeMenus With Style
TreeMenus Without Icons
Rigid and Expanded TreeMenus
Controlling Indenting and Vertical Spacing
LinkSelect, User Images and User Styles
Listbox Menus
History of TreeMenuXL
TreeMenuXL 1.1
TreeMenuXL 1.2
Summary of New Features in TreeMenuXL
HTML_TreeMenu Reference
Things To Do
TreeMenuXL Source Code

Above is a Rigid TreeMenu using default Autostyles, Alternate navigation graphics, and no icons.

What's Here?

HTML_TreeMenu is a wonderful PEAR package by Richard Heyes for generating dynamic tree menus using PHP. HTML_TreeMenuXL is my enhanced version of HTML_TreeMenu. My enhancements have been intended to extend its flexibility and fix a few problems, and I've been placed that Richard has incorporated many of my ideas back into the base package.

This page demonstrates HTML_TreeMenuXL, documents its usage, and offers access to the source code.

Introduction to HTML_TreeMenuXL

HTML_TreeMenu (also referred to as "TreeMenu") is a PHP component for generating dynamic tree-structured menus. TreeMenu will generate the appropriate combination of JavaScript and HTML for a collapsible vertical tree listing that resembles the Windows Explorer folder view. Expandable elements can be used as links, or they can be expanded. Other menu presentations are also possible. TreeMenu is a semi-standard, being part of the PEAR PHP component library since its initial release 2002-06-15.

HTML_TreeMenuXL is my (Chip Chapin's) enhanced version of TreeMenu. It is not my objective to create a fork of the HTML_TreeMenu component. As much as possible, the XL features are done using subclasses, and Richard Heyes, the author of TreeMenu, has been very reasonable about considering my ideas for inclusion in TreeMenu. The extensive changes he made in TreeMenu 1.1 incorporated many of my ideas at the time, fixed a few problems, and provided an improved interface which has greatly simplified the current form of TreeMenuXL. Nevertheless, the current TreeMenuXL release still requires modified versions of his core TreeMenu.php and TreeMenu.js files.

The original HTML_TreeMenu package consists of two PHP Classes: a TreeMenu class and a TreeNode class, each with a corresponding JavaScript class. Menus are built as a hierarchy of tree nodes. With the 1.1 release came the addition of Presentation classes. Now the menu and node classes are independent of the actual menu presentation. This means the same menu object can be used to generate several different types of menu presentations. More importantly, it is now much easier to add new types of menus to the TreeMenu package.

HTML_TreeMenu Home: http://pear.php.net/ and http://phpguru.org/treemenu.php
Last Updated: 2002-11-10 (v1.1.0)

  TreeMenuXL Page Contents
Introduction to HTML_TreeMenuXL
Using HTML_TreeMenuXL
Basic TreeMenus
TreeMenus With Style
TreeMenus Without Icons
Rigid and Expanded TreeMenus
Controlling Indenting and Vertical Spacing
LinkSelect, User Images and User Styles
Listbox Menus
History of TreeMenuXL
TreeMenuXL 1.1
TreeMenuXL 1.2
Summary of New Features in TreeMenuXL
HTML_TreeMenu Reference
Things To Do
TreeMenuXL Source Code
Above is a DHTML TreeMenu using default Autostyles, standard navigation graphics, and no icons.

Using TreeMenuXL

The examples in this section illustrate how to use HTML_TreeMenuXL. In some cases, there may be no significant difference between using TreeMenuXL and using TreeMenu. However I've stuck with the XL interface for consistency. Whereever possible, I'll try to point out where something is an XL-only feature.

Basic TreeMenus

The basic procedure to create a menu is only three steps:

  1. Create a TreeMenu object and a tree of TreeNodes, one node for each menu item.
  2. Create a Presentation object for the type of menu you wish to display.
  3. Print it (generate the HTML and JavaScript).
Menu 1.0
Folder Icon /
Standard Images /
No Styles
Menu 1.1
Folder Icon /
Alt Images
No Styles
Menu 1.2
Folder Icon /
Alt2 Images
No Styles
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam

Note: In older browsers, these menus will be appear fully expanded and will be static. In newer browsers the menus can be expanded and collapsed by clicking on theplus iconandminus iconicons in the tree.

Table 1 -- Basic TreeMenus

Table 1 shows simple TreeMenus drawn with the "folder" icons included with the package. It is also possible to specify a custom icon or no icon for each menu entry. The entries in Table 1 use the three sets of TreeMenu images supplied by Mr Heyes with the distribution package, which I'll refer to as the "Standard Images", "Alt Images", and "Alt2 Images". The three sets each include navigation images (line art, plusses and minusses) and a folder icon. Note that the drawn lines are not visible in the "Alt Images" version.

Below is the PHP code that produced the menus in Table 1. First we create a TreeMenu object and TreeNodes, then we create a Presentation object, and finally we generate the menu.

<?php
  
require_once("TreeMenuXL.php");
  
    
// Create the Menu object and the menu tree
  
$menu00  = new HTML_TreeMenuXL();
  
$nodeProperties = array("icon"=>"folder.gif");
  
$node0 = new HTML_TreeNodeXL("INBOX""#"$nodeProperties);
  
$nx = &$node0->
    
addItem(new HTML_TreeNodeXL("A Folder""#link1"$nodeProperties));
  
$nx = &$nx->
      
addItem(new HTML_TreeNodeXL("Nested Folder""#link2"$nodeProperties));
  
$nx = &$nx->
        
addItem(new HTML_TreeNodeXL("Deeper ...""#link3"$nodeProperties));
  
$nx = &$nx->
          
addItem(new HTML_TreeNodeXL("... and Deeper","#link4"$nodeProperties));
  
$node0->addItem(new HTML_TreeNodeXL("deleted-items""#link5"$nodeProperties));
  
$node0->addItem(new HTML_TreeNodeXL("sent-items",    "#link6"$nodeProperties));
  
$node0->addItem(new HTML_TreeNodeXL("drafts",        "#link7"$nodeProperties));    
  
$node0->addItem(new HTML_TreeNodeXL("spam",          "#link8"$nodeProperties));      
  
$menu00->addItem($node0);
  
$menu00->addItem(new HTML_TreeNodeXL("My Stuff",     "#link9"$nodeProperties));
  
$menu00->addItem(new HTML_TreeNodeXL("Other Stuff",  "#link10"$nodeProperties));
  
$menu00->addItem($node0);

  
// Menu 1.0
  // Create the presentation object.
  // It will generate HTML and JavaScript for the menu
  // These statements must occur in your HTML exactly where you want the menu to appear.
  
$example010 = &new HTML_TreeMenu_DHTMLXL($menu00, array("images"=>"TMimages"));
  
$example010->printMenu();
  
  
// Menu 1.1
  // Create another presentation object from the same menu, 
  // but using an alternate image directory
  
$example011 = &new HTML_TreeMenu_DHTMLXL($menu00, array("images"=>"TMimagesAlt"));
  
$example011->printMenu();
  
  
// Menu 1.2
  
$example012 = &new HTML_TreeMenu_DHTMLXL($menu00, array("images"=>"TMimagesAlt2"));
  
$example012->printMenu();
?>

Note that the same TreeMenu object is used to produce each of the menus, only different presentation objects are created, each with a different image directory. For now, we will only be working with presentation objects of the class HTML_TreeMenu_DHTMLXL. This is the XL version of the general purpose dynamic tree menu class.

Also, notice that each node is created with a property list. The only property defined in the list at this time is icon, which is the file name of the icon that will appear just before the node text (in this case, a file folder).

The HTML_TreeMenu package generates JavaScript code which dynamically creates and controls the menu on the client. There is one supporting JavaScript file which must be included in web pages that use the package as follows:

<script src="TreeMenu.js" language="JavaScript" type="text/javascript"></script>

TreeMenus With Style

Next, let's look at how one can use CSS (Cascading Style Sheets) classes to control the appearance of the different menu levels.

Menu 1.0
Folder Icon /
Standard Images /
No Styles
Menu 2.1
Folder Icon /
Standard Images /
Default Styles
Menu 2.2
Folder Icon /
Standard Images /
User Styles
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam

Table 2 -- TreeMenus With Style

In Table 2 Menu 1.0 appears again for comparison. Menus 2.1 and 2.2 are drawn using the AutoStyle feature. Expand the branches of Menu 2.1 or 2.2 and observe how the text style is different at different levels. The Auto Style feature assigns default CSS styles to the different levels of the menu. Menu 2.1 uses the default styles, while we've assigned a list of user styles for Menu 2.2.

Below is the PHP code that produced Menus 2.1 and 2.2.

<?php
    
// Menu 1.0
    
$example010->printMenu();  // The Presentation object already exists, just print it.

    // Menu 2.1
    
$menuProperties = array("images"=>"TMimages""defaultClass"=>"auto");
    
$example021 = &new HTML_TreeMenu_DHTMLXL($menu00$menuProperties);
    
$example021->printMenu();
        
    
// Menu 2.2
    
$menuProperties = array("images"=>"TMimages""defaultClass"=>"auto",
                            
"autostyles"=>array("smalltextBold""smallitalic""smalltext") );
    
$example022 = &new HTML_TreeMenu_DHTMLXL($menu00$menuProperties);
    
$example022->printMenu();
?>
 

First of all, we continue to use the same TreeMenu object for all these menus. We already have a Presentation object for Menu 1.0, so we just used it to generate another menu. For Menu 2.1, notice that the property defaultClass is set to auto when we create the Presentation object. This sets the default CSS class for every node. This could be the name of an actual CSS class, but the word "auto" is special: it means that the actual CSS class used for each node will be selected automatically, based on that node's level in the tree.

This should become more clear from Menu 2.2. This time, besides setting the defaultClass property, we also set the autostyles property. Autostyles controls the list of automatic styles used in Menu 2.2.

By default, autostyles lists four menu level styles that are defined in the standard TreeMenuXL style sheet: tmenu0text, tmenu1text, tmenu2text and tmenu3text. Why only four? What happens if one has five levels? Menu levels deeper than the number of auto styles are given the deepest defined auto style (tmenu3text in this case).

The standard HTML_TreeMenu style sheet is shown below. It can be included either as a link or directly in your document. The style sheet includes control over link appearance as well. Since all menu items are links, this can be important.

/* TreeMenu.css
  A component of HTML_TreeMenu as extended by Chip Chapin
  2002-10-31 Chip Chapin
*/
.tmenu0text {
  font-family: Verdana, Arial, Helvetica, sans-serif;
  font-size: 10pt;
  font-weight: bold;
}
.tmenu1text {
  font-family: Verdana, Arial, Helvetica, sans-serif;
  font-size: 9pt;
}
.tmenu2text {
  font-family: Arial, Helvetica, sans-serif;
  font-size: 9pt;
  font-style: italic;
}
.tmenu3text {
  font-family: Arial, Helvetica, sans-serif;
  font-size: 7.5pt;
}

/* Since all menu items are links, the following is equally important 
 * to your menu appearance.  
 * The main thing you may want to change are the A:link and A:visited colors.
 */
*.tmenu0text A:link,*.tmenu1text A:link,*.tmenu2text A:link,*.tmenu3text A:link 
  { text-decoration:none; color:#505080 }
*.tmenu0text A:visited,*.tmenu1text A:visited,*.tmenu2text A:visited,*.tmenu3text A:visited 
  { text-decoration:none; color:#505080 }
*.tmenu0text A:active,*.tmenu1text A:active,*.tmenu2text A:active,*.tmenu3text A:active 
  { text-decoration:none; color:#805050 }
*.tmenu0text A:hover,*.tmenu1text A:hover,*.tmenu2text A:hover,*.tmenu3text A:hover 
  { text-decoration:underline; color:#FF0000 }

/* .tmlistbox controls the appearance of Listbox menus */
.tmlistbox {
  font-family: Verdana, Arial, Helvetica, sans-serif;
  font-size: 11px;  /* match 'smalltext' value */
  font-size-adjust: 0.58; /* Verdana */
  margin-bottom: 0px;
}

/* .tmenuSelected is used with linkSelectKey to highlight selected items */
.tmenuSelected { 
  background-color: yellow;
}
*.tmenuSelected A:link    { text-decoration:none; color:#2020ff }
*.tmenuSelected A:visited { text-decoration:none; color:#2020ff }
*.tmenuSelected A:active  { text-decoration:none; color:#ff2020 }
*.tmenuSelected A:hover   { text-decoration:underline; color:#FF0000 }
 

TreeMenus Without Icons

It is possible to specify the icon associated with each menu item, or no icon at all. So far, all of our example menus have been generated with a folder icon (folder icon or folder icon)assigned to each item, but this is very easy to change.

Menu 1.0
Folder Icon /
Standard Images /
No Styles
Menu 3.1
No Icons /
Standard Images /
Default Styles
Menu 3.2
No Icons /
Alt Images /
Default Styles
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam

Table 3 -- TreeMenus With No Icons

Table 3 shows TreeMenus with no icons (Menu 1.0 is included again for comparison). As you can see, "no icons" means here that there is no longer a little folder icon folder icon associated with each item. Unless you're using an older browser, you'll notice that the menus still include the navigation graphics, such asplus iconandminus icon. We shall see later on how to eliminate all the navigation graphics.

The PHP code for Menus 3.1 and 3.2 is shown below. We first have to create a new TreeMenu object where each node has no icon -- icons are properties of the TreeNodes.

<?php
  
// Menu03 -- The nodes are created without icons.
  
$nodeProperties = array("cssClass"=>"auto");
  
$menu03  = new HTML_TreeMenuXL();
  
$node03  = new HTML_TreeNodeXL("INBOX""#"$nodeProperties);
  
$nx = &$node03->
    
addItem(new HTML_TreeNodeXL("A Folder""#link1"$nodeProperties));
  
$nx = &$nx->
      
addItem(new HTML_TreeNodeXL("Nested Folder""#link2"$nodeProperties));
  
$nx = &$nx->
        
addItem(new HTML_TreeNodeXL("Deeper ...""#link3"$nodeProperties));
  
$nx = &$nx->
          
addItem(new HTML_TreeNodeXL("... and Deeper""#link4"$nodeProperties));

  
$node03->addItem(new HTML_TreeNodeXL("deleted-items""#link5"$nodeProperties));
  
$node03->addItem(new HTML_TreeNodeXL("sent-items",    "#link6"$nodeProperties));
  
$node03->addItem(new HTML_TreeNodeXL("drafts",        "#link7"$nodeProperties));    
  
$node03->addItem(new HTML_TreeNodeXL("spam",          "#link8"$nodeProperties));    
  
  
$menu03->addItem($node03);
  
$menu03->addItem(new HTML_TreeNodeXL("My Stuff",      "#link9"$nodeProperties));
  
$menu03->addItem(new HTML_TreeNodeXL("Other Stuff",   "#link10"$nodeProperties));
  
$menu03->addItem($node03);
    
  
// Menu 3.1
  
$example031 = &new HTML_TreeMenu_DHTMLXL($menu03, array("images"=>"TMimages"));
  
$example031->printMenu();

  
// Menu 3.2
  
$example032 = &new HTML_TreeMenu_DHTMLXL($menu03, array("images"=>"TMimagesAlt"));
  
$example032->printMenu();
?>

Comparing this code to the tree creation code for Menu 1.0 and other previous menus, you should notice that the icon property has not been set in $nodeProperties and is therefore not set in each TreeNode as it is created. If icon is not set, or is null, then no icon appears for that node.

Rigid and Expanded TreeMenus

Sometimes one does not want the menu to be expandable and collapsible. I call such static menus Rigid, and introduced them as another extension to the original package. In fact, it is possible to generate such a menu entirely on the server -- it does not require any JavaScript on the client. In TreeMenu 1.1 Richard Heyes added a feature to the JavaScript that achieves the same result, but which does depend on JavaScript. Since I had already written the code to statically generate the menu on the server, you now have your choice between the two methods.

Another option is an Expanded menu, which is still dynamic, but which is fully expanded when it first appears. It's not clear whether this has any practical value...

Menu 4.1
Folder Icon /
Standard Images /
No Styles /
Expanded
Menu 4.2
Folder Icon /
Standard Images /
No Styles /
Not Dynamic
Menu 4.3
Folder Icon /
Standard Images /
No Styles /
Rigid
Menu 4.4
Folder Icon /
Alt Images /
No Styles /
Rigid
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam

Table 4 -- Rigid and Expanded TreeMenus

In Table 4 above, Menu 4.1 is our original Menu 1.0, now set to be Expanded. It appears fully expanded, but still has navigation graphics and can be collapsed.

Menu 4.2 is the same menu again, but this time with the property isDynamic set to false. This causes the client JavaScript to produce a rigid menu.

Menus 4.3 and 4.4 are also rigid, but they are produced using a different presentation class: HTML_TreeMenu_RigidXL. There should be no difference in the appearance of Menu 4.2 and Menu 4.3.

The PHP code which produced these menus is as follows:

<?php
  
// Menu 4.1
  
$example041 = &new HTML_TreeMenu_DHTMLXL($menu00, array("images"=>"TMimages""expanded"=>true"defaultClass"=>"smalltext"));
  
$example041->printMenu();

  
// Menu 4.2
  
$example042= &new HTML_TreeMenu_DHTMLXL($menu00, array("images"=>"TMimages""isDynamic"=>false"defaultClass"=>"smalltext"));
  
$example042->printMenu();

  
// Menu 4.3
  
$example043 = &new HTML_TreeMenu_RigidXL($menu00, array("images"=>"TMimages""defaultClass"=>"smalltext"));
  
$example043->printMenu();

  
// Menu 4.4
  
$example044 = &new HTML_TreeMenu_RigidXL($menu00, array("images"=>"TMimagesAlt""defaultClass"=>"smalltext"));
  
$example044->printMenu();
?>
 

One other thing to observe from Table 4 is the use of defaultClass to make all the text smaller.

Controlling Indenting and Vertical Spacing

The Problem: Embedded Images

You might have noticed that all our menus up until now have the same vertical spacing. The line for each menu entry is the same height no matter how small the font is. The reason is that, up until now, each of our menu entries has contained 20x20 graphic elements on the line, sometimes invisibly.

All of the folder icons, navigation buttons, line elements, and even the "invisible lines" in the Alt Images are 20x20 images. But if we can finally remove all graphic elements, the line spacing will be determined by the style and text content for that line.

The same observation can be made about the indenting of each line. Until now, each menu line is indented by some multiple of 20 pixels, since the indenting is controlled by the number of graphic elements at the start of each line. If we want any different indenting we will either have to remove the graphic elements or find a way to use different sizes.

Getting Rid of Navigation Images

We already know that icons are only included if we ask for them. And we can easily get ride of the navigation buttons and lines by setting the "images" property to null. But watch out! If your menu has no nav buttons then you won't be able to expand it. So you should generate a rigid menu.

So, to entirely eliminate graphics from a tree menu it should have the following properties:

Menu 5.1
No Icons /
Standard Images /
Default Styles /
Rigid
Menu 5.2
No Icons /
Alt Images /
Default Styles /
Rigid
Menu 5.3
No Icons /
XL Images /
Default Styles /
Rigid
Menu 5.4
No Icons /
No Images /
Default Styles /
Rigid
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
  A Folder
    Nested Folder
      Deeper ...
        ... and Deeper
  deleted-items
  sent-items
  drafts
  spam
My Stuff
Other Stuff
INBOX
  A Folder
    Nested Folder
      Deeper ...
        ... and Deeper
  deleted-items
  sent-items
  drafts
  spam

Table 5 -- Rigid TreeMenus With No Icons

Table 5 shows several rigid menus with no icons, showing the effect of various different line graphics sets. Only Menu 5.4 is complete free of graphic images. Notice that the line spacing is controlled by the font size for each menu entry. The indenting, in the absence of any graphics, is done with two "&nbsp;" entities for each level.

In Menu 5.1 you can see the line graphics that are part of the standard images. These 20x20 images control the line spacing and the indenting. Menu 5.2 has the same line spacing and indenting, controlled by the invisible 20x20 Alt images.

Menu 5.3, however, introduces something new. It uses a set of "XL Images" and introduces a new set of properties for controlling image size: lineImageWidth and lineImageHeight.

Here is the code for producing all the menus in Table 5.

<?php
  
// Menu 5.1
  
$example051 = &new HTML_TreeMenu_RigidXL($menu03, array("images"=>"TMimages"));
  
$example051->printMenu();

  
// Menu 5.2
  
$example052 = &new HTML_TreeMenu_RigidXL($menu03, array("images"=>"TMimagesAlt"));
  
$example052->printMenu();

  
// Menu 5.3
  
$menuProperties = array("images"=>"TMimagesXL""lineImageHeight"=>16"lineImageWidth"=>10);
  
$example053 = &new HTML_TreeMenu_RigidXL($menu03$menuProperties);
  
$example053->printMenu();

  
// Menu 5.4
  
$example054 = &new HTML_TreeMenu_RigidXL($menu03, array("images"=>""));
  
$example054->printMenu();
?>

Take a look at the code for Menu 5.3. The property setting "images"=>"TMimagesXL" selects the "XL Images" set. The property settings "lineImageHeight"=>16, "lineImageWidth"=>10 set the sizes that will be used for all the navigation images.

The XL Images set includes transparent 1x1 GIF spacers for all the navigation images. These can be used at any size, so one has complete freedom in setting their height and width. In Menu 5.3 the line images are set to be 10 pixels wide and 16 pixels high. The result is a menu in which the minimum line height is 16 pixels, and the indentation width is 10 pixels.

LinkSelect, User Images and User Styles

User Images

They don't appear in Menu 5.3, but included in the "XL Images" are a set of 12x9 navigation buttons (12 pixels wide, 9 pixels high). By "navigation button" I mean the and buttons. Navigation button sizes are also controlled using lineImageWidth and lineImageHeight, so 12x9 will be the correct settings if you want to use these particular images in a dynamic menu. If you use the wrong size you will get distortion, like this: .

The important point here is not really the sizes of the XL Images, but that you can create your own images. You just have to pay attention to the size.

LinkSelect

Another new feature in TreeMenuXL is LinkSelect which allows you to dynamically expand and highlight one (or more) of the menu nodes. Set the linkSelectKey property to a string that will match one of the link targets in the menu. Then any menu item with a link target that matches the linkSelectKey value will be highlighted and its branch will be expanded. linkSelectKey can also be set to an array of values.

We have already discussed User Styles and given an example in Menu 2.2. Here they are combined with the other features to produce a custom menu.

Menu 6.1
No Icons /
XL Images /
Default Styles
Menu 6.2
No Icons /
XL Images /
Default Styles /
LinkSelect
Menu 6.3
No Icons /
XL Images /
User Styles /
LinkSelect
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam
My Stuff
Other Stuff
INBOX
A Folder
Nested Folder
Deeper ...
... and Deeper
deleted-items
sent-items
drafts
spam

Table 6 -- Dynamic TreeMenus with LinkSelect, User Images and User Styles

All the menus in Table 6 illustrate the use of the XL images. In each case lineImageWidth and lineImageHeight are set to 12 and 9 respectively to match the size of the navigation icons. Menus 6.2 and 6.3 use LinkSelect to expand and highlight certain menu entries.

The full code for Table 6 is shown below. This also shows how to "unset" certain menu properties.

<?php
  
// Menu 6.1
  
$menuProperties = array("images"=>"TMimagesXL"
                          
"lineImageHeight"=>9"lineImageWidth"=>12 );
  
$example061 = &new HTML_TreeMenu_DHTMLXL($menu03$menuProperties);
  
$example061->printMenu();

  
// Menu 6.2
  
$menuProperties = array("images"=>"TMimagesXL"
                          
"lineImageHeight"=>9"lineImageWidth"=>12,
                          
"linkSelectKey"=>"#link5" );
  
$example062 = &new HTML_TreeMenu_DHTMLXL($menu03$menuProperties);
  
$example062->printMenu();
  
$menu03->unsetProperties( array("selected""expanded") );

  
// Menu 6.3
  
$menuProperties = array("images"=>"TMimagesXL",
                          
"lineImageHeight"=>9"lineImageWidth"=>12,
                          
"linkSelectKey"=>"#link3",
                          
"autostyles"=>array("smalltextBold""smallitalic""smalltext""xsmalltext") );
  
$example063 = &new HTML_TreeMenu_DHTMLXL($menu03$menuProperties);
  
$example063->printMenu();
  
$menu03->unsetProperties( array("selected""expanded") );
?>

The TreeMenu member function unsetProperties() is used in Table 6 for the first time. But you will probably never need it. I use it here to clean up the TreeNodes after the effect of LinkSelect so I can use the TreeMenu again in these examples.

Listbox Menus

I became interested in HTML_TreeMenu because I wanted to replace my previous menu system. One feature of my old code was that, in addition to a tree structured menu, I could use it to generate a Listbox to perform the same function. I like to use these Listboxes in the page footer, and sometimes elsewhere. As of HTML_TreeMenu 1.1, a listbox presentation class is included in the package. However there were still some features that I wanted which it lacked, and so I have an extended HTML_TreeMenu_ListboxXL presentation class.

Listbox 1
Standard Listbox: HTML_TreeMenu_Listbox

Table 7 -- Standard Listbox

Listbox 2
Extended Listbox: HTML_TreeMenu_ListboxXL
Default Listbox Style Class (tmlistbox)
No Listbox Style Class
User Listbox Style Class (xsmalltext)

Table 8 -- Extended Listbox with Styles

All of the Listboxes in Tables 7 and 8 are generated from the same menu object as Menu 1.0. But a new Presentation class is used.. Table 7 uses the standard TreeMenu listbox while Table 8 uses the XL extended Listbox class. The code is shown below:

<?php
  
// Listbox 1
  
$lbox01 = &new HTML_TreeMenu_Listbox($menu00);
  
$lbox01->printMenu();

  
// Listbox 2.1
  
$lbox021 = &new HTML_TreeMenu_ListboxXL($menu00);
  
$lbox021->printMenu();

  
// Listbox 2.2
  
$lbox022 = &new HTML_TreeMenu_ListboxXL($menu00, array("cssClass"=>""));
  
$lbox022->printMenu();

  
// Listbox 2.3
  
$lbox023 = &new HTML_TreeMenu_ListboxXL($menu00, array("cssClass"=>"xsmalltext"));
  
$lbox023->printMenu();
?>
 

The current advantages of the XL listbox are that it offers control over the CSS class within the form, supports pre-selection of an option, and allows a bit more flexibility in the appearance of the options themselves. Some or all of these features may migrate into the standard class in the future.

Why the 'Go' Button? Why not use 'onChange'?

Someone will ask, "Why the 'Go' button? Why not use 'onChange' and save a click?" The reason is that onChange in select boxes is often a disaster for people with wheel mice. Just imagine scrolling down a page and suddenly twirling the selection inadvertently. Then off you go. Just forget about it.

Listboxes With Bullets

The XL listbox class supports a bullet format within the list. To use it, set the property useBullets to true. You may wish to also set indentNum to 1 in order to avoid excessive indenting.

Listbox 3
Listbox With Bullets

Table 9 -- Extended Listbox

Below is the code for Table 9:

<?php
      $mprops 
= array("useBullets"=>true"indentNum"=>1);
      
$lbox03 = &new HTML_TreeMenu_ListboxXL($menu00$mprops);
      
$lbox03->printMenu();
?>

The list of bullet formats is set using property bulletStyles, an array. For more information see the property descriptions below.

Pre-Selecting Listbox Options

When I use a listbox for navigation I like to preselect the option corresponding to my current location. The XL Listbox class will do this using the linkSelectKey property, just like the TreeMenu presentation class. To illustrate, here's a more useful example: the Table of Contents for this document.

Listbox Menu 4
Table of Contents

Table 10 -- Table of Contents Listbox, using linkSelectKey

Try it! The code Listbox 4 is below:

<?php
  
// Listbox 4
  
$mprops = array("useBullets"=>true"indentNum"=>1"linkSelectKey"=>"#listbox");
  
$lbox04 = &new HTML_TreeMenu_ListboxXL($pgmenu$mprops);
  
$lbox04->printMenu();
?>

ListboxXL Properties

cssClass
The text style of the listBox is controlled by the property cssClass, which by default is set to "tmlistbox". cssClass will be used to set the class of the SELECT and INPUT elements. Note: I've usually found it necessary to adjust the font sizes on different browsers to get a consistent appearance. Set cssClass to the empty string if you don't want any classes set.
(XL only)
indentChar
Actually a string, not just a character. It will be used for indentation on each line. Defaults to "&nbsp;"
(standard)
indentNum
The number of times indentChar is repeated for each indentation level. So, array("indentChar"=>"&nbsp;", "indentNum"=>2) would result in each indentation level being two spaces (&nbsp;&nbsp;). Default value is 2.
(standard)
promoText
If set, this text will appear as the first option in the list. In the standard listbox class this defaults to "Select...". In the XL class this defaults to null.
(standard)
bulletStyles
An array of strings that can be used as part of the leading in addition to the indentChar. This allows you to put different sorts of bullets in front of menu entries at different levels. Default is currently array('', '&#8226; ', '-- ', '&nbsp;- ', '&nbsp;').
(XL only)
useBullets
True/false, controls whether or not to use the bulletStyles. Default is false.
(XL only)
linkSelectKey
Works in much the same way as for the TreeMenu presentation classes. Matching menu nodes (ideally there should be only one match) will have the "selected" attribute added to their OPTION element, so that it will be pre-selected in the listbox.
(XL only)

 

TreeMenuXL History

TreeMenuXL 1.1 (1.0.4/XL1.1)

When I began working with TreeMenu 1.0.4, I found the following issues:

I wanted greater built-in control over the menu appearance, and I wanted to produce different kinds of menu representations, such as listboxes, in addition to the trees. Part of my solution to the Netscape 4.x problem was to add the capability of statically generating menus, instead of depending entirely on client-side JavaScript for this function.

In addition to providing solutions for these problems, TreeMenuXL 1.1 offered a number of new features: The Style extension for using CSS classes with menu nodes, Menus without images, Listbox Menus, Rigid and Expanded menus, the property list interface, image size control, expansion and highlighting of selected branches (linkSelect).

TreeMenuXL 2.0 (1.1.0/XL2.0)

Richard Heyes' release of TreeMenu 1.1.0 contains solutions for most of the issues that I had with TreeMenu 1.0.4, and in several cases adopts my ideas (while generally improving on the implementation). This greatly simplifies the code for TreeMenuXL, and so the XL 2.0 release is a reimplementation using the new TreeMenu 1.1.0 base.

XL 2.0 still offers a number of benefits over the current TreeMenu 1.1.0, including Menu-independent assignment of Presentation properties, more usable Style interface, menus without images, more-flexible listbox menus, statically generated Rigid menus, flexible node creation interface using both positional parameters and property list array, image size control, expansion and highlighting of selected branches (linkSelect).

Summary of New Features in TreeMenuXL

This section is current as of TreeMenu 1.0.4 and TreeMenuXL 1.1. It has not yet been entirely updated for TreeMenu 1.1.0 and TreeMenuXL 2.0.

What features are in TreeMenuXL that aren't in the current TreeMenu release?

Styles for Menu Nodes
The Style extension supports the use of style sheets (CSS) to control the appearance of menu entries. It has an automatic mode that assigns standard styles to different levels of the menu tree. It possible to override the standard styles in a variety of ways.
 
Menus without Images
In its original form, HTML_TreeMenu always uses 20x20 graphic elements in the generated menus, though they may be invisible. This constrains the layout of menu. HTML_TreeMenuXL currently provides limited support for menus without images.
 
Listbox Menus
A new output option is available for statically generating HTML listboxes from a menu object. The extended Listbox class offers control over the CSS class within the form, supports pre-selected options, and allows greater flexibility in the appearance of the options themselves.
 
Rigid and Expanded Menus
My solution to the Netscape 4.x problem was to perform server-side browser detection and generate static menus on the server for older browsers. Once the code was in place for doing this, it was easy to add the Rigid Menu feature. I have also extended the Expanded Branch function in the original package so that it's easier to create a dynamic menu that starts out fully expanded.
 
Property List Interface
Along with these extensions has come a proliferation of new menu properties that need to be controlled. Rather than multiply the argument lists of the class functions, most behavior is now controlled using property lists.
 
Image Size Control
The sizes of line and icon graphics is no longer limited to 20x20.
 
Expansion and Highlighting of Selected Branches (LinkSelect)
HTML_TreeMenuXL will automatically expand the branches containing nodes that match certain criteria (for example, of the current page), and can highlight the selected nodes.
 

HTML_TreeMenu Reference

To Be Added... Intended to be a concise summary of the interface and property settings.

Things To Do

This section is my personal list of further work to be done on my version of the HTML_TreeMenu package. Remember, Richard Heyes is the original author and maintainer of HTML_TreeMenu, and he will undoubtedly have different priorities. No assumptions should be made regarding when or if any of these enhancements will be completed, or when they will be merged into Heyes' official version of this package.

Want to suggest an enhancement? Feel free, I don't bite. Send me mail. I will try to give it serious consideration.

HTML_TreeMenuXL Source Code

Click here to see the source code for this page in a new window:

  

Click the link to download HTML_TreeMenuXL:

Archive Versions:

 

.

Valid HTML 4.0! Valid CSS! Chip's Home Page

Updated Monday May 15, 2006 22:18:59 PDT