5.3.10.7 TreeIterator Objects

An instance of TreeIterator class (or the sub-classes LazyTreeIterator (5.3.10.8) or EllipsisTreeIterator (5.3.10.9)) will be placed into the execution context using the name specified in the iter (5.3.10.3) attribute. This iterator will contain traversal data for the current node each time the tag content is executed.

Note that it is also acceptable to create an instance of one of the TreeIterator classes prior to rendering the template. The set_selected_aliases() or set_open_aliases() methods can then be used to render the tree with nodes already selected or open.

By using an object to iterate over the tree the toolkit is able to provide additional data that is useful in formatting HTML. The toolkit also places the iterator into the session (you must be using an application class that supports sessions).

value( )
Returns the current node.

tree_depth( )
Returns the depth of the visible tree, from the root to deepest node. A single node tree has a depth of one.

depth( )
Returns the depth of the current node.

span( )
Is shorthand for n.tree_depth() - n.depth(). It is intended to be used for the colspan of the table cell containing the node name when laying the tree out in a table. See the samples/tree/tree2.html template for just such an example.

line( depth)
Only useful when displaying a tree in tabular form where the root is in the first column of the first row. Returns the type of line that should be displayed in each column up to the depth of the current node.

A return value of 0 indicates no line, 1 indicates a line that joins a node later than this node, and 2 indicates a line that terminates at this node.

The example in section 3.12 uses this method.

is_open( )
Returns TRUE if the current node is open. For non-lazy iterators, this is always TRUE except on leaf nodes.

is_selected( )
For non-lazy iterators, this always returns FALSE.

has_children( )
Returns TRUE if the current node has children (ie. it defines a children member).

Most of the methods and all of the members are not meant to be accessed from your code but are documented below to help clarify how the iterator behaves.

_value
Stores a reference to the current tree node -- returned by value().

_stack
As the tree is being traversed this list attribute records all parent nodes between the current node and the root. This is used to determine which branch lines should be drawn for the current node.

_line
Stores the branch line drawing information for the current node. Elements of this list are returned by line(depth).

_tree_depth
Stores the depth of the tree from the root to the deepest visible node. A single node tree has a depth of 1. This is calculated immediately before the tree is displayed. This is returned by tree_depth().

set_line( line)
Saves the line argument in _line.

set_value( node)
Sets the _value to the node argument.

node_is_open( ctx, node)
Called internally whenever the toolkit needs to determine the open state of a tree node. For non-lazy iterators, it returns whether or not the node in the node argument has children (because non-lazy iterators are always open).