Validation and Special Instructions

The advancedTree component can be instructed to behave a certain way for certain nodes through a special string formatted as XML and referenced by the component in its validator property. Instructions include which nodes can be dragged, where nodes can be dropped or whether a node is editable, closable or even visible.

The string used as the validator must be structured as valid XML (the advancedTree internally converts this to XML), with the structure representing the structure of your desired tree.

NOTE: These special instructions are designed to be used when the user is interacting with the tree. Any commands issued through ActionScript are not validated through this facility.

To use a validator string, create a string formatted as valid XML representing the structure of your tree. For instance, if your tree will always have a root node with the nodename "website", first level nodes with the nodename "section" and second level nodes with the nodename "page", the validator string would look like:

var validatorStr:String = "";
validatorStr += "<website>";
validatorStr +=   "<section>";
validatorStr +=     "<page />";
validatorStr +=   "</section>";
validatorStr += "</website>";

This string simply signifies that the root node will ALWAYS be website and it will hold section nodes. section nodes, in turn, will hold page nodes. It's important to understand that each node in this validator string represents a node type, not specific nodes. ANY node with a nodename of "section" will abide by the rules specified in the section node of this structure.

To use the validator string to validate any dragging and dropping internally in the tree, first set the component's draggable property to true to enable drag and drop and set the component's validator property to be the name of the validator string.

tree.draggable = true;
tree.validator = "validatorStr";

NOTE: the validator property takes the name of the validator string, not the validator string itself.

With the validator set up for the component, the tree will ONLY allow section nodes to be dropped into website and will ONLY allow page nodes to be dropped into section nodes. Any other drop will be considered invalid and prevented.

If you would like to enable sections to be inside other sections, you would alter the validator string as follows:

var validatorStr:String = "";
validatorStr += "<website>";
validatorStr +=   "<section>";
validatorStr +=     "<section>";
validatorStr +=       "<page />";
validatorStr +=     "</section>";
validatorStr +=     "<page />";
validatorStr +=   "</section>";
validatorStr += "</website>";

Now we have enabled sections to be both inside the website node or any other section node. page nodes still can only reside within section nodes.

By default, the root node of a tree is not movable, even when the component is set to be draggable. You can set other nodes to be immovable as well. This is done by setting the attribute "immovable" to a node type inside the validator string. Consider in the following that a new node type has been added to the tree that we have specified may NOT be dragged.

Another attribute that may be added to a node type is "unique", which specifies whether more than one node of the same type may exist within the same parent. In our example, we may wish to prevent another sitemap node from being dragged to the root.

You may also specify through the validator string whether a node can be closed once it has been opened. For instance, in our example, once the website node is opened we may wish for it to remain open.

var validatorStr:String = "";
validatorStr += "<website unclosable="true" >";
validatorStr +=   "<section>";
validatorStr +=     "<section>";
validatorStr +=       "<page />";
validatorStr +=     "</section>";
validatorStr +=     "<page />";
validatorStr +=   "</section>";
validatorStr +=   "<sitemap immovable="true" unique="true" />";
validatorStr += "</website>";

In the same way, nodes can be set to be editable or not (only when the component's editable property is set to true). This would prevent a user from being able to change the displayed name of a node. In the following example, the website, sitemap and section nodes may NOT be editable, though the page nodes may be.

var validatorStr:String = "";
validatorStr += "<website unclosable="true" uneditable="true" >";
validatorStr +=   "<section uneditable="true" >";
validatorStr +=     "<section uneditable="true" >";
validatorStr +=       "<page />";
validatorStr +=     "</section>";
validatorStr +=     "<page />";
validatorStr +=   "</section>";
validatorStr +=   "<sitemap immovable="true" unique="true" uneditable="true" />";
validatorStr += "</website>";

The last attribute that may be set for a node type is "invisible", which determines whether the node will be visible when the component is rendered. Though this may seem an odd instruction, it becomes useful if the XML used to populate the tree contains additional data you do not want displayed to the user. In the following example, a user node is present in the tree, but made invisible.

var validatorStr:String = "";
validatorStr += "<website unclosable="true" uneditable="true" >";
validatorStr +=   "<user invisible="true" />";
validatorStr +=   "<section uneditable="true" >";
validatorStr +=     "<section uneditable="true" >";
validatorStr +=       "<page />";
validatorStr +=     "</section>";
validatorStr +=     "<page />";
validatorStr +=   "</section>";
validatorStr +=   "<sitemap immovable="true" unique="true" uneditable="true" />";
validatorStr += "</website>";