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.
For basic usage, the <rich:tree> component needs one or more <rich:treeNode> components to work with the data model.
Example 12.1. Basic usage
This example demonstrates basic usage of the <rich:tree> component using an org.richfaces.model.TreeNode data model.
The data model is constructed as follows:
private TreeNodeImpl<String> stationRoot = new TreeNodeImpl<String>();
private TreeNodeImpl<String> stationNodes = new TreeNodeImpl<String>();
private 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.setData("KickRadio");
stationNodes.addChild(0, stationRoot);
for (int i = 0; i < kickRadioFeed.length; i++){
TreeNodeImpl<String> child = new TreeNodeImpl<String>();
child.setData(kickRadioFeed[i]);
stationRoot.addChild(i, child);
}
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>
Different nodes in the tree can have different appearances, such as node icons, depending on the type of data the node contains. Use the nodeFace attribute to differentiate the types of nodes; the node is then rendered according to the <rich:treeNode> component with the corresponding type 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.6.2, “Appearance” for details on customizing the appearance of <rich:treeNode> components.
Example 12.2. nodeFace attribute
<rich:tree style="width:300px" value="#{library.data}" var="item" nodeFace="#{item.type}">
<rich:treeNode type="artist" iconLeaf="/images/tree/singer.png" icon="/images/tree/singer.png">
<h:outputText value="#{item.name}" />
</rich:treeNode>
<rich:treeNode type="album" iconLeaf="/images/tree/disc.png" icon="/images/tree/disc.png">
<h:outputText value="#{item.title}" />
</rich:treeNode>
<rich:treeNode type="song" iconLeaf="/images/tree/song.png" icon="/images/tree/song.png">
<h:outputText value="#{item.title}" />
</rich:treeNode>
</rich:tree>
Alternatively, use Expression Language (EL) with the nodeFace attribute, as shown in Example 12.3, “nodeface attribute with Expression Language”.
Example 12.3. nodeface attribute with Expression Language
<rich:tree value="#{library.data}" var="item"
nodeFace="#{data.name != 'param-value' ? 'artist' : 'album'}">
If the nodeFace attribute returns null, the node is rendered as a "typeless" node. The typeless node is the first child <rich:treeNode> component with a valid rendered attribute, but without a defined type attribute.
Icons for different nodes and node states can be defined for the whole tree using the following attributes:
iconThe
iconattribute points to the icon to use for any node that contains child nodes.iconLeafThe
iconLeafattribute points to the icon to use for any node that does not contain any child nodes.iconExpandedandiconCollapsedThe
iconExpandedandiconCollapsedattributes point to the icons to use for expanded and collapsed nodes respectively. If these attributes are defined, theiconattribute is not used.
Alternatively, use facets with the same names as the attributes to define the icons, as shown in Example 12.4, “Icon facets”. The width of the rendered facet is 16 pixels.
Example 12.4. Icon facets
<rich:tree value="#{library.data}" var="item">
<f:facet name="icon">
<h:graphicImage value="/images/tree/singer.png "/>
</f:facet>
<f:facet name="iconCollapsed">
<h:graphicImage value="/images/tree/singer.png" />
</f:facet>
<f:facet name="iconExpanded">
<h:graphicImage value="/images/tree/singer.png" />
</f:facet>
<f:facet name="iconLeaf">
<h:graphicImage value="/images/tree/song.png" />
</f:facet>
...
</rich:tree>
The switching mode for performing submissions is determined by the switchType attribute, which can have one of the following three values:
ajaxThis is the default setting. The
<rich:tree>component performs an Ajax form submission, and only the content of the tree is rendered.serverThe
<rich:tree>component performs a common submission, completely re-rendering the page.clientThe
<rich:tree>component updates on the client side, re-rendering itself and any additional components listed with therenderattribute.
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:
org.richfaces.TreeRowKeyConverterThe
org.richfaces.TreeRowKeyConverterconverter is used for trees constructed using<rich:treeNode>components. The key should be of the type java.lang.String.
To apply a converter to the <rich:tree> component, define it with the rowKeyConverter attribute. Example 12.5, “Identifying nodes” demonstrates the use of a converter to identify tree nodes.
Example 12.5. Identifying nodes
<rich:tree value="#{treeBean.data}" var="node"
rowKeyConverter="org.richfaces.TreeRowKeyConverter">
<rich:treeNode>
<h:outputText value="#{node}"/>
</rich:treeNode>
</rich:tree>
The tree uses the following data model. The model can contain special characters normally disallowed in web page code.
String[ ] components = {"< a4j:keepAlive >", "< a4j:actionParam >" };
String[ ][ ] attributes = {{"ajaxOnly", "beanName"},
{"name", "value", "assignTo"}};
data = new TreeNodeImpl<String>();
for (int i = 0; i < components.length; i++) {
TreeNode<String> child = new TreeNodeImpl<String>();
child.setData(components[i]);
data.addChild(components[i], child);
for (int j = 0; j < attributes[i].length; j++) {
TreeNode<String> grandChild = new TreeNodeImpl<String>();
grandChild.setData(attributes[i][j]);
child.addChild(attributes[i][j], grandChild);
}
}
In addition to the standard Ajax events and HMTL events, the <rich:tree> component uses the following client-side events:
The
onexpandevent is triggered when a node is expanded.The
oncollapseevent is triggered when a node is collapsed.The
ondragstartevent is triggered when an element starts being dragged.The
ondragexitevent is triggered when an element is dragged out of the tree.The
ondragenterevent is triggered when an element is dragged into the tree.The
ondragendevent is triggered when an element is dropped.
The <rich:tree> component uses the following server-side listeners:
The
changeExpandListenerlistener processes expand and collapse events.The
dragListenerlistener processes drag events.The
dropListenerlistener processes drop events.The
nodeSelectListenerlistener processes the request when a node is selected.
component-type:org.richfaces.treecomponent-class:org.richfaces.component.html.Htmltreecomponent-family:org.richfaces.treerenderer-type:org.richfaces.treeRenderertag-class:org.richfaces.taglib.treeTag
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.
The <rich:treeNode> component must be a child of a <rich:tree> component. It does not need any attributes declared for basic usage, but should contain the content of the nodes. Refer to Example 12.1, “Basic usage” for an example of basic <rich:treeNode> component usage.
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: icon, 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.6, “rendered attribute”.
Example 12.6. rendered attribute
The rendered attribute is used to differentiate between music albums that are in stock and those that are not. The item type attributes return values that are otherwise identical; only the item.exist property differs, so it is used for the rendered attribute.
<rich:tree style="width:300px" value="#{library.data}" var="item" nodeFace="#{item.type}">
...
<rich:treeNode type="album" iconLeaf="/images/tree/album.gif" icon="/images/tree/album.gif"
rendered="#{item.exist}">
<h:outputText value="#{item.name}" />
</rich:treeNode>
<rich:treeNode type="album" iconLeaf="/images/tree/album_absent.gif" icon="/images/tree/album_absent.gif"
rendered="#{not item.exist}">
<h:outputText value="#{item.name}" />
</rich:treeNode>
...
</rich:tree>
All interactivity with individual nodes, such as expanding and collapsing, drag-and-drop, and other events handling, is managed by the parent <rich:tree> component. Refer to Section 12.1.3, “Expanding and collapsing tree nodes” and Section 12.1.4, “Event handling” for further details.