Getting Started

The dndTree component is very easy to setup. In fact we can do it simply in 5 minutes.

The Tree is designed to layout information in a heirarchial structure. It can use XML data natively to display parent and child nodes relationships. This relationship between a parent node and a child node comes from Family Tree terminology. You could also describe this Parent / Child relationship as a Branch and Leaf relationship or more commonly Folder and File relationship. These terms and methaphors can be used interchangably.

In an XML object the individual parts that make up the whole XML structure are called nodes. The first item in an XML object is called the Root node. The nodes that stem off of the root node are called Leaf nodes or Branch nodes. The difference between a leaf node and a branch node is that leaf nodes contain no nodes inside of them. These are also called Singletons. Branch nodes are nodes that contain nodes inside of them. Nodes contained inside of a branch node are child nodes of that branch. The dndTree uses this parent / child relationship to layout and display the XML structure. The dndTree.dataProvider is an XML object with a additional Tree specific methods and properties.

Using some of the built in methods of the Tree we can easily display heirarchial data: 

// create a new XML object and assign it to the dataProvider
theTree.dataProvider = new XML();
// use addTreeNode to add a node to the tree. the addTreeNode method is part of every xml node
// if you call the method from the tree reference it will add it to the root
var rootNode:XMLNode = theTree.addTreeNode("Root");
// add tree node to the root node
rootNode.addTreeNode("Child 1");
rootNode.addTreeNode("Child 2");
// if we did not add nodes to the root node the node would be a leaf node
// since we did the root node becomes a branch nodes and we are 
// going to open it to show the child nodes
theTree.setIsOpen(rootNode, true);

Using that code the Tree will look like this:

We can get the listen for the singleClick or the change event and get the selected node by checking the selectedNode property. 

// Change Event
var nodeSelectListener = new Object()
nodeSelectListener.change = function(evt) {
	// trace when a node is clicked
	var selectedNode = evt.target.selectedNode;
	trace("You selected " + selectedNode.attributes.label);
}
theTree.addEventListener("change", nodeSelectListener);

The more typical way to display data in the Tree is to load in an XML file rather than add nodes by hand.

ActionScript:

// Define an XML object and load in an external xml file
xmlObject = new XML();
xmlObject.ignoreWhite = true;



// load data into Tree
xmlObject.load("testdata.xml");

// when the xmlObject has loaded the xml file assign it to the tree dataprovider
xmlObject.onLoad = function() {
	
	theTree.dataProvider = xmlObject;
	theTree.setIsOpen(theTree.getTreeNodeAt(0), true);
}

XML File :

Will cause the Tree to look like this:


After you set up the source of the Tree content you may want to change the label of the nodes. All nodes have an attribute object. This object contains all the attributes that a node contains. In the xml in the example each node has a label attribute. By default the Tree uses the label attribute as text in the Tree. If you want to change where the label text comes from you can change the labelField property or use the labelFunction function. 

//set the label to use 
theTree.labelFunction = function(theNode) {
	// this label function checks if a label attribute exists
	// if a label exists we indicate what type of node it is
	var label = theNode.attributes.label;
	var nodeType = (theTree.getIsBranch(theNode)) ? "Branch" : "Leaf";

	if (label != undefined && label!="") {
		return label + " (" + nodeType + ")";
	}
	else {
		return "No Label Defined";
	}
}

Here is the Tree using our labelFunction:


One of common feature in Tree controls is the rename or edit ability. The dndTree has this built in. You double click on the label and an edit field or rename field appears. You can also use the context menu and select "Rename Item". You can restrict the text entered in, validate it, call it manually, disable it for certain nodes, disable it from appearing on double clicks or disable it completely.

It is common to want to show custom images, icons or movieclips in a Tree. For images you want to use as icons that will exist in the library use the iconFunction. It is better to use the iconFunction to set icons then load them in externally. See the icon example that is included. For loading in images from outside the swf we must use a cell renderer. A cell renderer gives you the ability to design the look and feel of the Tree cell. A cell is the column space inside the row of the Tree. You are able to layout and position the elements in the cell by attaching movieclips or components with ActionScript code. For dynamically loading in external images a cellrenderer has been made for you. See dynamic images example.

Dynamic external images example:

dynamic

We can make an working Tree file in 5 minutes like the ones described above,

  1. Create a new project and drag the dndTree component to the stage and give it the instance name "theTree".
  2. Save the file as TreeExample.fla
  3. Now go into the actions panel on frame 1. Do not go into the actions for the dndTree but for the frame.
Type in this code:
theTree.dataProvider = new XML();
var rootNode = theTree.addTreeNode("Root");
rootNode.addTreeNode("Child 1");
rootNode.addTreeNode("Child 2");
theTree.setIsOpen(rootNode, true);

Test the movie. Try dragging and dropping. Try double-clicking on a item's label. There is a similar finished example of this tutorial in the examples folder.

The dndTree has many more features and benefits. Many examples are included and the help documentation provides numerous code examples.

More information is available on the dndTree online at http://www.drumbeatinsight.com/examples/dndTree/index.html. It is extended off the Macromedia Tree component and inherits all of it features. You can also learn and follow any Macromedia Tree example.

Documentation for these classes are included within the Macromedia Flash Help Panel.

Numerous examples have been included and will show you how to do the following:

It also comes with drag and drop classes. These allow you to drag and drop a movieclip onto a dndTree and insert new items to the Tree. You can also use these classes to drag and drop a movieclip onto another movieclip and generate events. View the "drag & drop from a movieclip to a Tree" example to see this process in action.

© Drumbeat Insight 2006