Trinidad
Foundation
Modules
Project Documentation

Using the Apache Trinidad Tree Component

Introduction

Apache Trinidad tree components are used to display hierarchical data. For example, if we have a personnel organization chart depicting all the direct reports under each employee, we could use a tree component to display this chart. Each element (employee) in the hierarchy may have any number of child elements (direct reports). In addition several parent elements may share the same child elements. Apache Trinidad currently provides two tree components: Tree and TreeTable. The Apache Trinidad Tree component supports multiple root elements, and it has a simple user interface (UI) - each element in the Tree is appropriately indented to indicate its level in the hierarchy, and is connected to its parent. The features of the Tree component include mechanisms for expanding and collapsing portions of the hierarchy. The Apache Trinidad TreeTable component displays a hierarchy in a UI similar to an Apache Trinidad Table, and is more elaborate than the Tree component. TreeTable supports displaying columns of data per element in the hierarchy. The features of the TreeTable component include mechanisms for focusing in on subtrees (within the main tree), as well as expanding and collapsing elements in the hierarchy. We recommend that you familiarize yourself with the Table component before reading the rest of this chapter.

The Tree Model

The Apache Trinidad tree components use a model to access the data in the underlying hierarchy. The specific model class is org.apache.myfaces.trinidad.model.TreeModel. TreeModel extends CollectionModel (see Using Apache Trinidad Tables for more information about the CollectionModel). In other words, the TreeModel is a collection of rows. It has an isContainer method that returns true if the current row contains child rows. The children of the current row can be accessed by calling the enterContainer method. Once this method is called the TreeModel instance will change to be a collection of the child rows. To jump back up to the parent collection, call the exitContainer method. You may find the org.apache.myfaces.trinidad.model.ChildPropertyTreeModel class useful when constructing a TreeModel.

Tree

The Tree component displays a multi-root hierarchy in a simple UI where each element in the hierarchy is indented relative to the corresponding parent element.

Data

The Tree uses a stamping strategy similar to the Apache Trinidad Table component. The "nodeStamp" facet of the Tree is used to display the data for each element in the tree. The Tree does not create components per element; instead, the "nodeStamp" is repeatedly rendered (stamped) once per element. Because of this stamping behavior, only certain types of components are supported as children inside a Tree. Supported components include all components with no behavior and most components that implement the ValueHolder or ActionSource interfaces. Each time the "nodeStamp" is stamped, the data for the current element (see getRowData() in Using Apache Trinidad Tables) is copied into an EL reachable property. The name of this property is defined by the var property on the Tree. Once the Tree has completed rendering, this property is removed (or reverted back to its previous value). In the following example, the data for each element is placed under the EL property "node". The "nodeStamp" displays the data for each element by getting further properties from the "node" property: 
<tr:tree var="node">
  <f:facet name="nodeStamp">
    <tr:outputText value="#{node.firstname}"/>
  </f:facet>
</tr:tree>

RowDisclosureEvent

The Tree renders expand/collapse icons that the user can click on to expand or collapse a subtree. When these icons are clicked, the Tree generates a RowDisclosureEvent. This event has two RowKeySet objects. One, called RemovedSet, for all the collapsed nodes and one, called AddedSet, for all the expanded nodes. The Tree expands the subtrees under all nodes in the added set and collapses the subtrees under all nodes in the removed set.

You can register custom RowDisclosureListener instances (that can do post processing) on the Tree component.

SelectionEvent

The Tree supports a rowSelection attribute. Valid values for the rowSelection attribute are: single, multiple, and none. If a Tree is selectable, clicking on a node causes the tree to highlight the node and render it as selected. ctrl-click and shift-click operations are supported for trees which support multiple selections. When nodes are selected/unselected, the Tree fires a SelectionEvent . This event has two RowKeySet objects. One, called RemovedSet, for all the unselected nodes and one, called AddedSet, for all the selected nodes.

You can register custom SelectionListener instances (that can do post processing) on the Tree component.

TreeTable

