Introduction
ADF Faces 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.
ADF Faces currently provides two tree components: Tree and TreeTable.
The ADF 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 ADF TreeTable component displays a hierarchy
in a U
I similar to an ADF Table, and is more elaborate than the Tree component. TreeTable supports displaying columns of data per element in the hierarchy. Unlike the Tree component, TreeTable
only supports single rooted hierarchies. 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 ADF tree components use a model to access the data in the
underlying hierarchy. The specific model class is
oracle.adf.view.faces.model.TreeModel
.
TreeModel
extends
CollectionModel
(see
Using ADF Faces 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
oracle.adf.view.faces.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 rendered with a connector to
the cor
responding parent element. This component is not well suited
for massive trees, since it does not support any focusing capability.
Data
The Tree uses a stamping strategy similar to the ADF 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
EditableValueHolder or ActionSource interfaces.
Each time the "nodeStamp" is stamped, the data for the current
element (see
getRowData()
in
Using
ADF Faces 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:
<af:tree var="node">
<f:facet name="nodeStamp">
<af:outputText value="#{node.firstname}"/>
</f:facet>
</af:tree>
DisclosureEvent
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
DisclosureEvent
. This event has a
n
isExpanded
method that returns whether the user wants
to expand or collapse the subtree of a particular element. That
particular element is made current on the Tree before the event is
delivered. The Tree responds to this by expanding or collapsing the
subtree of that element.
You can register custom
DisclosureListener
instances
(that can do post processing) on the Tree component.
TreeTable
The TreeTable component displays a single-root hierarchy in a UI
similar to Table. Like the Table, the TreeTable's children must be ADF
Column components. 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.
<af:treeTable var="node">
<f:facet name="nodeStamp">
<af:column>
<f:facet name="header">
<af:outputText value="Employee Name"/>
</f:facet>
<af:outputText value="#{node.ename}"/>
</af:column>
</f:facet>
<f:facet name="pathStamp">
<af:outputText value="#{node.ename}"/>
</f:facet>
<af:column>
<f:facet name="header">
<af:outputText value="Employee Id"/>
</f:facet>
<af:outputText value="#{node.empid}"/>
</af:column>
<af:column>
<f:facet name="header">
<af:outputText value="Department"/>
</f:facet>
<af:outputText value="#{node.dname}"/>
</af:column>
</af:treeTable>
The TreeTable supports all the formatting properties that are supported by the
Column component. Please see
Using ADF Faces Tables
for more
information about the ADF 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.
RangeChangeEvent
The TreeTable allows the user to page through child record sets by
clicking on special "Next", "Previous" links rendered above and below a large
record set. In response to this, the TreeTable generates a
RangeChangeEvent
. This event has properties that return the
previous range and the new range. The TreeTable responds to this by scrolling
the corresponding record set.
To enable this scrolling behaviour, the "rowsByDepth" property must
be set on the TreeTable. This is a space-separated list of non-negative
numbers. Each number defines the range-size for a particular depth of the
tree. If the tree is deeper than the size of this list, the last number in
the list applies to the rest of the tree. Use "0" for any particular depth
to show everything.
Expand/Collapse State
The ADF tree components use an instance of the
oracle.adf.view.faces.mod
el.PathSet
class to keep track
of which elements are expanded. This instance is stored as the
"treeState" 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
PathSet
instance is deemed expanded. All other elements are collapsed. This
class also supports operations like
addAll()
and
removeAll()
.
Bookmark
