Getting Started

To use the TreeView control, include the following source files in your web page with the script tag:

 <!-- Required CSS -->
<link type="text/css" rel="stylesheet" href="http://yui.yahooapis.com/2.5.2/build/treeview/assets/skins/sam/treeview.css">
 
  <!-- Dependency source files --> 
  <script src = "http://yui.yahooapis.com/2.5.2/build/yahoo/yahoo-min.js" ></script>
  <script src = "http://yui.yahooapis.com/2.5.2/build/event/event-min.js" ></script>

  <!-- TreeView source file --> 
  <script src = "http://yui.yahooapis.com/2.5.2/build/treeview/treeview-min.js" ></script>
  

The TreeView control is defined by YAHOO.widget.Tree. The nodes of the tree are defined by the base class YAHOO.widget.Node and various subclasses.

Creating the Tree

Create a tree by instantiating TreeView with the ID of the element in which you want to draw the tree:

var tree;
function treeInit() {
	tree = new YAHOO.widget.TreeView("treeDiv1");
}

You can use an element reference instead of an ID:

var tree;
function treeInit() {
	tree = new YAHOO.widget.TreeView(document.getElementById("treeDiv1"));
}

Once the tree object has been created you can begin to add its nodes. The HTML code for the tree is not inserted into the host element until you call the draw method, so any nodes you add prior to calling the draw method will be present when it is rendered.

var tree;
function treeInit() {
	tree = new YAHOO.widget.TreeView("treeDiv1");
	// add nodes here
	tree.draw();
}

Adding Nodes

When the tree is created, a root node is generated automatically. The constructor for a new node takes the parent node as an argument. You can get a reference to the tree's root node to build the first level of the tree with the getRoot method:

var tree;
function treeInit() {
	tree = new YAHOO.widget.TreeView("treeDiv1");
	var root = tree.getRoot();
	var tmpNode = new YAHOO.widget.TextNode("mylabel", root, false);

	tree.draw();
}

The above example appends a text node to the root of the tree with "mylabel" as the label. The last parameter is a boolean that indicates whether or not the new node should be expanded when the HTML for the tree is generated.

The new node you created (tmpNode) can now be used as the parent for other nodes.

var tree;
function treeInit() {
   tree = new YAHOO.widget.TreeView("treeDiv1");
   var root = tree.getRoot();
   var tmpNode = new YAHOO.widget.TextNode("mylabel1", root, false);
   var tmpNode2 = new YAHOO.widget.TextNode("mylabel1-1", tmpNode, false);

   tree.draw();
}

Removing Nodes

Nodes can be removed with the removeNode method. The removed node's descendants are also deleted.

tree.removeNode(nodeToRemove);

The TreeView instance's popNode method can be used to remove a node from a tree while preserving the node's child collection. You can also use the Node object's appendTo, insertBefore, and insertAfter methods to move the popped node to a new location within the Tree.

// remove the node and insert it before another node
tree.popNode(nodeToPop);
nodeToPop.insertBefore(anotherNode);
anotherNode.parent.refresh();

// remove the node and append it to another node
tree.popNode(nodeToPop);
nodeToPop.appendTo(anotherNode);
anotherNode.refresh();

See the examples below in Using TreeView or the API Documentation for more details.

Using TreeView

This section describes several common uses and customizations of TreeView and contains these sections:

• Setting Up your Style Definitions
• Keeping Custom Properties in Node References
• Changing the Behavior for the Label of a Text Node
• Responding to Events
• Loading Your Data Dynamically
• Creating Custom Node Types

Setting Up your Style Definitions

The TreeView component makes use of several CSS classes to style the tree. You can either use the CSS provided in the download source, or you can create your own. If you create your own, you'll need to follow TreeView's naming conventions for its CSS classes.

Icon styles:

• ygtvtn: First or middle sibling, no children
• ygtvtm: First or middle sibling, collapsible
• ygtvtmh: First or middle sibling, collapsible, hover state
• ygtvtp: First or middle sibling, expandable
• ygtvtph: First or middle sibling, expandable, hover state
• ygtvln: Last sibling, no children
• ygtvlm: Last sibling, collapsible
• ygtvlmh: Last sibling, collapsible, hover state
• ygtvlp: Last sibling, expandable
• ygtvlph: Last sibling, expandable, hover state
• ygtloading: Loading dynamic data indicator

Depth spacer styles:

• ygtvdepthcell: Node's ancestor at the current depth has a next sibling
• ygtvblankdepthcell: Node's ancestor at the current depth does not have a next sibling

Container styles:

• ygtvitem: The node's container element
• ygtvchildren: The container around each node's collection of children

Text styles:

• ygtvlabel[link,visited,hover]: The style of the text label/href when using TextNode

You can review the current CSS definitions for TreeView by looking at the CSS file that accompanies TreeView in the YUI download or by reviewing the current production CSS:

• http://yui.yahooapis.com/2.5.2/build/treeview/assets/skins/sam/treeview.css

Multiple trees with different styles

You can configure multiple different presentation styles for multiple trees on the same page by defining the additional styles using id selectors on the element containing the tree. An example of this technique is provided.

Keeping Custom Properties in Node References

