⁠Chapter 13. Trees

13.1. <rich:tree>
13.1.1. Basic usage
13.1.2. Appearance
13.1.3. Expanding and collapsing tree nodes
13.1.4. Selecting tree nodes
13.1.5. Identifying nodes with the rowKeyConverter attribute
13.1.6. Event handling
13.1.7. Reference data
13.1.8. Style classes
13.1.9. <rich:treeSelectionChangeListener>
13.1.10. <rich:treeNode>
13.2. Tree adaptors
13.2.1. <rich:treeModelAdaptor>
13.2.2. <rich:treeModelRecursiveAdaptor>
Read this chapter for details on components that use tree structures.

⁠13.1. <rich:tree>

The <rich:tree> component provides a hierarchical tree control. Each <rich:tree> component typically consists of <rich:treeNode> child components. The appearance and behavior of the tree and its nodes can be fully customized.

⁠13.1.1. Basic usage

The <rich:tree> component requires the value attribute to point to the data model for populating the tree. The data model must be either an org.richfaces.model.TreeNode interface, an org.richfaces.model.TreeDataModel interface, or a javax.swing.tree.TreeNode interface. The var attribute declares the variable used for iterating through the data model, so that child <rich:treeNode> components can reference each iteration.
Ideally, the <rich:tree> component needs one or more <rich:treeNode> components to work with the data model. However if no <rich:treeNode> components are provided the tree creates default nodes instead.
⁠

Example 13.1. Basic usage

This example demonstrates basic usage of the <rich:tree> component using an org.richfaces.model.TreeNode data model.
First extend the org.richfaces.model.TreeNodeImpl and add the data fields you require, with appropriate accessor methods, as in: 
​import org.richfaces.model.TreeNodeImpl;
​
​public class DataHolderTreeNodeImpl extends TreeNodeImpl {
​    private Object data;
​
​    public DataHolderTreeNodeImpl() {
​        super();
​    }
​
​    public DataHolderTreeNodeImpl(boolean leaf, Object data) {
​        super(leaf);
​        this.data = data;
​    }
​
​    public Object getData() {
​        return data;
​    }
​
​    @Override
​    public String toString() {
​        return super.toString() + " >> " + data;
​    }
​}
Then, the data model is constructed as follows: 
​private DataHolderTreeNodeImpl stationRoot;
​private DataHolderTreeNodeImpl rootNodes;
​
​public DataHolderTreeNodeImpl getRootNodes() {
​    if (rootNodes == null) {
​        String[] kickRadioFeed = {"Hall & Oates - Kiss On My List",
​                "David Bowie - Let's Dance",
​                "Lyn Collins - Think (About It)",
​                "Kim Carnes - Bette Davis Eyes",
​                "KC & the Sunshine Band - Give It Up"};
​        stationRoot = new DataHolderTreeNodeImpl(false, "KickRadio");
​        for (int i = 0; i<kickRadioFeed.length; i++) {
​            DataHolderTreeNodeImpl child = new DataHolderTreeNodeImpl(true, kickRadioFeed[i]);
​            stationRoot.addChild(i, child);
​        }
​        rootNodes = new DataHolderTreeNodeImpl();
​        rootNodes.addChild(0, stationRoot);
​    }
​    return rootNodes;
​}
The tree then accesses the nodes of the model using the station variable: 
​<rich:tree value="#{stations.stationNodes}" var="station">
​   <rich:treeNode>
​      <h:outputText value="#{station}" />
​   </rich:treeNode>
​</rich:tree>

⁠13.1.2. Appearance

Different nodes in the tree can have different appearances, such as node icons, depending on the type of data the node contains. Use the nodeType attribute to differentiate the types of nodes; the node is then rendered according to the <rich:treeNode> component with the corresponding type attribute. Example 13.2, “nodeType attribute” shows a <rich:tree> component with three different child <rich:treeNode> components defined to represent three different node appearances. Refer to Section 13.1.10.2, “Appearance” for details on customizing the appearance of <rich:treeNode> components.
⁠

Example 13.2. nodeType attribute

