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()
.