5.3.11.7 TreeIterator Objects

###
5.3.11.7 TreeIterator Objects

An instance of `TreeIterator` class (or the sub-classes `LazyTreeIterator` (5.3.11.8) or `EllipsisTreeIterator` (5.3.11.9)) will be placed into the execution context using the name specified in the `iter` (5.3.11.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).