JBoss.orgCommunity Documentation

Chapter 12. Trees

12.1. <rich:tree>
12.1.1. Basic usage
12.1.2. Appearance
12.1.3. Expanding and collapsing tree nodes
12.1.4. Selecting tree nodes
12.1.5. Identifying nodes
12.1.6. Event handling
12.1.7. Reference data
12.1.8. <rich:treeNode>
12.2. Tree adaptors
12.2.1. <rich:treeModelAdaptor>
12.2.2. <rich:treeModelRecursiveAdaptor>

Documentation in development

Some concepts covered in this chapter may refer to the previous version of Richfaces, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date.

Read this chapter for details on components that use tree structures.

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.

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.


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 12.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 12.1.8.2, “Appearance” for details on customizing the appearance of <rich:treeNode> components.


Alternatively, use Expression Language (EL) with the nodeType attribute, as shown in Example 12.3, “nodeType attribute with Expression Language”.


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.

The <rich:tree> component uses a data model to represent the node structure on the page. To identify a particular node during a client request, the model provides unique keys for tree nodes. 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, the following converter is provided:

To apply a converter to the <rich:tree> component, define it with the rowKeyConverter attribute. Example 12.4, “Identifying nodes” demonstrates the use of a converter to identify tree nodes.


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.

Refer to Section 12.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, as shown in Example 12.5, “rendered attribute”.


Use a tree adaptor to create a tree and populate it with data from a defined data model.

The <rich:treeModelAdaptor> component takes a defined data model and uses it to populate an associated <rich:tree> component.

<rich:treeModelAdaptor> components can further be nested in other <rich:treeModelAdaptor> components to subsequently populate lower levels of the tree.

Use the var attribute to access the current collection element at each level. Example 12.6, “Nested <rich:treeModelAdaptor> components” demonstrates a series of nested <rich:treeModelAdaptor> components, each using the parent's var attribute to reference the current element.


The <rich:treeModelRecursiveAdaptor> component recursively populates a tree with hierarchical nodes, such as for a file system with multiple levels of directories and files.

The <rich:treeModelRecursiveAdaptor> component is an extension of the <rich:treeModelAdaptor> component. As such, the <rich:treeModelRecursiveAdaptor> component uses all of the same attributes. Refer to Section 12.2.1, “<rich:treeModelAdaptor>” for details on the <rich:treeModelAdaptor> component.

In addition, the <rich:treeModelRecursiveAdaptor> component requires the root attribute. The root attribute defines the collection to use at the top of the recursion. For subsequent levels, the node attribute is used for the collection.

Example 12.7, “Basic usage” demonstrates how the <rich:treeModelRecursiveAdaptor> component can be used in conjunction with the <rich:treeModelAdaptor> component to recursively iterate through a file system and create a tree of directories and files.