HTML_TreeMenuXL
An Enhanced Version of HTML_TreeMenu
| 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
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)
| |
|
|
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:
- Create a TreeMenu object and a tree of TreeNodes,
one node for each menu item.
- Create a Presentation object for the type of menu you wish
to display.
- Print it (generate the HTML and JavaScript).
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.
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
(
or 
)assigned
to each item, but this is very easy to change.
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
associated with each item. Unless you're using an older browser, you'll notice
that the menus still include the navigation graphics, such as
and
.
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...
TreeMenuXL Page Contents
Introduction to HTML_TreeMenuXL
Listbox Menus