​<rich:tree style="width:300px" value="#{library.data}" var="item" nodeType="#{item.type}">
​   <rich:treeNode type="artist" iconExpanded="/images/tree/singer.png" iconCollapsed="/images/tree/singer.png">
​      <h:outputText value="#{item.name}" />
​   </rich:treeNode>
​   <rich:treeNode type="album" iconExpanded="/images/tree/disc.png" iconCollapsed="/images/tree/disc.png">
​      <h:outputText value="#{item.album}" />
​   </rich:treeNode>
​   <rich:treeNode type="song" iconLeaf="/images/tree/song.png">
​      <h:outputText value="#{item.title}" />
​   </rich:treeNode>
​</rich:tree>
If the nodeType attribute returns null, the node is rendered as a "typeless" (or default) node. The typeless node is the first child <rich:treeNode> component with a valid rendered attribute, but without a defined type attribute.
If the nodeType attribute is not included and there are no child <rich:treeNode> components, the tree constructs a default node itself.
Icons for different nodes and node states can be defined for the whole tree using the following attributes:
iconLeaf
The iconLeaf attribute points to the icon to use for any node that does not contain any child nodes.
iconExpanded and iconCollapsed
The iconExpanded and iconCollapsed attributes point to the icons to use for expanded and collapsed nodes respectively. If these attributes are defined, the icon attribute is not used.

⁠13.1.3. Expanding and collapsing tree nodes

The mode for performing submissions when nodes are expanded or collapsed is determined by the toggleType attribute, which can have one of the following three values:
ajax
This is the default setting. The <rich:tree> component performs an Ajax form submission, and only the content of the tree is rendered.
server
The <rich:tree> component performs a common submission, completely refreshing the page.
client
The <rich:tree> component updates on the client side through JavaScript, without any additional requests or updates. All nodes are rendered to the client during the initial page rendering.
By default, tree nodes are expanded and collapsed through the + and - controls. To expand or collapse a tree node using an action event such as a mouse click, specify the event with the toggleNodeEvent attribute.

⁠13.1.4. Selecting tree nodes

The mode for performing submissions when nodes are selected is determined by the selectionType attribute, which can have one of the following three values:
ajax
This is the default setting. The <rich:tree> component performs an Ajax form submission, and only the content of the tree is rendered.
client
The <rich:tree> component updates on the client side using JavaScript, without any additional requests or updates.

⁠13.1.5. Identifying nodes with the rowKeyConverter attribute

If the <rich:tree> component uses a custom data model, the data model provides unique keys for tree nodes so they can be identified during a client request. The <rich:tree> component can use strings as key values. These strings may contain special characters that are not allowed by browsers, such as the left angle bracket (<) and ampersand (&). To allow these characters in the keys, a row key converter must be provided.
To apply a converter to the <rich:tree> component, define it with the rowKeyConverter attribute.

⁠13.1.6. Event handling

In addition to the standard Ajax events and HMTL events, the <rich:tree> component uses the following client-side events:
  • The nodetoggle event is triggered when a node is expanded or collapsed.
  • The beforenodetoggle event is triggered before a node is expanded or collapsed.
  • The selectionchange event is triggered when a node is selected.
  • The beforeselectionchange event is triggered before a node is selected.
The <rich:tree> component uses the following server-side listeners:
  • The toggleListener listener processes expand and collapse events.
  • The selectionChangeListener listener processes the request when a node is selected.

⁠13.1.7. Reference data

  • component-type: org.richfaces.Tree
  • component-class: org.richfaces.component.UItree
  • component-family: org.richfaces.Tree
  • renderer-type: org.richfaces.TreeRenderer
  • handler-class: org.richfaces.view.facelets.TreeHandler

⁠13.1.8. Style classes

Styling for the <rich:tree> component is mostly applied to the tree nodes. Refer to Section 13.1.10.5, “Style classes and skin parameters” for details on styling tree nodes. In addition, the <rich:tree> component can make use of the style classes outlined in Style classes (selectors).
⁠

Style classes (selectors)

.rf-tr-nd
This class defines styles for the nodes in a tree.
.rf-tr-nd-last
This class defines styles for last node in a tree.
.rf-tr-nd-colps
This class defines styles for a collapsed tree node.
.rf-tr-nd-exp
This class defines styles for an expanded tree node.

⁠13.1.9. <rich:treeSelectionChangeListener>

Use the <rich:treeSelectionChangeListener> tag to register a TreeSelectionChangeListener class on a parent <rich:tree> component. The class provided as a listener must implement the org.richfaces.event.TreeSelectionChangeListener interface. The processTreeSelectionChange method accepts an org.richface.event.TreeSelectionChangeEvent event as a parameter.

