Validation and Special Instructions

The AdvancedTree component can be instructed to behave a certain way for certain nodes through a special XML document 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 validator must be valid 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.

1. To use a validator string, create an instance of 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 XML would look like:

var validator:XML = <website>
  <section>
    <page />
  </section>
</website>;


This XML 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.

2. To use the validator to validate any dragging and dropping internally in the tree, first set the component's draggable and internalDropEnabled properties to true to enable drag and drop and set the component's validator property to be your validator XML.

tree.draggable = true;
tree.internalDropEnabled = true;
tree.validator = validator;


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.

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

var validator:XML = <website>
  <section>
    <section>
      <page />
    </section>
    <page />
  </section>
</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.

4. You can also set nodes to be immovable as well when a tree is drag-enabled. This is done by setting the attribute "immovable" to a node type inside the validator. Consider in the following that a new node type has been added to the tree that we have specified may NOT be dragged.

var validator:XML = <website>
  <section>
    <section>
      <page />
    </section>
    <page />
  </section>
  <sitemap immovable="true" />
</website>;


5. 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.

var validator:XML = <website>
  <section>
    <section>
      <page />
    </section>
    <page />
  </section>
  <sitemap immovable="true" unique="true" />
</website>;


6. You may also specify through the validator 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 validator:XML = <website unclosable="true">
  <section>
    <section>
      <page />
    </section>
    <page />
  </section>
  <sitemap immovable="true" unique="true" />
</website>;


7. In the same way, nodes can be set to be editable or not (only when the component's editable property is also 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 validator:XML = <website unclosable="true" uneditable="true">
  <section uneditable="true">
    <section uneditable="true">
      <page />
    </section>
    <page />
  </section>
  <sitemap immovable="true" unique="true" uneditable="true" />
</website>;


8. By default, nodes on the tree only render branch icons if they contain child nodes or have been explicitly set to be branches through the branch property of TreeNode. With the attribute "alwaysBranch" in the validator XML, though, you can specify this as a special instruction, as in the following which specifies that sections will always be branches.

var validator:XML = <website unclosable="true" uneditable="true">
  <section uneditable="true" alwaysBranch="true">
    <section uneditable="true" alwaysBranch="true">
      <page />
    </section>
    <page />
  </section>
  <sitemap immovable="true" unique="true" uneditable="true" />
</website>;


9. 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 validator:XML = <website unclosable="true" uneditable="true">
  <user invisible="true" />
  <section uneditable="true" alwaysBranch="true">
    <section uneditable="true" alwaysBranch="true">
      <page />
    </section>
    <page />
  </section>
  <sitemap immovable="true" unique="true" uneditable="true" />
</website>;