The TreeTable component displays a hierarchy in a UI similar to Table. Like the Table, the TreeTable's children must be Apache Trinidad Column components (Please see Table Columns). Like the Tree, the TreeTable has a "nodeStamp" facet which renders the "Object Name" Column. The TreeTable has a "pathStamp" facet for rendering the focus path. The "Object Name" Column contains the primary identifier of an element in the hierarchy. For example, in an organization chart of employees, the "Object Name" Column might be the employee name. The TreeTable supports the same stamping behavior as the Tree component. In the following example, The "Object Name" Column is the "Employee Name" Column. For each element (that is, employee) the TreeTable stamps out the name, ID and the department. 
<tr:treeTable var="node">
  <f:facet name="nodeStamp">
    <tr:column>
      <f:facet name="header">
        <tr:outputText value="Employee Name"/>
      </f:facet>
      <tr:outputText value="#{node.ename}"/>
    </tr:column>
  </f:facet>
  <f:facet name="pathStamp">
    <tr:outputText value="#{node.ename}"/>
  </f:facet>
  <tr:column>
    <f:facet name="header">
      <tr:outputText value="Employee Id"/>
    </f:facet>
    <tr:outputText value="#{node.empid}"/>
  </tr:column>
  <tr:column>
    <f:facet name="header">
      <tr:outputText value="Department"/>
    </f:facet>
    <tr:outputText value="#{node.dname}"/>
  </tr:column>
</tr:treeTable>
The TreeTable supports all the formatting properties that are supported by the Column component. Please see Using Apache Trinidad Tables for more information about the Apache Trinidad Column component.

FocusEvent

In addition to displaying expand/collapse icons, the TreeTable also renders a column containing "focus" icons that a user can click to focus on (or zoom into) a particular element's subtree of children.

To focus (or zoom) out of a subtree, the user can click on path links that are rendered above the TreeTable. These path links are rendered by the "pathStamp" facet. If this facet is not provided the focus column and the path links are not rendered.

The TreeTable has a "focusPath" property that controls which element has the current focus. This property is a java.util.List of row-keys that describe a path from the root to the element that has the focus. When the user focuses in or out, the TreeTable generates a FocusEvent. The element that the user focused in, is made current before the event is delievered. The TreeTable responds to this event by modifying the "focusPath" property appropriately. Subsequently, any registered FocusListener instances are called.

DisclosureAllEvent

The TreeTable allows the user to expand or collapse all the subtrees by clicking on special "expand-all" or "collapse-all" links. In response to this, the TreeTable generates a DisclosureAllEvent. This event has an isExpandAll method that returns whether the user wants to show or hide all the subtrees. The TreeTable responds to this by expanding or collapsing all the elements under the current focus root. If the tree is massive, the expand-all operation will not propagate beyond the children of the current focus root.

RowDisclosureEvent - TreeTable

Like the Tree component the TreeTable generates a RowDisclosureEvent. Please see the Tree's RowDisclosureEvent description for more information about this event.

SelectionEvent - TreeTable

Like the Tree component the TreeTable generates a SelectionEvent. Please see the Tree's SelectionEvent description for more information about this event.

Expand/Collapse State

The Apache Trinidad tree components use an instance of the org.apache.myfaces.trinidad.model.RowKeySet class to keep track of which elements are expanded. This instance is stored as the "disclosedRowKeys" attribute on the component. You may use this instance to programmatically control the expand/collapse state of an element in the hierarchy. Any element contained by the RowKeySet instance is deemed expanded. All other elements are collapsed. This class also supports operations like addAll() and removeAll().

Selection State

The Apache Trinidad tree components use an instance of the org.apache.myfaces.trinidad.model.RowKeySet class to keep track of which elements are selected. This instance is stored as the "selectedRowKeys" attribute on the component. You may use this instance to programmatically control the selection state of an element in the hierarchy. Any element contained by the RowKeySet instance is deemed selected. All other elements are not selected. This class also supports operations like addAll() and removeAll().

Grid Lines and Banding

Like the Table component, the TreeTable component supports vertical and horizontal grid lines and banding. Please see Table Grid Lines and Banding for more information.