⁠13.1.10. <rich:treeNode>

The <rich:treeNode> component is a child component of the <rich:tree> component. It represents nodes in the parent tree. The appearance and functionality of each tree node can be customized.

⁠13.1.10.1. Basic usage

The <rich:treeNode> component must be a child of a <rich:tree> component or a tree adaptor component. It does not need any attributes declared for basic usage, but can provide markup templates for tree nodes of particular types. Default markup is used if the tree node type is not specified. Refer to Example 13.1, “Basic usage” for an example of basic <rich:treeNode> component usage.
⁠

Example 13.3. Basic usage

​<rich:tree nodeType="#{node.type}" var="node"
​           value="#{treeBean.rootNodes}">
​   <rich:treeNode type="country">
​      #{node.name}
​   </rich:treeNode>
​   <rich:treeNode type="state">
​      #{node.name}
​   </rich:treeNode>
​   <rich:treeNode type="city">
​      #{node.name}
​   </rich:treeNode>
​</rich:tree>
The example renders a simple tree of countries. Each country node expands to show state nodes for that country, and each state node expands to show city nodes for that state.

⁠13.1.10.2. Appearance

Refer to Section 13.1.2, “Appearance” for the <rich:tree> component for details and examples on styling nodes and icons. Icon styling for individual <rich:treeNode> components uses the same attributes as the parent <rich:tree> component: iconLeaf, iconExpanded, and iconCollapsed. Icon-related attributes specified for child <rich:treeNode> components overwrite any global icon attributes of the parent <rich:tree> component.
Use the rendered attribute to determine whether the node should actually be rendered in the tree or not. Using the rendered attribute in combination with the <rich:treeNode> type attribute can allow further style differentiation between node content.

⁠13.1.10.3. Interactivity

Interactivity with individual nodes, such as expanding, collapsing, and other event handling, can be managed by the parent <rich:tree> component. Refer to Section 13.1.3, “Expanding and collapsing tree nodes” and Section 13.1.6, “Event handling” for further details.
Use the expanded attribute to determine whether the node is expanded or collapsed.

⁠13.1.10.4. Reference data

  • component-type: org.richfaces.TreeNode
  • component-class: org.richfaces.component.UITreeNode
  • component-family: org.richfaces.TreeNode
  • renderer-type: org.richfaces.TreeNodeRenderer
  • handler-class: org.richfaces.view.facelets.TreeNodeHandler

⁠13.1.10.5. Style classes and skin parameters

⁠

Table 13.1. Style classes (selectors) and corresponding skin parameters

Class (selector) Skin Parameters Mapped CSS properties
.rf-trn
This class defines styles for a tree node.
generalFamilyFont
font-family
generalSizeFont
font-size
.rf-trn-lbl
This class defines styles for a tree node label.
No skin parameters.
.rf-trn-cnt
This class defines styles for tree node content.
No skin parameters.
.rf-trn-sel
This class defines styles for a selected tree node.
additionalBackgroundColor
background
.rf-trn-ldn
This class defines styles for a tree node when it is loading.
additionalBackgroundColor
background
.rf-trn-hnd
This class defines styles for a tree node handle.
No skin parameters.
.rf-trn-hnd-lf
This class defines styles for the handle of a leaf node.
No skin parameters.
.rf-trn-hnd-colps
This class defines styles for the handle of a collapsed node.
No skin parameters.
.rf-trn-hnd-exp
This class defines styles for the handle of an expanded node.
No skin parameters.
.rf-trn-hnd-ldn-fct
This class defines styles for the loading facet of a tree node handle.
No skin parameters.
.rf-trn-ico
This class defines styles for tree node icon.
No skin parameters.
.rf-trn-ico-lf
This class defines styles for the icon of a leaf node.
No skin parameters.
.rf-trn-ico-colps
This class defines styles for the icon of a collapsed node.
No skin parameters.
.rf-trn-ico-exp
This class defines styles for the icon of an expanded node.
No skin parameters.
.rf-trn-ico-cst
This class defines styles for a custom node icon.
No skin parameters.

⁠13.1.10.6. <rich:treeToggleListener>

Use the <rich:treeToggleListener> tag to register a TreeToggleListener class on a parent <rich:treeNode> component. The class provided as a listener must implement the org.richfaces.event.TreeToggleListener interface. The processTreeToggle method accepts an org.richface.event.TreeToggleEvent event as a parameter.