1 Get the Zapatec DHTML Tree files
1.1 Download the Zip file
1.2 Unzip zptree.zip
2 Create a Tree with the Wizard
2.1 What does the Wizard Do?
2.2 How to Start the Wizard
2.3 Using the Wizard
2.4 Tree Contents
2.5 Configuration
2.5.1 Highlight selected node
2.5.2 Icons style
2.5.3 Compact mode
2.5.4 Dynamic initialization
2.5.5 Collapsed tree
2.5.6 Initial level
2.6 Preview
2.7 Get Your Code
3 Quick Startup (Without Wizard)
3.1 Set Up Your Tree
3.1.1 insert the headers
3.1.2 Path Warning
3.2 Create the Tree
3.2.1 Define the Data
3.2.2 Create the Tree
3.3 Copy your files to your web server
3.4 Test the tree application
3.5 Change Included Files
3.5.1 Use a Different Themes
3.6 Customize Icons
4 Configuration Options
4.1 Configuration Parameters
4.1.1 hiliteSelectedNode (boolean, default "true")
4.1.2 compact (boolean, default "false")
4.1.3 initLevel (integer or boolean, default "false")
4.2 Custom Expanded/Collapsed Items
4.3 Synchronizing
5 Tree API
5.1 Expand or collapse all nodes
5.2 Synchronize the tree
5.3 Expand/collapse/toggle single items
5.4 Custom Event Handlers
5.5 Adding and Removing Nodes
5.5.1 addNode
5.5.2 insertNode
5.5.3 removeNode
The DHTML Tree files are bundled in a zip file. Click the download link in the Tree section of Zapatec’s web site and follow the instructions to download the file.
Save the file (zptree.zip) to your website’s root folder on your computer or server.
On your computer, go to the folder where you saved the file zptree.zip.
zptree.zip contains a folder called zptree that holds all of the files you nneed to create your tree.
Open or double-click zptree.zip to unzip or unpack it.
You can create a Zapatec tree with or without using the wizard.
The wizard generates the code for exactly the kind of tree you want! It is a Graphic User Interface (GUI) that allows you to visually select the nodes, theme, and more. After you have made your selections, the wizard creates the code you need to place in your HTML document, form, or application with the click of a button.
If you haven’t done so, follow the instructions in section 1.1. to download the Tree files.
Navigate to your DHTML Tree folder (zptree).
Open index.html in your Web browser.
Click Wizard in the left menu.
In the wizard, click the Next and Previous buttons to move through the panes, or choose a specific pane from the top menu. Roll your mouse over the question marks for additional information about the various options.
The first pane introduces the wizard and explains how to use it.
Click Next to move to the Tree Contents page and start creating your tree.
This pane starts with a simple tree and lets you add, remove and rename nodes and branches. Since the tree is built using standard HTML lists, you can also build the actual tree contents in your favorite editor or GUI or have your server generate the nodes programmatically from a database.
To build a tree, you can choose from the following actions:
Insert Item Before: Click a node in the tree, edit the text of the node, and then click Insert Item Before. The wizard creates a node before the node you selected.
Insert Item After: Click a node in the tree, edit the text of the node, and then click Insert Item After. The wizard creates a node after the node you selected.
Remove Node: Click a node in the tree, then click Remove Node. The node will be removed.
Add Subtree: Click a node in the tree, then click Add Subtree. The wizard creates a sub-tree after the selected node.
Change The Text for a Node: Click a node in the tree and edit the text in the text field.
You can choose different options in the configuration pane and then preview the tree in the preview pane, Experiment with the different options and go back and forth between this configuration pane and the preview pane until the tree looks the way you want it.
Checking this option causes the selected node to be highlighted.
Choose the style of icons for the tree, or choose "no icons" for a tree with no icons.
Check to turn on compact mode in the tree. In compact mode, a tree only allows one expanded branch per level. When a user expands another branch, the tree automatically collapses the previous branch, thus keeping the tree compact This setting implies a collapsed tree.
Check this box if you want the tree to use a technique called "dynamic initialization". Dynamic initialization results in much faster startup time for large trees. Instead of reading the whole tree ahead of displaying it, Zapatec tree generates subtrees on demand when the user opens them. You need this option only for large trees with hundreds of nodes or more. This setting implies a collapsed tree.
Dynamic initialization is incompatible with the expandAll() method described in Section 5.1. Do not use expandAll() for a tree that is configured for dynamic initialization.
Check this box if you want the tree to appear with all its branches closed when it is initially presented.
Check this box if you want the tree to expand only to a certain level. You specify a nuber for the level and only branches included in that level will open. For example, in a tree with initial level set to 2, children and grandchildren will display, but not great grandchildren.
This pane provides a preview of your tree. If you are not happy with any of the options, you can click the Previous button to go back and change them.
The Wizard displays the code for your tree. Click select all to copy the code to the clipboard. In your editor, paste and save it. The paths in the code assume that the tree file will be in the same folder as the zptree folder, not in the zptree folder itself. If you save the file in a different folder, you need to adjust the paths accordingly.
If you have not done so follow the instructions in section 1.1. to download and unzip the tree files.
In your web editor (Dreamweaver, UltraEdit, etc.), open the web page where you want the tree placed. Insert your cursor before the ending </head> tag. Paste the following style path and script paths before the ending </head> tag:
<!-- Javascript utilities file for the tree--> <script src="zptree/utils/utils.js" type="text/javascript"></script> <!-- basic Javascript file for the tree--> <script src="zptree/src/tree.js" type="text/javascript"></script> <!-- basic CSS file for the tree--> <link href="zptree/themes/tree.css" rel="stylesheet" /> <!-- CSS file for the lines in the tree--> <link href="zptree/themes/tree-lines.css" rel="stylesheet" /> <!-- CSS file for icons for folders and files windows style in the tree--> <link href="zptree/themes/windows.css" rel="stylesheet" />
The five lines point to five different files located in the tree folder. The files are:
utils.js
Located in the utils folder. This is the general javascript utilities file.
tree.js
Located in the src folder. This is the main javascript tree file.
tree.css Located in the themes folder. This is the main javascript CSS file.
tree-lines.css Located in the themes folder. Provides lines between tree nodes. Remove this file if you do not want lines.
windows.css Located in the themes folder. Provides windows-style icons for open folder, closed folder, etc.
If your web page containing the tree is saved in the folder above the tree folder, these lines will work without any changes. If, however, you save your web page in another location (like directly under your website’s root folder),you need to adjust the path for these files.
First define the data for the tree and then create the tree object.
The tree data is defined as a nested HTML list. The items can be in unordered lists <UL> or ordered lists <OL>. The top <UL> needs to have an id parameter, which will be used for creating the tree object.
<ul id="myTree">
<li>
item 1
</li>
<li>
item 2
<ul>
<li>
item 2.1
</li>
<li>
item 2.2
</li>
</ul>
</li>
</ul>
The easiest way to create the tree is to do it when the HTML finishes loading.
<body onload="new Zapatec.Tree('myTree')">
An alternative is to place the following code after the section in which you defined the data for the tree. Do not place it before that section, because Javascript will not be able to find the tree definition and will generate an error.
<script type="text/javascript">
new Zapatec.Tree("myTree");
</script>
Using your editing or FTP program, copy or "put" your web page and the entire tree folder to the root of your website.
Using your web browser, navigate to the web page that you created to include the Zapatec HTML Tree. Congratulations! You have set up the most basic version of the Zapatec HTML Tree! Now, on to the fun and exciting features you can change with this highly adaptable application!
You can change the theme of the tree by including a different file in your header.
One of the lines you inserted in Section 3.1.1 includes the windows.css file in the themes folder. Windows is one of the themes that comes with the Zapatec DHTML Tree. You can choose among several themes by changing the CSS file. Look in the themes folder for more options.
You can add custom icons to each node by inserting image <IMG> tags inside the node’s HTML list item tags before the item label:
<li> <img src="icon.gif" alt="An icon" /> Our item with an icon </li>
If you include two icons, the first displays when the item is expanded, and the second when the item is collapsed:
<li> <img src="folder-open.gif" alt="Expanded folder" /> <img src="folder-closed.gif" alt="Closed folder" /> C:\WINDOGS<ul> [ ... subtree content ] </ul> </li>
As mentioned earlier you create a tree using the following syntax:
<body onload="new Zapatec.Tree('myTree')">
You can also pass a set of parameters to control the tree behavior when you create the tree:
<script type="text/javascript">
new Tree('tree', { hiliteSelectedNode: false, initLevel: 2 });
</script>
This specifies that the tree should not highlight selected nodes and that the initial tree can expand to at most two levels. If you wanted the tree to be collapsed when it is initially displayed, you should pass initLevel: 0.
The following section describes the tree configuration parameters.
This option specifies whether the tree should highlight selected nodes. Pass "false" for no highlighting.
When this option is true, the tree is collapsed when it is initially presented, and it will not allow two nodes within the same subtree to be expanded in the same time. In this case, if one node is expanded, all its relatives (other nodes within the same subtree) are automatically collapsed.
If a number is passed, the tree expands only up to that level when it is first presented. Otherwise (when initLevel passes "false") the tree expands. This option can be overridden on a node by node basis as described in the next section.
Up to now we have seen how to expand and collapse the whole tree. This section explains how override the tree’s behavior in this regard on a node by node basis.
You can collapse or expand individual nodes by setting them to a specific "collapse" or "expanded" class, as demonstrated below:
<li class="collapsed">
Initially collapsed node
<ul>
... define the subtree here
</ul>
</li>
The item defined in this code will be initially collapsed, regardless of whatever options were passed to when the tree was created. So even if the initLevel were set to "false", which means a fully expanded tree, or were numeric to extend beyond the level of this item, this item will be collapsed since its class is set to "collpased". The class attribute has precedence in determing whether a node is initially expanded or collapsed.
Similarly, you can pass class="expanded" to certain nodes to ensure that they will be initially expanded, even if compact is "true" or initLevel would not allow that node to be initially expanded.
However, the class attribute applies only to subnodes, not to parent nodes. Even if you pass "expanded" to a certain node, if its parent is initially collapsed, the node you are trying to expand will not be visible at all. Of course, when you expand its parent, the node in question expands also If you wish to expand the ancestors of some item, you can either assign class="expanded" to all its parents or synchronize the tree, as described in the next section.
The tree can be initially synchronized to a certain item. In this case, all items are initially collapsed, except the ancestors of that specific item and the item itself, if it has children.
To synchronize expand/collapse behavior for an item, specify class="selected" for the item that you want the tree to be sync-ed to.
You can access certain tree operations using external Javascript code. To do this you need a reference to the tree object. You can get it either by saving the return value of "new Zapatec.Tree" or by using the global property "Zapatec.Tree.all".
<script type="text/javascript">
var myTree;
function initTree() {
myTree = new Tree('id-of-the-ul-element');
}
</script>
<body onload="initTree()">
Later you can use the "myTree" variable.
Or, using the "Tree.all" variant, create the tree:
<body onload="new Tree('id-of-the-ul-element')">
Then you can use:
var tree = Tree.all("id-of-the-ul-element");
to get a reference to the tree object.
You can expand, collapse or toggle all nodes using the following tree methods:
tree.expandAll()
tree.collapse.All()
tree.toggleAll()
Then you can cause all nodes to expand or collapse in response to an external event such as a button click:
<script type="text/javascript">
function expandAll() {
var myTree = Zapatec.Tree.all["tree"];
myTree.expandAll();
}
</script>
<button onclick="expandAll()">Expand all nodes</button>
Similarly, use "myTree.collapseAll()" if you want to collapse all nodes.
You can also use "tree.toggleAll()" if you want to toggle all tree items, in other words, to collapse expanded nodes and to expand collapsed nodes.
Dynamic initialization is incompatible with the expandAll()and toggleAll() methods. Do not use these methods for a tree that is configured for dynamic initialization.
You can use the tree.sync(item-string) method to synchronize the expanded/collapsed state of a tree to a certain item, if you have the id of the item.
You know the id of the item if you assign it yourself:
<li id="my-item"> ... </li>
Then you can synchronize the tree to that item:
myTree.sync("my-item");
You can expand, collapse or toggle a specific item using tree.toggleItem(item-id-string, boolean):
// this will expand the item "foo"
// note we're passing "true" to expand it no matter what
tree.toggleItem("foo", true);
// this will collapse the item "bar"
// note we're passing "false" to collapse it regardless the current
// state
tree.toggleItem("bar", false);
// if we're not passing the second argument, the item will be toggled
tree.toggleItem("baz");
For certain applications, you might need to install event handlers for tree actions. Currently, the tree supports one event handler: onItemSelect. This event fires when an item is clicked. An item can also become selected as a result of a sync operation, but in this case the handler is not called because there is no onclick event to trigger it.
Tto install an event handlern you need a reference to the tree element. For example:
<script type="text/javascript">
function init() {
var tree = new Zapatec.Tree('tree');
tree.onItemSelect = ourHandler;
}
function ourHandler(item_id) {
alert("Item with ID " + item_id + " was clicked");
}
</script>
<body onload="init()">
In this example, the event handler is installed immediately after the tree is created. Our handler will simply display a message dialog stating the ID of the item that was clicked.
You can programmatically add nodes to the tree at runtime. This might be triggered by users’ clicks or some other event.
Use the addNode, insertNode, or removeNode functions as appropriate to add nodes to or remove nodes from an existing tree.
See the Tree Pruning Demo.
The addNode function appends a node to a tree. It takes three arguments:
string pID - ID of the parent of the node being added
string cID - ID of the new child node
boolean atStart - if true, appends the new node at the start (top) of the existing tree; if false, appends it at the end (bottom); default is false
This example adds a node called "Misc1" at the start of the tree named "tree" and another node named "Misc2" at the bottom of the tree.
<a href="javascript:addNode('tree', 'Misc1', true)"></a>
<a href="javascript:addNode('tree', 'Misc2')"></a>
The insertNode function inserts a node into a tree before the specified node. It takes two arguments:
string newID - ID of the new child node being inserted
string refID - ID of the node that will come after the new node in the tree; specifies both the tree and the reference node using dot notation
This example inserts a subtree named "Misc9’ before the "item-1’ node in the "zapatec-tree" tree.
<a href="javascript:insertNode('Misc9', 'zapatec-tree.item-1')"</a>>
The removeNode function removes the specified node and all of its subnodes, if it has any. It takes one argument:
string oldNode - node to remove
This example removes a subtree named "item-7" from the "zapatec-tree" tree.
<a href="javascript:removeNode('zapatec-tree.item-7')"</a>