Formatting XML for the Tree component

The Tree component is designed to display hierarchical data structures using XML as the data model. It is important to understand the relationship of the XML data source to the Tree component.

<node>
  <node label="Mail">
       <node label="INBOX"/>
       <node label="Personal Folder">
           <node label="Business" isBranch="true" />
           <node label="Demo" isBranch="true" /> 
           <node label="Personal" isBranch="true" /> 
           <node label="Saved Mail" isBranch="true" /> 
           <node label="bar" isBranch="true" />
       </node>
       <node label="Sent" isBranch="true" />
       <node label="Trash"/>
  </node>
</node>

Nodes in the XML data source can have any name. Notice in the previous example that each node is named with the generic name node. The tree reads through the XML and builds the display hierarchy according to the nested relationship of the nodes.

Each XML node can be displayed as one of two types in the tree: branch or leaf. Branch nodes can contain multiple child nodes and appear as a folder icon with an expander arrow that allows users to open and close the folder. Leaf nodes appear as a file icon and cannot contain child nodes. Both leaves and branches can be roots; a root node appears at the top level of the tree and has no parent. The icons are customizable; for more information, see Using skins with the Tree component.

There are many ways to structure XML, but the Tree component cannot use all types of XML structures. Do not nest node attributes in a child node; each node should contain all its necessary attributes. Also, the attributes of each node should be consistent to be useful. For example, to describe a mailbox structure with a Tree component, use the same attributes on each node (message, data, time, attachments, and so on). This lets the tree know what it expects to render, and lets you loop through the hierarchy to compare data.

When a Tree displays a node, it uses the label attribute of the node by default as the text label. If any other attributes exist, they become additional properties of the node's attributes within the tree.

The actual root node is interpreted as the Tree component itself. This means that the first child (in the previous example, <node label="Mail">), is rendered as the root node in the tree view. This means that a tree can have multiple root folders. In the example, there is only one root folder displayed in the tree: Mail. However, if you were to add sibling nodes at that level in the XML, multiple root nodes would be displayed in the tree.

A data provider for a tree always wants a node that has children it can display. It displays the first child of the XMLNode object. When the XML is wrapped in an XML object, the structure looks like the following:

<XMLDocumentObject>
    <node>
        <node label="Mail">
            <node label="INBOX"/>
            <node label="Personal Folder">
                <node label="Business" isBranch="true" />
                <node label="Demo" isBranch="true" /> 
                <node label="Personal" isBranch="true" /> 
                <node label="Saved Mail" isBranch="true" /> 
                <node label="bar" isBranch="true" />
            </node>
            <node label="Sent" isBranch="true" />
            <node label="Trash"/>
        </node>
    </node>
</XMLDocumentObject>

Flash Player wraps the XML nodes in an extra document node, which is passed to the tree. When the tree tries to display the XML, it tries to display <node>, which doesn't have a label, so it doesn't display correctly.

To avoid this problem, the data provider for the Tree component should point at the XMLDocumentObject's first child, as shown here:

myTree.dataProvider = myXML.firstChild;