The TreeView control accepts objects as the first argument of the node constructor. This provides an opportunity for storing metadata about the node in its object. If you do this, TreeView will store your object in the data member of the node object; it looks for a property called "label" within your metadata object and applies this value as the label of the node. This feature can be useful when handling events passed to you by the TreeView Control (See Responding to Events, below, for an example of this use).

var tree;
function treeInit() {
   tree = new YAHOO.widget.TreeView("treeDiv1");
   var root = tree.getRoot();
   var myobj = { label: "mylabel1", id:"myid1" };
   var tmpNode = new YAHOO.widget.TextNode(myobj, root, false);

   tree.draw();
}

Changing the Behavior for the Label of a Text Node

By default, clicking the text label of a node expands or collapses it. You can change this behavior to a URL by using a custom object to instantiate your node and providing an href property:

var tree;
function treeInit() {
   tree = new YAHOO.widget.TreeView("treeDiv1");
   var root = tree.getRoot();
   var myobj = { label: "mylabel1", href:"http://www.yahoo.com" };
   var tmpNode = new YAHOO.widget.TextNode(myobj, root, false);

   tree.draw();
}

The HTML for the TreeView component includes a link (<a href="...">) with the contents of the href property.

Responding to Events

The TreeView component supports event callbacks for when a node is expanded or collapsed. The callback function gets a reference to the node that was expanded/collapsed, and that callback can be used to dynamically alter the presentation of the node.

var tree;
function treeInit() {
   tree = new YAHOO.widget.TreeView("treeDiv1");

   var root = tree.getRoot();

   var myobj = { label: "mylabel1", id:"myid1" } ;
   var tmpNode = new YAHOO.widget.TextNode(myobj, root, false);

   myobj = { label: "mylabel2", id:"myid2" } ;
   var tmpNode2 = new YAHOO.widget.TextNode(myobj, tmpNode, false);

   myobj = { label: "mylabel3", id:"myid3" } ;
   var tmpNode3 = new YAHOO.widget.TextNode(myobj, tmpNode, false);

   // Expand and collapse happen prior to the actual expand/collapse,
   // and can be used to cancel the operation
   tree.subscribe("expand", function(node) {
          alert(node.data.id + " was expanded");
          // return false; // return false to cancel the expand
       });

   tree.subscribe("collapse", function(node) {
          alert(node.data.id + " was collapsed");
       });

   // Trees with TextNodes will fire an event for when the label is clicked:
   tree.subscribe("labelClick", function(node) {
          alert(node.data.id + " label was clicked");
       });

   tree.draw();
}

Loading your data dynamically

The TreeView component supports dynamic data loading. To enable this feature, you must provide a callback function that populates the child nodes for a given node when that node is expanded for the first time. Dynamic loading can be defined for the entire tree or for individual nodes. The callback function receives a reference to the node that is being expanded and a callback function that must be executed once you are finished creating the child nodes.

var tree;
function treeInit() {
   tree = new YAHOO.widget.TreeView("treeDiv1");
   tree.setDynamicLoad(loadDataForNode);

   var root = tree.getRoot();

   var myobj = { label: "mylabel1", id:"myid1" } ;
   var tmpNode = new YAHOO.widget.TextNode(myobj, root, false);

   myobj = { label: "mylabel2", id:"myid2" } ;
   var tmpNode2 = new YAHOO.widget.TextNode(myobj, tmpNode, false);

   myobj = { label: "mylabel3", id:"myid3" } ;
   var tmpNode3 = new YAHOO.widget.TextNode(myobj, tmpNode, false);

   tree.draw();
}

 function loadDataForNode(node, onCompleteCallback) {
    var id= node.data.id;
    // -- code to get your data, possibly using Connect --
    var tmpNode = new YAHOO.widget.TextNode(id + "label1", node, false);
    tmpNode = new YAHOO.widget.TextNode(id + "label2", node, false);

    // Be sure to notify the TreeView component when the data load is complete
    onCompleteCallback();
 }

Reloading Dynamic Nodes

Dynamically loaded nodes only invoke the data loader the first time they node are expanded. The widget has a utility method that will clear out the node's collection of children and reset the node so that the next time it is expanded it will call the data loader again.

tree.removeChildren(nodeToReset);

Creating Custom Node Types

The TreeView widget provides a number of node types that differ in behavior and presentation:

• YAHOO.widget.TextNode: Provides the default tree presentation. The node label is an anchor tag that will expand/collapse the node by default. It is possible to override this so the a click on the label does soemthing else.
• YAHOO.widget.MenuNode: Similar to TextNode, except two sibling nodes cannot be expanded at once. This lets you create navigation menus that only show the sub-destinations for the current selection.
• YAHOO.widget.HTMLNode: Does not create the anchor tag with default behavior like TextNode does. Instead, it allows you to pass in arbritrary HTML that will be inserted into the node verbatim.

It is also possible to subclass one of these node to provide custom features. Check out the task list example to learn how to do this.

Known Issues

Internet Explorer sometimes has trouble rendering deeply nested nodes (It has been reported that this problem surfaces at about 38 levels deep). A future release will have a different markup pattern that may fix this issue.

YUI on Mobile: Using TreeView Control with "A-Grade" Mobile Browsers

TreeView is functional in the target mobile browsers. However, deeply nested nodes may be will cause horizontal scrolling and may be a sub-optimal user experience.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.