JBoss.orgCommunity Documentation

Component Reference

A reference guide to the components of the RichFaces 4 framework

Logo

Abstract

This book details each component in the RichFaces 4 framework, including examples of their use in applications.


1. Introduction
1.1. Libraries
2. Common Ajax attributes
2.1. Data processing
2.1.1. execute
2.1.2. bypassUpdates
2.2. Rendering
2.2.1. render
2.2.2. ajaxRendered
2.2.3. limitRender
2.3. Queuing and traffic control
2.3.1. requestDelay
2.3.2. ignoreDupResponses
2.4. Events and JavaScript interactions
2.4.1. onbeforesubmit
2.4.2. onbegin
2.4.3. onbeforedomupdate
2.4.4. oncomplete
2.4.5. onerror
I. Ajax control components
3. Actions
3.1. <a4j:ajax>
3.1.1. Basic usage
3.1.2. Reference data
3.2. <a4j:param>
3.2.1. Basic usage
3.2.2. Interoperability
3.2.3. Passing client-side parameters
3.2.4. Reference data
3.3. <a4j:actionListener>
3.4. <a4j:commandButton>
3.4.1. Basic usage
3.4.2. Reference data
3.5. <a4j:commandLink>
3.5.1. Basic usage
3.5.2. Reference data
3.6. <a4j:jsFunction>
3.6.1. Basic usage
3.6.2. Parameters and JavaScript
3.6.3. Reference data
3.7. <a4j:poll>
3.7.1. Timing options
3.7.2. Reference data
3.8. <a4j:push>
3.8.1. Setting up Push
3.8.2. Server-side Push methods
3.8.3. Client-side Push methods
3.8.4. Push Topics
3.8.5. Handling a push message
3.8.6. Handling a push subscription
3.8.7. Using TopicsContext to publish message
3.8.8. Integrating Push with CDI events
3.8.9. Push and JMS integration
3.8.10. Reference data
4. Resources
4.1. <a4j:mediaOutput>
4.1.1. Basic usage
4.1.2. Handling content
4.1.3. Reference data
5. Containers
5.1. <a4j:outputPanel>
5.1.1. Aiding complex Ajax rendering
5.1.2. Panel appearance
5.1.3. Reference data
5.2. <a4j:region>
5.2.1. Reference data
6. Validation
6.1. <rich:validator> client-side validation
6.1.1. Basic usage
6.1.2. Messages from client-side validators
6.1.3. Validation triggers
6.1.4. Ajax fall-backs
6.1.5. Reference data
6.2. <rich:graphValidator> object validation
6.2.1. Basic usage
6.2.2. Reference data
7. Processing management
7.1. <a4j:queue>
7.1.1. Basic usage
7.1.2. Delaying requests
7.1.3. Duplicate responses
7.1.4. Queue scopes
7.1.5. <a4j:queue> client-side events
7.1.6. Reference data
7.1.7. <a4j:attachQueue>
7.2. <a4j:log>
7.2.1. Basic usage
7.2.2. Log monitoring
7.2.3. Reference data
7.2.4. Style classes and skin parameters
7.3. <a4j:status>
7.3.1. Customizing the text
7.3.2. Specifying a region
7.3.3. JavaScript API
7.3.4. Reference data
II. User interface components
8. Rich inputs
8.1. <rich:autocomplete>
8.1.1. Basic usage
8.1.2. Submission modes
8.1.3. Interactivity options
8.1.4. Customizing the filter in client and lazyClient modes
8.1.5. JavaScript API
8.1.6. Reference data
8.1.7. Style classes and skin parameters
8.2. <rich:calendar>
8.2.1. Basic usage
8.2.2. Behavior and appearance
8.2.3. Time of day
8.2.4. Localization and formatting
8.2.5. Using a data model
8.2.6. Client-side customization
8.2.7. JavaScript API
8.2.8. Reference data
8.2.9. Style classes and skin parameters
8.3. <rich:editor>
8.3.1. Basic usage
8.3.2. Styling
8.3.3. Editor skins
8.3.4. Advanced configuration
8.3.5. Toolbar customization
8.3.6. Internationalization and localization
8.3.7. Client-side event handlers
8.3.8. JavaScript API
8.3.9. Reference data
8.3.10. Style classes and skin parameters
8.4. <rich:fileUpload>
8.4.1. Basic usage
8.4.2. Upload settings
8.4.3. Sanitizing file upload input
8.4.4. Interactivity options
8.4.5. <rich:fileUpload> client-side events
8.4.6. Reference data
8.4.7. Style classes and skin parameters
8.5. <rich:inplaceInput>
8.5.1. Basic usage
8.5.2. Interactivity options
8.5.3. JavaScript API
8.5.4. Reference data
8.5.5. Style classes and skin parameters
8.6. <rich:inplaceSelect>
8.6.1. Basic usage
8.6.2. Interactivity options
8.6.3. JavaScript API
8.6.4. Reference data
8.6.5. Style classes and skin parameters
8.7. <rich:inputNumberSlider>
8.7.1. Basic usage
8.7.2. Interactivity options
8.7.3. JavaScript API
8.7.4. Reference data
8.7.5. Style classes and skin parameters
8.8. <rich:inputNumberSpinner>
8.8.1. Basic usage
8.8.2. Interactivity options
8.8.3. JavaScript API
8.8.4. Reference data
8.8.5. Style classes and skin parameters
8.9. <rich:select>
8.9.1. Basic usage
8.9.2. Using manual input
8.9.3. Advanced options
8.9.4. JavaScript API
8.9.5. Reference data
8.9.6. Style classes and skin parameters
8.10. <rich:orderingList>
8.10.1. Basic usage
8.10.2. Column Layout
8.10.3. JavaScript API
8.10.4. Reference data
8.10.5. Style classes and skin parameters
8.11. <rich:pickList>
8.11.1. Basic usage
8.11.2. Column Layout
8.11.3. JavaScript API
8.11.4. Reference data
8.11.5. Style classes and skin parameters
9. Panels
9.1. <rich:panel>
9.1.1. Basic usage
9.1.2. Adding a header
9.1.3. Reference data
9.1.4. Style classes and skin parameters
9.2. <rich:accordion>
9.2.1. Basic usage
9.2.2. Switching panels
9.2.3. <rich:accordion> client-side events
9.2.4. <rich:accordion> server-side events
9.2.5. JavaScript API
9.2.6. Reference data
9.2.7. Style classes and skin parameters
9.2.8. <rich:accordionItem>
9.3. <rich:collapsiblePanel>
9.3.1. Basic usage
9.3.2. Expanding and collapsing the panel
9.3.3. Appearance
9.3.4. <rich:collapsiblePanel> server-side events
9.3.5. JavaScript API
9.3.6. Reference data
9.3.7. Style classes and skin parameters
9.3.8. <rich:panelToggleListener>
9.4. <rich:popupPanel>
9.4.1. Basic usage
9.4.2. Showing and hiding the pop-up
9.4.3. Modal and non-modal panels
9.4.4. Size and positioning
9.4.5. Header and controls
9.4.6. Contents of the pop-up
9.4.7. JavaScript API
9.4.8. Reference data
9.4.9. Style classes and skin parameters
9.5. <rich:tabPanel>
9.5.1. Switching panels
9.5.2. <rich:tabPanel> client-side events
9.5.3. <rich:tabPanel> server-side events
9.5.4. JavaScript API
9.5.5. Reference data
9.5.6. Style classes and skin parameters
9.5.7. <rich:tab>
9.6. <rich:togglePanel>
9.6.1. Basic usage
9.6.2. Toggling between components
9.6.3. JavaScript API
9.6.4. Reference data
9.6.5. <rich:itemChangeListener>
9.6.6. <rich:toggleControl>
9.6.7. <rich:togglePanelItem>
10. Tables and grids
10.1. <a4j:repeat>
10.1.1. Basic usage
10.1.2. Limited views and partial updates
10.1.3. Reference data
10.2. <rich:dataTable>
10.2.1. Basic usage
10.2.2. Customizing the table
10.2.3. Partial updates
10.2.4. JavaScript API
10.2.5. Reference data
10.2.6. Style classes and skin parameters
10.3. <rich:column>
10.3.1. Basic usage
10.3.2. Spanning columns
10.3.3. Spanning rows
10.3.4. Reference data
10.4. <rich:columnGroup>
10.4.1. Complex headers
10.4.2. Reference data
10.5. <rich:collapsibleSubTable>
10.5.1. Basic usage
10.5.2. Expanding and collapsing the sub-table
10.5.3. Reference data
10.5.4. Style classes
10.5.5. <rich:collapsibleSubTableToggler>
10.6. <rich:extendedDataTable>
10.6.1. Basic usage
10.6.2. Table appearance
10.6.3. Extended features
10.6.4. JavaScript API
10.6.5. Reference data
10.6.6. Style classes and skin parameters
10.7. <rich:dataGrid>
10.7.1. Basic usage
10.7.2. Customizing the grid
10.7.3. Partial updates
10.7.4. Reference data
10.7.5. Style classes and skin parameters
10.8. <rich:list>
10.8.1. Basic usage
10.8.2. Type of list
10.8.3. Bullet and numeration appearance
10.8.4. Customizing the list
10.8.5. Reference data
10.8.6. Style classes and skin parameters
10.9. <rich:dataScroller>
10.9.1. Basic usage
10.9.2. Appearance and interactivity
10.9.3. JavaScript API
10.9.4. Reference data
10.9.5. Style classes and skin parameters
10.10. Table filtering
10.11. Table sorting
11. Trees
11.1. <rich:tree>
11.1.1. Basic usage
11.1.2. Appearance
11.1.3. Expanding and collapsing tree nodes
11.1.4. Selecting tree nodes
11.1.5. Identifying nodes with the rowKeyConverter attribute
11.1.6. Event handling
11.1.7. Reference data
11.1.8. Style classes
11.1.9. <rich:treeSelectionChangeListener>
11.1.10. <rich:treeNode>
11.2. Tree adaptors
11.2.1. <rich:treeModelAdaptor>
11.2.2. <rich:treeModelRecursiveAdaptor>
12. Menus and toolbars
12.1. <rich:dropDownMenu>
12.1.1. Basic usage
12.1.2. Menu content
12.1.3. Appearance
12.1.4. Expanding and collapsing the menu
12.1.5. Reference data
12.1.6. Style classes and skin parameters
12.2. <rich:contextMenu>
12.2.1. Basic usage
12.2.2. Appearance
12.2.3. Expanding and collapsing the menu
12.2.4. Reference data
12.2.5. Style classes and skin parameters
12.3. Menu sub-components
12.3.1. <rich:menuItem>
12.3.2. <rich:menuGroup>
12.3.3. <rich:menuSeparator>
12.4. <rich:panelMenu>
12.4.1. Basic usage
12.4.2. Interactivity options
12.4.3. Appearance
12.4.4. Submission modes
12.4.5. <rich:panelMenu> server-side events
12.4.6. JavaScript API
12.4.7. Reference data
12.4.8. Style classes and skin parameters
12.4.9. <rich:panelMenuGroup>
12.4.10. <rich:panelMenuItem>
12.5. <rich:toolbar>
12.5.1. Basic usage
12.5.2. Appearance
12.5.3. Grouping items
12.5.4. Reference data
12.5.5. Style classes and skin parameters
12.5.6. <rich:toolbarGroup>
13. Output and messages
13.1. <rich:message>
13.1.1. Basic usage
13.1.2. Appearance
13.1.3. Reference data
13.1.4. Style classes and skin parameters
13.2. <rich:messages>
13.2.1. Basic usage
13.2.2. Appearance
13.2.3. Reference data
13.2.4. Style classes and skin parameters
13.3. <rich:notify>
13.3.1. Basic usage
13.3.2. Customizing notifications
13.3.3. Reference data
13.3.4. Style classes and skin parameters
13.4. <rich:notifyMessage>
13.4.1. Basic usage
13.4.2. Reference data
13.4.3. Style classes and skin parameters
13.5. <rich:notifyMessages>
13.5.1. Reference data
13.5.2. Style classes and skin parameters
13.6. <rich:notifyStack>
13.6.1. Basic usage
13.6.2. Positioning notifications
13.6.3. Stacking notifications
13.6.4. Reference data
13.6.5. Style classes and skin parameters
13.7. <rich:progressBar>
13.7.1. Basic usage
13.7.2. Customizing the appearance
13.7.3. Update mode
13.7.4. Using set intervals
13.7.5. JavaScript API
13.7.6. Reference data
13.7.7. Style classes and skin parameters
13.8. <rich:tooltip>
13.8.1. Basic usage
13.8.2. Attaching the tool-tip to another component
13.8.3. Appearance
13.8.4. Update mode
13.8.5. <rich:tooltip> client-side events
13.8.6. JavaScript API
13.8.7. Reference data
13.8.8. Style classes and skin parameters
14. Drag and drop
14.1. <rich:dragSource>
14.1.1. Basic usage
14.1.2. Dragging an object
14.1.3. Reference data
14.2. <rich:dropTarget>
14.2.1. Basic usage
14.2.2. Handling dropped data
14.2.3. Reference data
14.2.4. Style classes
14.3. <rich:dragIndicator>
14.3.1. Basic usage
14.3.2. Styling the indicator
14.3.3. Reference data
14.3.4. Style classes
15. Layout and appearance
15.1. <rich:jQuery>
15.1.1. Basic usage
15.1.2. Defining a selector
15.1.3. Event handlers
15.1.4. Timed queries
15.1.5. Named queries
15.1.6. Dynamic rendering
15.1.7. Reference data
16. Functions
16.1. rich:clientId
16.2. rich:component
16.3. rich:element
16.4. rich:findComponent
16.5. rich:isUserInRole
17. Functionality extension
17.1. <rich:componentControl>
17.1.1. Basic usage
17.1.2. Passing parameters to API methods
17.1.3. Reference data
17.1.4. <rich:hotKey>
17.1.5. <rich:hashParam>
A. Revision History

This book is a guide to the various components available in the RichFaces 4.2.2.Final framework. It includes descriptions of the role of the components, details on how best to use them, coded examples of their use, and basic references of their properties and attributes.

For full references for all component classes and properties, refer to the following supplementary documentation:

For further examples for each component, refer to the RichFaces Showcase at http://richfaces-showcase.appspot.com/.

The Ajax components in the a4j library share common attributes to perform similar functionality. Most RichFaces components in the rich library that feature built-in Ajax support share these common attributes as well.

Most attributes have default values, so they need not be explicitly set for the component to function in its default state. These attributes can be altered to customize the behavior of the component if necessary.

The RichFaces Ajax script is built on a base of the JSF 2 Ajax script. As such, each time a request is sent, the data from the requesting component's parent JSF form is submitted along with the XMLHTTPRequest object. The form data contains values from the input element and auxiliary information such as state-saving data.

The render attribute provides a reference to one or more components on the page that need updating after an Ajax interaction. It uses the UIComponent.findComponent() algorithm to find the components in the component tree using their id identifiers as a reference. Components can be referenced by their id identifier alone, or by their clientId identifier to make locating components more efficient. Example 2.1, “render example” shows both ways of referencing components. Each command button will correctly render the referenced panel grids, but the second button locates the references more efficiently with explicit clientId paths.


The value of the render attribute can also be an expression written using JavaServer Faces' Expression Language (EL); this can either be a Set, Collection, Array, or String.

Differences between JSF Ajax and RichFaces Ajax

JSF evaluates all parameters during page rendering. As such, during a request from a page, all execute and render values are passed to the server from the client. In contrast, RichFaces evaluates these options at the server side during the current request.

This means that with JSF, making changes during a request to a render value defined with EL will not influence the request. RichFaces, however, will always use the newer values.

The RichFaces approach additionally increases data integrity. Parameters that are changed from the client side are re-evaluated on the server, where they cannot be changed.

Conditionally-rendered component updates

A common problem with using render occurs when the referenced component is conditionally rendered via the rendered attribute. If a component is not initially rendered, it does not have any HTML representation in the Document Object Model (DOM). As such, when RichFaces renders the component via Ajax, the page does not update as the place for the update is not known.

To work around this issue, wrap the component to be rendered in an <a4j:outputPanel> component. The <a4j:outputPanel> component will receive the update and render the component as required.

JSF provides global jsf.ajax.onError and jsf.ajax.onEvent events to define handlers (the jsf.ajax.onEvent event is used for all begin, success, and complete events). RichFaces adds event-specific attributes at the component level.

Table of Contents

3. Actions
3.1. <a4j:ajax>
3.1.1. Basic usage
3.1.2. Reference data
3.2. <a4j:param>
3.2.1. Basic usage
3.2.2. Interoperability
3.2.3. Passing client-side parameters
3.2.4. Reference data
3.3. <a4j:actionListener>
3.4. <a4j:commandButton>
3.4.1. Basic usage
3.4.2. Reference data
3.5. <a4j:commandLink>
3.5.1. Basic usage
3.5.2. Reference data
3.6. <a4j:jsFunction>
3.6.1. Basic usage
3.6.2. Parameters and JavaScript
3.6.3. Reference data
3.7. <a4j:poll>
3.7.1. Timing options
3.7.2. Reference data
3.8. <a4j:push>
3.8.1. Setting up Push
3.8.2. Server-side Push methods
3.8.3. Client-side Push methods
3.8.4. Push Topics
3.8.5. Handling a push message
3.8.6. Handling a push subscription
3.8.7. Using TopicsContext to publish message
3.8.8. Integrating Push with CDI events
3.8.9. Push and JMS integration
3.8.10. Reference data
4. Resources
4.1. <a4j:mediaOutput>
4.1.1. Basic usage
4.1.2. Handling content
4.1.3. Reference data
5. Containers
5.1. <a4j:outputPanel>
5.1.1. Aiding complex Ajax rendering
5.1.2. Panel appearance
5.1.3. Reference data
5.2. <a4j:region>
5.2.1. Reference data
6. Validation
6.1. <rich:validator> client-side validation
6.1.1. Basic usage
6.1.2. Messages from client-side validators
6.1.3. Validation triggers
6.1.4. Ajax fall-backs
6.1.5. Reference data
6.2. <rich:graphValidator> object validation
6.2.1. Basic usage
6.2.2. Reference data
7. Processing management
7.1. <a4j:queue>
7.1.1. Basic usage
7.1.2. Delaying requests
7.1.3. Duplicate responses
7.1.4. Queue scopes
7.1.5. <a4j:queue> client-side events
7.1.6. Reference data
7.1.7. <a4j:attachQueue>
7.2. <a4j:log>
7.2.1. Basic usage
7.2.2. Log monitoring
7.2.3. Reference data
7.2.4. Style classes and skin parameters
7.3. <a4j:status>
7.3.1. Customizing the text
7.3.2. Specifying a region
7.3.3. JavaScript API
7.3.4. Reference data

This chapter details the basic components that respond to a user action and submit an Ajax request.

The <a4j:param> behavior combines the functionality of the JavaServer Faces (JSF) components <f:param> and <f:actionListener>.

The <a4j:jsFunction> component performs Ajax requests directly from JavaScript code and retrieves server-side data. The server-side data is returned in JavaScript Object Notation (JSON) format prior to the execution of any JavaScript code defined using the oncomplete attribute.

The <a4j:jsFunction> component requires the data attribute. Use the data attribute to define where the retrieved server-side data is stored.

Example 3.4, “<a4j:jsFunction> example” shows how an Ajax request can be initiated from the JavaScript and a partial page update performed. The JavaScript function can be invoked with the data returned by the Ajax response.


The <a4j:push> component performs real-time updates on the client side from events triggered at the server side. The events are pushed out to the client through the RichFaces messaging queue. When the <a4j:push> component is triggered by a server event, it can in turn cause Ajax updates and changes.

The <a4j:push> component uses the Comet model for pushing data to the client.

Using the Push component requires configuration steps which depends on an environment in which the Push is used:

The Push requires a PushServlet registered in web application and listening for Push client connections.

In the Servlets 3.0 and higher environments, the servlet will be registered automatically.

However in the Servlets 2.5 and lower environments, the servlet needs to be registered manually in web.xml:


<!-- Push Servlet - listens for user sessions -->
<servlet>
    <servlet-name>Push Servlet</servlet-name>
    <servlet-class>org.richfaces.webapp.PushServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>Push Servlet</servlet-name>
    <url-pattern>/__richfaces_push</url-pattern>
</servlet-mapping>

<!-- setups servlet-mapping in RichFaces configuration -->
<context-param>
    <param-name>org.richfaces.push.handlerMapping</param-name>
    <param-value>/__richfaces_push</param-value>
</context-param>

An integration of the RichFaces Push and the Java Messaging Service (JMS) allows to write robust interactive applications.

The JMS instance on the back-end must be configured to work with your <a4j:push> components.


Ensure the Create durable subscriber and Delete durable subscriber options are set to true for push functionality.

Durable subscriptions

Durable subscriptions receive all events, including those events which were sent while the push component was not connected.

Refer to JMS Documentation for details on configuring the JMS Server.

JMS integration with custom configuration

The RichFaces looks for the JMS Connection Factory on the JNDI context /ConnectionFactory by default

The prefix /topic is used for deriving JMS topic names from Push topic names.

When integrating component into an enterprise system, this defaults can be changed.

Use following web.xml parameters to change default values: org.richfaces.push.jms.connectionFactory, org.richfaces.push.jms.topicsNamespace.

When RichFaces obtains a connection, an empty user name is used with an empty password.

Use following web.xml parameters or equivalent JVM parameters to change default values: org.richfaces.push.jms.connectionUsername, org.richfaces.push.jms.connectionPassword.

,

The JMS message which should be propagated to Push needs to be created with method session.createObjectMessage(message);.

The message could be then published using publisher.publish(message); like in a following example:


Receiving messages from JMS doesn't differ from receiving messages sent by the TopicsContext or using CDI events.


This example demonstrates a simple use of the <a4j:push> causing an immediate update of page content.

This chapter covers those components used to handle and manage resources and beans.

The <a4j:mediaOutput> component is used for generating images, video, sounds, and other resources defined on the fly.

The mimeType attribute describes the type of output content, and corresponds to the type in the header of the HTTP request. The element attribute defines XHTML element used to display the content:

Example 4.1. <a4j:mediaOutput> example

This example uses the <a4j:mediaOutput> component to generate a JPEG image of verification digits. The code on the application page is a single element:


<a4j:mediaOutput element="img" cacheable="false" session="false"
                 createContent="#{mediaBean.paint}" value="#{mediaData}" 
                 mimeType="image/jpeg" />

The <a4j:mediaOutput> component uses the MediaBean.paint method to create the image. The method generates a random number, which is then converted into an output stream and rendered to a JPEG image. The MediaBean class is as follows:

package demo;


import java.awt.Graphics2D;
import java.awt.image.BufferedImage;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Random;
import javax.imageio.ImageIO;
public class MediaBean {
    public void paint(OutputStream out, Object data) throws IOException {
        Integer high = 9999;
        Integer low = 1000;
        Random generator = new Random();
        Integer digits = generator.nextInt(high - low + 1) + low;
        if (data instanceof MediaData) {            
            MediaData paintData = (MediaData) data;
            BufferedImage img = new BufferedImage(paintData.getWidth(),paintData.getHeight(),BufferedImage.TYPE_INT_RGB);
            Graphics2D graphics2D = img.createGraphics();
            graphics2D.setBackground(paintData.getBackground());
            graphics2D.setColor(paintData.getDrawColor());
            graphics2D.clearRect(0,0,paintData.getWidth(),paintData.getHeight());
            graphics2D.setFont(paintData.getFont());
            graphics2D.drawString(digits.toString(), 20, 35);
            ImageIO.write(img,"png",out);
        }
    }
}

Another class, MediaData is required by the value attribute for keeping data to be used as input for the content creation method. The MediaData class is as follows:

package demo;


import java.awt.Color;
import java.awt.Font;
import java.io.Serializable;
public class MediaData implements Serializable {
    private static final long serialVersionUID = 1L;
    Integer Width=110;
    Integer Height=50;
    Color Background=new Color(190, 214, 248);
    Color DrawColor=new Color(0,0,0);
    Font font = new Font("Serif", Font.TRUETYPE_FONT, 30);
    /* Corresponding getters and setters */
    ...
}

The <a4j:mediaOutput> component uses the MediaBean and MediaData classes to generate a new image on each page refresh.


Serializable interface

A bean class passed using the value attribute of <a4j:mediaOutput> should implement the Serializable interface so that it will be encoded to the URL of the resource.

This chapter details those components in the a4j tag library which define an area used as a container or wrapper for other components.

JavaServer Faces 2 provides built-in support for bean validation as per the Java Specification Request JSR-303 standard. As such, containers must validate model objects. Validation is performed at different application tiers according to annotation-based constraints. Refer to http://jcp.org/en/jsr/detail?id=303 for further details on the JSR-303 specification.

Example 6.1, “JSR-303 validation annotations” shows an example JSF managed bean. The bean includes JSR-303 annotations for validation. Validation annotations defined in this way are registered on components bound to the bean properties, and validation is triggered in the Process Validation phase.


Requirements

Bean validation in both JavaServer Faces and RichFaces requires the JSR-303 implementation. The implementation is bundled with JEE 6 Application Server.

If using Tomcat or another simple servlet container, add the validation-api Java Archive and a validation provider (such as Hibernate Validator) to your application libraries.

The validation built in to JavaServer Faces 2 occurs on the server side. The <rich:validator> behavior adds client-side validation to a control based on registered server-side validators. It provides this validation without the need to reproduce the server-side annotations. The <rich:validator> behavior triggers all client validator annotations listed in the relevant managed bean.

Use the <rich:message> and <rich:messages> components to display validation messages. The for attribute of the <rich:message> component references the id identifier of the input control being validated.


The <rich:graphValidator> component is used to wrap a set of input components related to one object. The object defined by the <rich:graphValidator> component can then be completely validated. The validation includes all object properties, even those which are not bound to the individual form components. Validation performed in this way allows for cross-field validation in complex forms.

The <rich:graphValidator> element must wrap all the input controls that are required to validate the object. The value attribute names the bean for the validating object.

Example 6.5. Basic usage

The example demonstrates a simple form for changing a password. The two entered passwords must match, so a <rich:graphValidator> component is used for cross-field validation.


<h:form>
   <rich:graphValidator value="#{userBean}">
      <rich:panel header="Change password">
         <rich:messages/>
         <h:panelGrid columns="3">
            <h:outputText value="Enter new password:" />
            <h:inputSecret value="#{userBean.password}" id="pass"/>
            <rich:message for="pass"/>
            <h:outputText value="Confirm the new password:" />
            <h:inputSecret value="#{userBean.confirm}" id="conf"/>
            <rich:message for="conf"/>
         </h:panelGrid>
         <a4j:commandButton value="Store changes"
                            action="#{userBean.storeNewPassword}" />
      </rich:panel>
   </rich:graphValidator>
</h:form>

The input controls validate against the following bean:

@ManagedBean

@RequestScoped
public class UserBean implements Cloneable {
   @Size(min = 5, max = 15, message="Wrong size for password")
   private String password;
   @Size(min = 5, max = 15, message="Wrong size for confirmation")
   private String confirm;
   private String status = "";
   
   @AssertTrue(message = "Different passwords entered!")
   public boolean isPasswordsEquals() {
      return password.equals(confirm);
   }
   public void storeNewPassword() {
      FacesContext.getCurrentInstance().addMessage("", new FacesMessage(FacesMessage.SEVERITY_INFO, "Succesfully changed!", "Succesfully changed!"));
   }
   ...
}

When validation occurs, the whole object is validated against the annotation contstraints. The @AssertTrue annotation relies on the isPasswordsEqual() function to check whether the two entered passwords are equal.

If the entered passwords do not match, an error message is displayed:


This chapter covers those components that manage the processing of information, requests, and updates.

The <a4j:queue> component manages the JSF queue of Ajax requests. It provides additional options for a finer control of request processing.

The <a4j:attachQueue> behavior is used together with a <a4j:queue> component to further customize queuing for particular components and behaviors. The <a4j:attachQueue> behavior can override the scope-wide queue settings for an individual component, or attach specific requests to a queue.

The <a4j:log> component generates JavaScript that opens a debug window, logging application information such as requests, responses, and DOM changes.

The <a4j:log> component is intended primarily for debugging during development. However it is still possible to style the component if desired.

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

Class (selector)Skin ParametersMapped CSS properties
.rf-log

This class defines styles for the log.

generalTextColor

color

.rf-log-popup

This class defines styles for the log when it appears as a pop-up.

No skin parameters.
.rf-log-popup-cnt

This class defines styles for the content of the log pop-up.

No skin parameters.
.rf-log-inline

This class defines styles for the log when it appears in-line.

No skin parameters.
.rf-log-contents

This class defines styles for the log contents.

No skin parameters.
.rf-log-entry-lbl

This class defines styles for a label in the log.

No skin parameters.
.rf-log-entry-lbl-debug

This class defines styles for the debug label in the log.

No skin parameters.
.rf-log-entry-lbl-info

This class defines styles for the information label in the log.

No skin parameters.
.rf-log-entry-lbl-warn

This class defines styles for the warning label in the log.

No skin parameters.
.rf-log-entry-lbl-error

This class defines styles for the error label in the log.

No skin parameters.
.rf-log-entry-msg

This class defines styles for a message in the log.

No skin parameters.
.rf-log-entry-msg-debug

This class defines styles for the debug message in the log.

No skin parameters.
.rf-log-entry-msg-info

This class defines styles for the information message in the log.

No skin parameters.
.rf-log-entry-msg-warn

This class defines styles for the warning message in the log.

No skin parameters.
.rf-log-entry-msg-error

This class defines styles for the error message in the log.

No skin parameters.
.rf-log-entry-msg-xml

This class defines styles for an XML message in the log.

No skin parameters.

The <a4j:status> component displays the status of current Ajax requests. The status can be either in progress, complete, or an error is shown after a failed request.

The <a4j:status> component monitors the status of the region relevant to where it is placed.

However, if identified with the name attribute, the <a4j:status> component can monitor any Ajax component or behavior. Use the status attribute on the Ajax component or behavior to reference the name identifier of the <a4j:status> component.


Table of Contents

8. Rich inputs
8.1. <rich:autocomplete>
8.1.1. Basic usage
8.1.2. Submission modes
8.1.3. Interactivity options
8.1.4. Customizing the filter in client and lazyClient modes
8.1.5. JavaScript API
8.1.6. Reference data
8.1.7. Style classes and skin parameters
8.2. <rich:calendar>
8.2.1. Basic usage
8.2.2. Behavior and appearance
8.2.3. Time of day
8.2.4. Localization and formatting
8.2.5. Using a data model
8.2.6. Client-side customization
8.2.7. JavaScript API
8.2.8. Reference data
8.2.9. Style classes and skin parameters
8.3. <rich:editor>
8.3.1. Basic usage
8.3.2. Styling
8.3.3. Editor skins
8.3.4. Advanced configuration
8.3.5. Toolbar customization
8.3.6. Internationalization and localization
8.3.7. Client-side event handlers
8.3.8. JavaScript API
8.3.9. Reference data
8.3.10. Style classes and skin parameters
8.4. <rich:fileUpload>
8.4.1. Basic usage
8.4.2. Upload settings
8.4.3. Sanitizing file upload input
8.4.4. Interactivity options
8.4.5. <rich:fileUpload> client-side events
8.4.6. Reference data
8.4.7. Style classes and skin parameters
8.5. <rich:inplaceInput>
8.5.1. Basic usage
8.5.2. Interactivity options
8.5.3. JavaScript API
8.5.4. Reference data
8.5.5. Style classes and skin parameters
8.6. <rich:inplaceSelect>
8.6.1. Basic usage
8.6.2. Interactivity options
8.6.3. JavaScript API
8.6.4. Reference data
8.6.5. Style classes and skin parameters
8.7. <rich:inputNumberSlider>
8.7.1. Basic usage
8.7.2. Interactivity options
8.7.3. JavaScript API
8.7.4. Reference data
8.7.5. Style classes and skin parameters
8.8. <rich:inputNumberSpinner>
8.8.1. Basic usage
8.8.2. Interactivity options
8.8.3. JavaScript API
8.8.4. Reference data
8.8.5. Style classes and skin parameters
8.9. <rich:select>
8.9.1. Basic usage
8.9.2. Using manual input
8.9.3. Advanced options
8.9.4. JavaScript API
8.9.5. Reference data
8.9.6. Style classes and skin parameters
8.10. <rich:orderingList>
8.10.1. Basic usage
8.10.2. Column Layout
8.10.3. JavaScript API
8.10.4. Reference data
8.10.5. Style classes and skin parameters
8.11. <rich:pickList>
8.11.1. Basic usage
8.11.2. Column Layout
8.11.3. JavaScript API
8.11.4. Reference data
8.11.5. Style classes and skin parameters
9. Panels
9.1. <rich:panel>
9.1.1. Basic usage
9.1.2. Adding a header
9.1.3. Reference data
9.1.4. Style classes and skin parameters
9.2. <rich:accordion>
9.2.1. Basic usage
9.2.2. Switching panels
9.2.3. <rich:accordion> client-side events
9.2.4. <rich:accordion> server-side events
9.2.5. JavaScript API
9.2.6. Reference data
9.2.7. Style classes and skin parameters
9.2.8. <rich:accordionItem>
9.3. <rich:collapsiblePanel>
9.3.1. Basic usage
9.3.2. Expanding and collapsing the panel
9.3.3. Appearance
9.3.4. <rich:collapsiblePanel> server-side events
9.3.5. JavaScript API
9.3.6. Reference data
9.3.7. Style classes and skin parameters
9.3.8. <rich:panelToggleListener>
9.4. <rich:popupPanel>
9.4.1. Basic usage
9.4.2. Showing and hiding the pop-up
9.4.3. Modal and non-modal panels
9.4.4. Size and positioning
9.4.5. Header and controls
9.4.6. Contents of the pop-up
9.4.7. JavaScript API
9.4.8. Reference data
9.4.9. Style classes and skin parameters
9.5. <rich:tabPanel>
9.5.1. Switching panels
9.5.2. <rich:tabPanel> client-side events
9.5.3. <rich:tabPanel> server-side events
9.5.4. JavaScript API
9.5.5. Reference data
9.5.6. Style classes and skin parameters
9.5.7. <rich:tab>
9.6. <rich:togglePanel>
9.6.1. Basic usage
9.6.2. Toggling between components
9.6.3. JavaScript API
9.6.4. Reference data
9.6.5. <rich:itemChangeListener>
9.6.6. <rich:toggleControl>
9.6.7. <rich:togglePanelItem>
10. Tables and grids
10.1. <a4j:repeat>
10.1.1. Basic usage
10.1.2. Limited views and partial updates
10.1.3. Reference data
10.2. <rich:dataTable>
10.2.1. Basic usage
10.2.2. Customizing the table
10.2.3. Partial updates
10.2.4. JavaScript API
10.2.5. Reference data
10.2.6. Style classes and skin parameters
10.3. <rich:column>
10.3.1. Basic usage
10.3.2. Spanning columns
10.3.3. Spanning rows
10.3.4. Reference data
10.4. <rich:columnGroup>
10.4.1. Complex headers
10.4.2. Reference data
10.5. <rich:collapsibleSubTable>
10.5.1. Basic usage
10.5.2. Expanding and collapsing the sub-table
10.5.3. Reference data
10.5.4. Style classes
10.5.5. <rich:collapsibleSubTableToggler>
10.6. <rich:extendedDataTable>
10.6.1. Basic usage
10.6.2. Table appearance
10.6.3. Extended features
10.6.4. JavaScript API
10.6.5. Reference data
10.6.6. Style classes and skin parameters
10.7. <rich:dataGrid>
10.7.1. Basic usage
10.7.2. Customizing the grid
10.7.3. Partial updates
10.7.4. Reference data
10.7.5. Style classes and skin parameters
10.8. <rich:list>
10.8.1. Basic usage
10.8.2. Type of list
10.8.3. Bullet and numeration appearance
10.8.4. Customizing the list
10.8.5. Reference data
10.8.6. Style classes and skin parameters
10.9. <rich:dataScroller>
10.9.1. Basic usage
10.9.2. Appearance and interactivity
10.9.3. JavaScript API
10.9.4. Reference data
10.9.5. Style classes and skin parameters
10.10. Table filtering
10.11. Table sorting
11. Trees
11.1. <rich:tree>
11.1.1. Basic usage
11.1.2. Appearance
11.1.3. Expanding and collapsing tree nodes
11.1.4. Selecting tree nodes
11.1.5. Identifying nodes with the rowKeyConverter attribute
11.1.6. Event handling
11.1.7. Reference data
11.1.8. Style classes
11.1.9. <rich:treeSelectionChangeListener>
11.1.10. <rich:treeNode>
11.2. Tree adaptors
11.2.1. <rich:treeModelAdaptor>
11.2.2. <rich:treeModelRecursiveAdaptor>
12. Menus and toolbars
12.1. <rich:dropDownMenu>
12.1.1. Basic usage
12.1.2. Menu content
12.1.3. Appearance
12.1.4. Expanding and collapsing the menu
12.1.5. Reference data
12.1.6. Style classes and skin parameters
12.2. <rich:contextMenu>
12.2.1. Basic usage
12.2.2. Appearance
12.2.3. Expanding and collapsing the menu
12.2.4. Reference data
12.2.5. Style classes and skin parameters
12.3. Menu sub-components
12.3.1. <rich:menuItem>
12.3.2. <rich:menuGroup>
12.3.3. <rich:menuSeparator>
12.4. <rich:panelMenu>
12.4.1. Basic usage
12.4.2. Interactivity options
12.4.3. Appearance
12.4.4. Submission modes
12.4.5. <rich:panelMenu> server-side events
12.4.6. JavaScript API
12.4.7. Reference data
12.4.8. Style classes and skin parameters
12.4.9. <rich:panelMenuGroup>
12.4.10. <rich:panelMenuItem>
12.5. <rich:toolbar>
12.5.1. Basic usage
12.5.2. Appearance
12.5.3. Grouping items
12.5.4. Reference data
12.5.5. Style classes and skin parameters
12.5.6. <rich:toolbarGroup>
13. Output and messages
13.1. <rich:message>
13.1.1. Basic usage
13.1.2. Appearance
13.1.3. Reference data
13.1.4. Style classes and skin parameters
13.2. <rich:messages>
13.2.1. Basic usage
13.2.2. Appearance
13.2.3. Reference data
13.2.4. Style classes and skin parameters
13.3. <rich:notify>
13.3.1. Basic usage
13.3.2. Customizing notifications
13.3.3. Reference data
13.3.4. Style classes and skin parameters
13.4. <rich:notifyMessage>
13.4.1. Basic usage
13.4.2. Reference data
13.4.3. Style classes and skin parameters
13.5. <rich:notifyMessages>
13.5.1. Reference data
13.5.2. Style classes and skin parameters
13.6. <rich:notifyStack>
13.6.1. Basic usage
13.6.2. Positioning notifications
13.6.3. Stacking notifications
13.6.4. Reference data
13.6.5. Style classes and skin parameters
13.7. <rich:progressBar>
13.7.1. Basic usage
13.7.2. Customizing the appearance
13.7.3. Update mode
13.7.4. Using set intervals
13.7.5. JavaScript API
13.7.6. Reference data
13.7.7. Style classes and skin parameters
13.8. <rich:tooltip>
13.8.1. Basic usage
13.8.2. Attaching the tool-tip to another component
13.8.3. Appearance
13.8.4. Update mode
13.8.5. <rich:tooltip> client-side events
13.8.6. JavaScript API
13.8.7. Reference data
13.8.8. Style classes and skin parameters
14. Drag and drop
14.1. <rich:dragSource>
14.1.1. Basic usage
14.1.2. Dragging an object
14.1.3. Reference data
14.2. <rich:dropTarget>
14.2.1. Basic usage
14.2.2. Handling dropped data
14.2.3. Reference data
14.2.4. Style classes
14.3. <rich:dragIndicator>
14.3.1. Basic usage
14.3.2. Styling the indicator
14.3.3. Reference data
14.3.4. Style classes
15. Layout and appearance
15.1. <rich:jQuery>
15.1.1. Basic usage
15.1.2. Defining a selector
15.1.3. Event handlers
15.1.4. Timed queries
15.1.5. Named queries
15.1.6. Dynamic rendering
15.1.7. Reference data
16. Functions
16.1. rich:clientId
16.2. rich:component
16.3. rich:element
16.4. rich:findComponent
16.5. rich:isUserInRole
17. Functionality extension
17.1. <rich:componentControl>
17.1.1. Basic usage
17.1.2. Passing parameters to API methods
17.1.3. Reference data
17.1.4. <rich:hotKey>
17.1.5. <rich:hashParam>
8.1. <rich:autocomplete>
8.1.1. Basic usage
8.1.2. Submission modes
8.1.3. Interactivity options
8.1.4. Customizing the filter in client and lazyClient modes
8.1.5. JavaScript API
8.1.6. Reference data
8.1.7. Style classes and skin parameters
8.2. <rich:calendar>
8.2.1. Basic usage
8.2.2. Behavior and appearance
8.2.3. Time of day
8.2.4. Localization and formatting
8.2.5. Using a data model
8.2.6. Client-side customization
8.2.7. JavaScript API
8.2.8. Reference data
8.2.9. Style classes and skin parameters
8.3. <rich:editor>
8.3.1. Basic usage
8.3.2. Styling
8.3.3. Editor skins
8.3.4. Advanced configuration
8.3.5. Toolbar customization
8.3.6. Internationalization and localization
8.3.7. Client-side event handlers
8.3.8. JavaScript API
8.3.9. Reference data
8.3.10. Style classes and skin parameters
8.4. <rich:fileUpload>
8.4.1. Basic usage
8.4.2. Upload settings
8.4.3. Sanitizing file upload input
8.4.4. Interactivity options
8.4.5. <rich:fileUpload> client-side events
8.4.6. Reference data
8.4.7. Style classes and skin parameters
8.5. <rich:inplaceInput>
8.5.1. Basic usage
8.5.2. Interactivity options
8.5.3. JavaScript API
8.5.4. Reference data
8.5.5. Style classes and skin parameters
8.6. <rich:inplaceSelect>
8.6.1. Basic usage
8.6.2. Interactivity options
8.6.3. JavaScript API
8.6.4. Reference data
8.6.5. Style classes and skin parameters
8.7. <rich:inputNumberSlider>
8.7.1. Basic usage
8.7.2. Interactivity options
8.7.3. JavaScript API
8.7.4. Reference data
8.7.5. Style classes and skin parameters
8.8. <rich:inputNumberSpinner>
8.8.1. Basic usage
8.8.2. Interactivity options
8.8.3. JavaScript API
8.8.4. Reference data
8.8.5. Style classes and skin parameters
8.9. <rich:select>
8.9.1. Basic usage
8.9.2. Using manual input
8.9.3. Advanced options
8.9.4. JavaScript API
8.9.5. Reference data
8.9.6. Style classes and skin parameters
8.10. <rich:orderingList>
8.10.1. Basic usage
8.10.2. Column Layout
8.10.3. JavaScript API
8.10.4. Reference data
8.10.5. Style classes and skin parameters
8.11. <rich:pickList>
8.11.1. Basic usage
8.11.2. Column Layout
8.11.3. JavaScript API
8.11.4. Reference data
8.11.5. Style classes and skin parameters

This chapter details rich components for user input and interaction.

The <rich:autocomplete> component is an auto-completing input-box with built-in Ajax capabilities. It supports client-side suggestions, browser-like selection, and customization of the look and feel.

The auto-complete box is a standard JSF UIInput control with added validation.

Figure 8.1. <rich:autocomplete>


The <rich:autocomplete> component uses the JavaScript startsWith() method to create the list of suggestions. The filtering is performed on the client side. Alternatively, use the clientFilterFunction attribute to specify a custom filtering function. The custom function must accept two parameters: the subString parameter is the filtering value as typed into the text box by the user, and the value parameter is an item in the list of suggestions against which the subString must be checked. Each item is iterated through and passed to the function as the value parameter. The custom function must return a boolean value indicating whether the passed item meets the conditions of the filter, and the suggestion list is constructed from successful items.


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

Class (selector)Skin ParametersMapped CSS properties
.rf-au-fnt

This class defines styles for the auto-complete box font.

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-au-inp

This class defines styles for the auto-complete input box.

controlBackgroundColor

background-color

.rf-au-fld

This class defines styles for the auto-complete field.

panelBorderColor

border-color

controlBackgroundColor

background-color

.rf-au-fld-btn

This class defines styles for a button in the auto-complete field.

No skin parameters.
.rf-au-btn

This class defines styles for the auto-complete box button.

headerBackgroundColor

background-color

panelBorderColor

border-left-color

.rf-au-btn-arrow

This class defines styles for the button arrow.

No skin parameters.
.rf-au-btn-arrow-dis

This class defines styles for the button arrow when it is disabled.

No skin parameters.
.rf-au-lst-scrl

This class defines styles for the scrollbar in the auto-complete list.

No skin parameters.
.rf-au-itm

This class defines styles for an item in the auto-complete list.

No skin parameters.
.rf-au-itm-sel

This class defines styles for a selected item in the auto-complete list.

headerBackgroundColor

background-color

generalTextColor

border-color

.rf-au-shdw

This class defines styles for the auto-complete box shadow.

No skin parameters.
.rf-au-shdw-t, .rf-au-shdw-l, .rf-au-shdw-r, .rf-au-shdw-b

These classes define styles for the top, left, right, and bottom part of the auto-complete box shadow.

No skin parameters.
.rf-au-tbl

This class defines styles for a table in the auto-complete box.

No skin parameters.

The <rich:calendar> component allows the user to enter a date and time through an in-line or pop-up calendar. The pop-up calendar can navigate through months and years, and its look and feel can be highly customized.

Figure 8.2. <rich:calendar>


The <rich:calendar> component is presented as a pop-up by default, appearing as a text field with a button to expand the full pop-up calendar. To render the calendar in-line on the page instead, set popup="false. This displays the full calendar without the text field and display button.

To add keyboard support for manual input, set enableManualInput="true". To disable the calendar from any user input, set disabled="true".

To change the appearance of the display button from the standard calendar icon, use the buttonIcon and buttonDisabledIcon attributes to replace the icon with a specified file. Alternatively, use the buttonLabel attribute to display text on the button without an icon. If buttonLabel is specified then both the buttonIcon and buttonDisabledIcon attributes are ignored. To hide the text field box, set showInput="false".

The calendar features a Today button for locating today's date on the calendar. This can be set to three different values using the todayControlMode attribute:

To make the entire calendar read-only, set readonly="true". This allows months and years to be browsed through with the arrow controls, but dates and times cannot be selected.

Instead of using a data model, the <rich:calendar> component can be customized on the client-side using JavaScript. Use the dayClassFunction attribute to reference the function that determines the CSS style class for each day cell. Use the dayDisableFunction to reference the function that enables or disables a day cell. Example 8.4, “Client-side customization” demonstrates how client-side customization can be used to style different days in a calendar.


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

Class (selector)Skin ParametersMapped CSS properties
.rf-cal-extr

This class defines the styles for a pop-up calendar exterior.

panelBorderColor

border-color

.rf-cal-btn

This class defines styles for a calendar button.

No skin parameters.
.rf-cal-hdr

This class defines the styles for a calendar header.

panelBorderColor

border-bottom-color

additionalBackgroundColor

background-color

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-hdr-optnl

This class defines the styles for an optional header.

panelBorderColor

border-bottom-color

additionalBackgroundColor

background-color

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-hdr-month

This class defines the styles for the month header.

headerBackgroundColor

background-color

headerSizeFont

font-size

headerFamilyFont

font-family

headerWeightFont

font-weight

headerTextColor

color

.rf-cal-ftr

This class defines the styles for a calendar footer.

panelBorderColor

border-right-color, border-bottom-color

additionalBackgroundColor

background

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-ftr-optnl

This class defines the styles for an optional footer.

panelBorderColor

border-right-color, border-bottom-color

additionalBackgroundColor

background

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-tl

This class defines the styles for calendar toolbars.

headerBackgroundColor

background-color

headerSizeFont

font-size

headerFamilyFont

font-family

headerWeightFont

font-weight

headerTextColor

color

.rf-cal-tl-ftr

This class defines the styles for a toolbar item in the calendar footer.

additionalBackgroundColor

background

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-tl-btn

This class defines styles for a toolbar button.

No skin parameters.
.rf-cal-tl-btn-dis

This class defines styles for a disabled toolbar button.

No skin parameters.
.rf-cal-tl-btn-hov

This class defines the styles for toolbar items when it is hovered over with the mouse cursor.

calendarWeekBackgroundColor

background-color

generalTextColor

color

tableBackgroundColor

border-color

panelBorderColor

border-right-color, border-bottom-color

.rf-cal-tl-btn-press

This class defines the styles for toolbar items when it is pressed.

panelBorderColor

border-color

panelBorderColor

border-right-color, border-bottom-color

.rf-cal-tl-close

This class defines styles for a Close button in a toolbar.

No skin parameters.
.rf-cal-c

This class defines the styles for regular calendar cells.

panelBorderColor

border-bottom-color, border-right-color

tableBackgroundColor

background-color

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-c-cnt

This class defines styles for the content of a cell.

No skin parameters.
.rf-cal-today

This class defines the styles for the cell representing today's date.

calendarCurrentBackgroundColor

background-color

calendarCurrentTextColor

color

.rf-cal-sel

This class defines the styles for the selected day.

headerBackgroundColor

background-color

headerTextColor

color

.rf-cal-hov

This class defines the styles for a cell when it is hovered over with the mouse cursor.

calendarSpecBackgroundColor

background-color

calendarSpecTextColor

color

.rf-cal-week

This class defines the styles for week numbers.

panelBorderColor

border-bottom-color, border-right-color

calendarWeekBackgroundColor

background-color

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-holiday

This class defines the styles for weekends and holidays.

calendarHolidaysBackgroundColor

background-color

calendarHolidaysTextColor

color

.rf-cal-boundary-day

This class defines styles for an active boundary button.

No skin parameters.
.rf-cal-sp-inp

This class defines the styles for a spinner input field in the pop-up element for time selection.

buttonSizeFont

font-size

buttonFamilyFont

font-family

.rf-cal-sp-inp-cntr

This class defines the styles for a wrapper <td> element for a spinner input field in the pop-up element for time selection.

controlBackgroundColor

background-color

panelBorderColor

border-color

subBorderColor

border-right-color, border-bottom-color

.rf-cal-sp-btn

This class defines the styles for a wrapper <td> element for spinner buttons in the pop-up element for time selection.

headerBackgroundColor

background-color, border-color

.rf-cal-sp-up

This class defines styles for the Up spinner button.

No skin parameters.
.rf-cal-sp-down

This class defines styles for the Down spinner button.

No skin parameters.
.rf-cal-sp-press

This class defines styles for a spinner button when it is pressed.

No skin parameters.
.rf-cal-edtr-shdw

This class defines the styles for the calendar editor shadow.

tableBackgroundColor

background

.rf-cal-edtr-layout-shdw

This class defines the styles for the layout shadow of a calendar editor.

shadowBackgroundColor

background-color

.rf-cal-edtr-btn

This class defines styles for a button in the calendar editor.

No skin parameters.
.rf-cal-edtr-btn-over

This class defines the styles for the calendar editor button when it is hovered over with the mouse cursor.

panelBorderColor

border-color

calendarSpecBackgroundColor

background

.rf-cal-edtr-btn-sel

This class defines the styles for the calendar editor button when it is selected.

calendarCurrentBackgroundColor

background-color

calendarCurrentTextColor

color

.rf-cal-edtr-tl-over

This class defines the styles for a toolbar item in the calendar editor when it is hovered over with the mouse cursor.

additionalBackgroundColor

background

tableBackgroundColor

border-color

panelBorderColor

border-right-color, border-bottom-color

.rf-cal-edtr-tl-press

This class defines the styles for a toolbar item in the calendar editor when it is pressed.

additionalBackgroundColor

background

panelBorderColor

border-color

tableBackgroundColor

border-right-color, border-bottom-color

.rf-cal-time-inp

This class defines styles for the time input field.

No skin parameters.
.rf-cal-time-btn

This class defines the styles for a button in the pop-up element for the calendar's time section.

tableBackgroundColor

border-color

panelBorderColor

border-right-color, border-bottom-color

.rf-cal-time-btn-press

This class defines the styles for a pressed button in the pop-up element for the calendar's time section.

tableBackgroundColor

border-right-color, border-bottom-color

panelBorderColor

border-color

calendarWeekBackgroundColor

background-color

.rf-cal-timepicker-cnt

This class defines the styles for the content of the pop-up element during time selection.

panelBorderColor

border-color

additionalBackgroundColor

background

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-timepicker-inp

This class defines the styles for an input field in the time picker.

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-timepicker-ok

This class defines styles for the OK button in the time picker.

No skin parameters.
.rf-cal-timepicker-cancel

This class defines styles for the Cancel button in the time picker.

No skin parameters.
.rf-cal-monthpicker-cnt

This class defines the styles for the content of the pop-up element during month or year selection.

panelBorderColor

border-color

tableBackgroundColor

background

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-cal-monthpicker-ok

This class defines the styles for the OK button for the month picker.

additionalBackgroundColor

background

panelBorderColor

border-top-color

.rf-cal-monthpicker-cancel

This class defines the styles for the Cancel button for the month picker.

additionalBackgroundColor

background

panelBorderColor

border-top-color

.rf-cal-monthpicker-split

This class defines the styles for the splitter in the month picker.

panelBorderColor

border-right-color


The <rich:editor> component is used for creating a WYSIWYG editor on a page.

Figure 8.3. <rich:editor>


<rich:editor> component is based on the CKEditor implementation.

When rendering a <rich:editor>, a textarea is rendered to the page and once the page is completely loaded (ready state), the textarea is enhanced using a CKEditor script and replaced with a full-featured WYSIWYG editor.

The <rich:editor> is skinnable using the skin attribute and either of the two approaches:

By default, <rich:editor> has a skin called richfaces that is optimized to match rest of the component suite look & feel and changes to match the active RichFaces skin (refer to RichFaces Developer's Guide for details about Skinning and theming).

Example 8.6. The skin richfaces of <rich:editor>

Figure 8.4. 


A <rich:editor> with the default richfaces editor skin rendered against several RichFaces Skin options.


Alternatively, you can use any other CKeditor skin, either from the standard distribution, a downloaded skin, or a custom skin. In the distribution, there are three skins bundled: kama, v2, office2003.

Example 8.7. Examples of <rich:editor> skins in CKEditor distribution

Figure 8.5. 


A CKEditor distribution skins kama, v2 and office2003.


The <rich:editor> supports a toolbar attribute, which is able to change the configuration of the toolbar's button set. There are two configurations available: basic (default), full (enables all of the features).

It is also possible to define a custom toolbar using the CKEditor toolbar configuration in a config facet:


<rich:editor toolbar="CustomToolbar">
    <f:facet name="config">
        toolbar_CustomToolbar:
        [
        { name: 'document', items : [ 'NewPage','Preview' ] },
        { name: 'clipboard', items : [ 'Cut','Copy','Paste','-','Undo','Redo' ] },
        { name: 'editing', items : [ 'Find','Replace','-','SelectAll','-','Scayt' ] },
        { name: 'insert', items : [ 'Image', 'Flash', 'Table', 'HorizontalRule', 
                 'Smiley', 'SpecialChar', 'PageBreak', 'Iframe' ] },
                '/',
        { name: 'styles', items : [ 'Styles','Format' ] },
        { name: 'basicstyles', items : [ 'Bold','Italic','Strike','-','RemoveFormat' ] },
        { name: 'paragraph', items : [ 'NumberedList','BulletedList','-','Outdent','Indent','-','Blockquote' ] },
        { name: 'links', items : [ 'Link','Unlink','Anchor' ] },
        { name: 'tools', items : [ 'Maximize' ] }
        ]
        </f:facet>
</rich:editor>

Note that toolbar name (CustomToolbar) needs to match the toolbar_<name> configuration option.

The <rich:editor> comes with a lang attribute which allows you to change the localization of the editor. For language configuration options, refer to http://www.w3.org/TR/html4/struct/dirlang.html.

The lang attribute influences following settings:

  • underlying textarea - specifies the i18n settings for received and submitted content

  • editor value - specifies the i18n settings for value edited in WYSIWYG mode

  • default settings of localization of editor controls and interface

However the interface first localized using the browser configuration (usually determined by client system settings). To force the editor to use a specific localization for the interface, you use the advanced CKEditor configuration option language, as in following sample:


<rich:editor lang="fr" config="language: 'fr'" />

The above sample forces the editor to use a french interface, suppressing the browser preferred settings.

The <rich:fileUpload> component allows the user to upload files to a server. It features multiple uploads, progress bars, restrictions on file types, and restrictions on sizes of the files to be uploaded.

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

Class (selector)Skin ParametersMapped CSS properties
.rf-fu

This class defines styles for the file upload control.

generalBackgroundColor

background-color

panelBorderColor

border-color

.rf-fu-hdr

This class defines styles for the header of the file upload control.

headerBackgroundColor

background-color, border-color

.rf-fu-lst

This class defines styles for lists in the file upload control.

No skin parameters.
.rf-fu-cntr-hdn

This class defines styles for the file upload container when it is hidden.

No skin parameters.
.rf-fu-btns-lft, .rf-fu-btns-rgh

These classes define styles for buttons on the left and right of the file upload control.

No skin parameters.
.rf-fu-btn-add

This class defines styles for the Add button in the file upload control.

trimColor

background-color

panelBorderColor

border-color

.rf-fu-btn-cnt-add

This class defines styles for the content of the Add button in the file upload control.

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-fu-btn-add-dis

This class defines styles for the Add button in the file upload control when it is disabled.

tableFooterBackgroundColor

background-color

tableFooterBackgroundColor

border-color

.rf-fu-btn-cnt-add-dis

This class defines styles for the content of the Add button in the file upload control when it is disabled.

tabDisabledTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-fu-btn-upl

This class defines styles for the Upload button in the file upload control.

trimColor

background-color

panelBorderColor

border-color

.rf-fu-btn-cnt-upl

This class defines styles for the content of the Upload button in the file upload control.

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-fu-btn-clr

This class defines styles for the Clear button in the file upload control.

trimColor

background-color

panelBorderColor

border-color

.rf-fu-btn-cnt-clr

This class defines styles for the content of the Clear button in the file upload control.

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-fu-itm

This class defines styles for an item in the file upload control.

panelBorderColor

border-bottom-color

.rf-fu-itm-lft, .rf-fu-itm-rgh

These classes define styles for items on the left and right of the file upload control.

No skin parameters.
.rf-fu-itm-lbl

This class defines styles for the label of an item in the file upload control.

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-fu-itm-st

This class defines styles for the status of an item in the file upload control.

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-fu-itm-lnk

This class defines styles for a link item in the file upload control.

generalLinkColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-fu-inp

This class defines styles for the input field in the file upload control.

No skin parameters.
.rf-fu-inp-cntr

This class defines styles for the input field container in the file upload control.

No skin parameters.

The <rich:inplaceInput> component allows information to be entered in-line in blocks of text, improving readability of the text. Multiple input regions can be navigated with keyboard navigation. The component has three functional states: the view state, where the component displays its initial setting, such as "click to edit"; the edit state, where the user can input text; and the "changed" state, where the new value for the component has been confirmed but can be edited again if required.

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

Class (selector)Skin ParametersMapped CSS properties
.rf-ii-d-s

This class defines styles for the in-place input when it is in the default state.

editorBackgroundColor

background-color

generalTextColor

border-bottom-color

.rf-ii-e-s

This class defines styles for the in-place input when it is in the editing state.

No skin parameters.
.rf-ii-c-s

This class defines styles for the in-place input when it is in the changed state.

No skin parameters.
.rf-ii-dis-s

This class defines styles for the in-place input when it is in the disabled state.

No skin parameters.
.rf-ii-fld

This class defines styles for the in-place input field.

editBackgroundColor

background-color, border-bottom-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-ii-dflt-lbl

This class defines styles for the default label of the in-place input.

No skin parameters.
.rf-ii-edit

This class defines styles for the in-place input when it is being edited.

No skin parameters.
.rf-ii-btn

This class defines styles for the buttons for the in-place input.

tabBackgroundColor

background-color

panelBorderColor

border-color

.rf-ii-btn-p

This class defines styles for the buttons for the in-place input when they are pressed.

tabBackgroundColor

background-color

panelBorderColor

border-color

.rf-ii-btn-set, .rf-ii-btn-prepos, .rf-ii-btn-pos

These classes define the positioning of the buttons.

No skin parameters.
.rf-ii-btn-shdw

This class defines styles for the button shadows for the in-place input.

No skin parameters.
.rf-ii-btn-shdw-t, .rf-ii-btn-shdw-b, .rf-ii-btn-shdw-l, .rf-ii-btn-shdw-r

These classes define the top, bottom, left, and right edge of the button shadows.

No skin parameters.
.rf-ii-none

This class defines styles for the in-place input when it cannot be edited.

No skin parameters.

The <rich:inplaceSelect> component is similar to the <rich:inplaceInput> component, except that the <rich:inplaceSelect> component uses a drop-down selection box to enter text instead of a regular text field. Changes can be rendered either in-line or for the whole block, and inputs can be focused with keyboard navigation. The component is based on the JSF UISelectOne component, so all the standard rules for value definition, processing, conversion, and validation apply.

The component has three functional states:

Figure 8.6. <rich:inplaceSelect>


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

Class (selector)Skin ParametersMapped CSS properties
.rf-is-d-s

This class defines styles for the in-place select when it is in the default state.

editorBackgroundColor

background-color

generalTextColor

border-bottom-color

.rf-is-e-s

This class defines styles for the in-place select when it is in the editing state.

No skin parameters.
.rf-is-c-s

This class defines styles for the in-place select when it is in the changed state.

No skin parameters.
.rf-is-dis-s

This class defines styles for the in-place select when it is in the disabled state.

No skin parameters.
.rf-is-fld

This class defines styles for the in-place select field.

editBackgroundColor

background

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-is-opt

This class defines styles for an option for the in-place select.

generalTextColor

border-color

.rf-is-sel

This class defines styles for the selected option of the in-place select.

generalTextColor

border-color

.rf-is-lbl

This class defines styles for the label of the in-place select.

No skin parameters.
.rf-is-dflt-lbl

This class defines styles for the default label of the in-place select.

No skin parameters.
.rf-is-edit

This class defines styles for the in-place select when it is being edited.

No skin parameters.
.rf-is-btn

This class defines styles for the buttons for the in-place select.

tabBackgroundColor

background-color

panelBorderColor

border-color

.rf-is-btn-p

This class defines styles for the buttons for the in-place select when they are pressed.

tabBackgroundColor

background-color

panelBorderColor

border-color

.rf-is-btn-set, .rf-is-btn-prepos, .rf-is-btn-pos

These classes define the positioning of the buttons.

No skin parameters.
.rf-is-lst-pos

This class defines the positioning of the list.

No skin parameters.
.rf-is-lst-dec

This class defines styles for a decreasing list for the in-place select.

editBackgroundColor

background-color

panelBorderColor

border-color

.rf-is-lst-scrl

This class defines styles for the list scrollbar.

No skin parameters.
.rf-is-shdw

This class defines styles for the in-place select shadow.

No skin parameters.
.rf-is-shdw-t, .rf-is-shdw-b, .rf-is-shdw-l, .rf-is-shdw-r

These classes define the top, bottom, left, and right edge of the in-place select shadows.

No skin parameters.
.rf-is-btn-shdw

This class defines styles for the button shadows for the in-place select.

No skin parameters.
.rf-is-none

This class defines styles for the in-place select when it cannot be edited.

No skin parameters.

The <rich:inputNumberSlider> component provides a slider for changing numerical values. Optional features include control arrows to step through the values, a tool-tip to display the value while sliding, and a text field for typing the numerical value which can then be validated against the slider's range.

Figure 8.7. <rich:inputNumberSlider>


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

Class (selector)Skin ParametersMapped CSS properties
.rf-insl

This class defines styles for the number slider itself.

No skin parameters.
.rf-insl-trc

This class defines styles for the number slider track.

controlBackgroundColor

background-color

panelBorderColor

border-bottom-color

.rf-insl-trc-cntr

This class defines styles for the container of the number slider track.

No skin parameters.
.rf-insl-mn

This class defines styles for the minimum label on the number slider.

generalSizeFont

font-size

generalFamilyFont

font-family

generalTextColor

color

panelBorderColor

border-left-color

.rf-insl-mx

This class defines styles for the maximum label on the number slider.

generalSizeFont

font-size

generalFamilyFont

font-family

generalTextColor

color

panelBorderColor

border-right-color

.rf-insl-inp

This class defines styles for the input field on the number slider.

generalSizeFont

font-size

generalFamilyFont

font-family

generalTextColor

color

.rf-insl-inp-cntr

This class defines styles for the container of the input field.

No skin parameters.
.rf-insl-hnd

This class defines styles for the handle on the number slider.

No skin parameters.
.rf-insl-hnd-cntr

This class defines styles for the container of the handle.

No skin parameters.
.rf-insl-hnd-sel

This class defines styles for the handle when it is selected.

No skin parameters.
.rf-insl-hnd-dis

This class defines styles for the handle when it is selected.

No skin parameters.
.rf-insl-dec, .rf-insl-inc

These classes define styles for the step controls to decrease and increase the number.

No skin parameters.
.rf-insl-dec-sel, .rf-insl-inc-sel

These classes define styles for the step controls when they are selected.

No skin parameters.
.rf-insl-dec-dis, .rf-insl-inc-dis

These classes define styles for the step controls when they are disabled.

No skin parameters.
.rf-insl-tt

This class defines styles for the tool-tip on the number slider.

generalSizeFont

font-size

generalFamilyFont

font-family

generalTextColor

color

tipBorderColor

border

tipBackgroundColor

background-color


The <rich:inputNumberSpinner> component is a single-line input field with buttons to increase and decrease a numerical value. The value can be changed using the corresponding directional keys on a keyboard, or by typing into the field.

Figure 8.8. <rich:inputNumberSpinner>


The <rich:select> component provides a drop-down list box for selecting a single value from multiple options. The <rich:select> component can be configured as a combo-box, where it will accept typed input. The component also supports keyboard navigation. The <rich:select> component functions similarly to the JSF UISelectOne component.

Figure 8.9. <rich:select>


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

Class (selector)Skin ParametersMapped CSS properties
.rf-sel

This class defines styles for the select control itself.

No skin parameters.
.rf-sel-cntr

This class defines styles for the container of the select control.

panelBorderColor

border-color

.rf-sel-inp

This class defines styles for the select control input field.

controlBackgroundColor

background-color

.rf-sel-fld-err

This class defines styles for the input field when an error occurs.

No skin parameters.
.rf-sel-opt

This class defines styles for an option in the select control.

generalTextColor

color

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-sel-sel

This class defines styles for the selected option of the select control.

generalTextColor

border-color

.rf-sel-dflt-lbl

This class defines styles for the default label of the select control.

No skin parameters.
.rf-sel-btn

This class defines styles for the button of the select control.

headerBackgroundColor

background-color

panelBorderColor

border-left-color

.rf-sel-btn-arrow

This class defines styles for the arrow on the button.

No skin parameters.
.rf-sel-btn-dis

This class defines styles for the button of the select control when it is disabled.

No skin parameters.
.rf-sel-lst-scrl

This class defines styles for the list scrollbar.

No skin parameters.
.rf-sel-shdw

This class defines styles for the select control shadow.

No skin parameters.
.rf-sel-shdw-t, .rf-sel-shdw-b, .rf-sel-shdw-l, .rf-sel-shdw-r

These classes define the top, bottom, left, and right edge of the select control shadows.

No skin parameters.

The <rich:orderingList> is a component for ordering items in a list (client-side).

Figure 8.10. <rich:select>


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

Class (selector)Skin ParametersMapped CSS properties
.rf-ord

This class defines styles for the orderingList control itself.

No skin parameters.
.rf-ord-cntr

This class defines styles for the container of the orderingList control.

No skin parameters.
.rf-ord-cptn

This class defines styles for the caption of the orderingList control.

headerTextColor

color

headerSizeFont

font-size

headerFamilyFont

font-family

headerWeightFont

font-weight

.rf-ord-lst

This class defines styles for the items list of the orderingList control.

No skin parameters.
.rf-ord-hdr

This class defines styles for the header of the items list.

headerBackgroundColor

background-color

headerTextColor

color

headerSizeFont

font-size

headerFamilyFont

font-family

headerWeightFont

font-weight

.rf-ord-opt

This class defines styles for an option in the orderingList control.

generalTextColor

color

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-ord-sel

This class defines styles for the selected option of the orderingList control.

generalTextColor

border-color

.rf-ord-dflt-lbl

This class defines styles for the default label of the orderingList control.

No skin parameters.
.rf-ord-btn

This class defines styles for the button of the orderingList control.

headerBackgroundColor

background-color

panelBorderColor

border-left-color

.rf-ord-btn-dis

This class defines styles for the button of the orderingList control when it is disabled.

No skin parameters.
.rf-ord-lst-scrl

This class defines styles for the list scrollbar.

No skin parameters.

The <rich:pickList> is a component for selecting items from a list. Additionally, it allows for the selected items to be ordered (client-side). From the client side perspective, items are added/removed from the source list, and removed/added to the target list. However it is important to note that the server-side source of items is never modified, and always represents the list of all items available for selection. If the list of unselected items is required, it can be determined by subtracting the collection of all selected items from the collection of all available items.

Figure 8.11. <rich:select>


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

Class (selector)Skin ParametersMapped CSS properties
.rf-pick

This class defines styles for the pickList control itself.

No skin parameters.
.rf-pick-cntr

This class defines styles for the container of the pickList control.

No skin parameters.
.rf-pick-src-cptn, .rf-pick-tgt-cptn

These classes define styles for the source and target captions of the pickList control.

headerTextColor

color

headerSizeFont

font-size

headerFamilyFont

font-family

headerWeightFont

font-weight

.rf-pick-lst

This class defines styles for the items list of the pickList control.

No skin parameters.
.rf-pick-hdr

This class defines styles for the header of the items list.

headerBackgroundColor

background-color

headerTextColor

color

headerSizeFont

font-size

headerFamilyFont

font-family

headerWeightFont

font-weight

.rf-pick-opt

This class defines styles for an option in the pickList control.

generalTextColor

color

generalSizeFont

font-size

generalFamilyFont

font-family

.rf-pick-sel

This class defines styles for the selected option of the pickList control.

generalTextColor

border-color

.rf-pick-dflt-lbl

This class defines styles for the default label of the pickList control.

No skin parameters.
.rf-pick-btn

This class defines styles for the button of the pickList control.

headerBackgroundColor

background-color

panelBorderColor

border-left-color

.rf-pick-btn-dis

This class defines styles for the button of the pickList control when it is disabled.

No skin parameters.
.rf-pick-lst-scrl

This class defines styles for the list scrollbar.

No skin parameters.

This chapter details those components which act as panels and containers to hold groups of other components.

The <rich:panel> component is a bordered panel with an optional header.

Figure 9.1. <rich:panel>


The <rich:accordion> is a series of panels stacked on top of each other, each collapsed such that only the header of the panel is showing. When the header of a panel is clicked, it is expanded to show the content of the panel. Clicking on a different header will collapse the previous panel and epand the selected one. Each panel contained in a <rich:accordion> component is a <rich:accordionItem> component.

Figure 9.3. A <rich:accordion> component containing three <rich:accordionItem> components


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

Class (selector)Skin ParametersMapped CSS properties
.rf-ac

This class defines styles for the accordion control itself.

panelBorderColor

border-color

generalBackgroundColor

background

.rf-ac-itm-hdr

This class defines styles for the header of an accordion item.

panelBorderColor

border-bottom-color

headerBackgroundColor

background-color

headerTextColor

color

headerWeightFont

font-weight

headerFamilyFont

font-family

headerSizeFont

font-size

.rf-ac-itm-hdr-act, .rf-ac-itm-hdr-inact

These classes define styles for the header when the item is either active (expanded) or inactive (collapsed).

No skin parameters.
.rf-ac-itm-hdr-dis

This class defines styles for the header when it is disabled.

tabDisabledTextColor

color

.rf-ac-itm-gr

This class defines styles for an item group.

No skin parameters.
.rf-ac-itm-cnt

This class defines styles for the content of an accordion item.

panelBorderColor

border-bottom-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-ac-itm-ico

This class defines styles for the item icon.

No skin parameters.
.rf-ac-itm-exp-ico

This class defines styles for the expanded icon for an item.

No skin parameters.
.rf-ac-itm-ico-act, .rf-ac-itm-ico-inact

These classes define styles for the icon when the item is either active (expanded) or inactive (collapsed).

No skin parameters.
.rf-ac-itm-lbl

This class defines styles for the item label.

No skin parameters.
.rf-ac-itm-lbl-act, .rf-ac-itm-lbl-inact

These classes define styles for the label when the item is either active (expanded) or inactive (collapsed).

No skin parameters.

The <rich:collapsiblePanel> component is a collapsible panel that shows or hides content when the header bar is activated. It is a simplified version of <rich:togglePanel> component.

Figure 9.4. <rich:collapsiblePanel>


The <rich:popupPanel> component provides a pop-up panel or window that appears in front of the rest of the application. The <rich:popupPanel> component functions either as a modal window which blocks interaction with the rest of the application while active, or as a non-modal window. It can be positioned on the screen, dragged to a new position by the user, and re-sized.

If show="true" then the pop-up panel will display when the page is first loaded.

The <rich:popupPanel> component can be shown and hidden manually using the show() and hide() methods from the JavaScript API. These can be implemented using two different approaches:

For explicit referencing when using the functions, the component can be given an id identifier.

Example 9.2, “<rich:popupPanel> example” demonstrates basic use of both the <rich:componentControl> component and the rich:component function to show and hide the <rich:popupPanel> component.


Placement

The <rich:popupPanel> component is usually rendered in front of any other objects on the page. This is achieved by attaching the component to the <body> element of the page, and setting a very high "z-index" (the stack order of the object). This approach is taken because relatively-positioned elements could still overlap the pop-up panel if they exist at higher levels of the DOM hierarchy, even if their z-index is less than the <rich:popupPanel> component.

If the <rich:popupPanel> is to participate in submitting child components/behaviors, then a form element must be nested within the <rich:popupPanel>. Alternatively, if no overlapping elements exist, the <rich:popupPanel> component can be reattached to its original DOM element by setting domElementAttachment to either parent or form.

The <rich:tabPanel> component provides a set of tabbed panels for displaying one panel of content at a time. The tabs can be highly customized and themed. Each tab within a <rich:tabPanel> container is a <rich:tab> component. Refer to Section 9.5.7, “<rich:tab>” for further details on the <rich:tab> component.

Figure 9.6. A <rich:tabPanel> component containing three <rich:tab> components


Form elements required

All <rich:tabPanel> components should be wrapped in a form element when using either ajax or server mode, as usual for submitting components.

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

Class (selector)Skin ParametersMapped CSS properties
.rf-tab-hdr

This class defines styles for a tab header.

panelBorderColor

border

tabBackgroundColor

background-color

generalTextColor

color

.rf-tab-hdr-act

This class defines styles for a tab header when it is active.

additionalBackgroundColor

background-color

.rf-tab-hdr-inact

This class defines styles for a tab header when it is inactive.

No skin parameters.
.rf-tab-hdr-dis

This class defines styles for a tab header when it is disabled.

tabDisabledTextColor

color

.rf-tab-hdr-tabline-vis

This class defines styles for the header tab line when it is visible.

additionalBackgroundColor

background-color

panelBorderColor

border-color

.rf-tab-hdr-tabs

This class defines styles for the tabs in the header.

No skin parameters.
.rf-tab-hdr-spcr

This class defines styles for the tab header spacer.

panelBorderColor

border-bottom

.rf-tab-lbl

This class defines styles for the tab label.

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-tab-hdn

This class defines styles for the tab when it is hidden.

No skin parameters.
.rf-tab-hdr-scrl-lft, .rf-tab-hdr-scrl-rgh

These classes define styles for the left and right controls for the tab header scroller.

additionalBackgroundColor

background

panelBorderColor

border

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-tab-hdr-tablst

This class define styles for the tab header list.

additionalBackgroundColor

background

panelBorderColor

border

generalFamilyFont

font-family

.rf-tab-hdr-brd

This class define styles for the tab header border.

tabBackgroundColor

background

panelBorderColor

border

.rf-tab-cnt

This class define styles for the content of the tab panel.

generalBackgroundColor

background

panelBorderColor

border

generalFamilyFont

font-family

generalSizeFont

font-size


The <rich:tab> component represents an individual tab inside a <rich:tabPanel> component, including the tab's content. Clicking on the tab header will bring its corresponding content to the front of other tabs.

The <rich:togglePanel> component is used as a base for the other switchable components, the <rich:accordion> component and the <rich:tabPanel> component. It provides an abstract switchable component without any associated markup. As such, the <rich:togglePanel> component could be customized to provide a switchable component when neither an accordion component or a tab panel component is appropriate.

The <rich:togglePanel> component acts as a wrapper for multiple <rich:togglePanelItem> components. Each child component is displayed after being activated with the <rich:toggleControl> behavior.

Refer to Section 9.6.6, “<rich:toggleControl>” and Section 9.6, “<rich:togglePanel>” for details on how to use the components together.

The <rich:toggleControl> behavior can be attached to any interface component, whether inside or outside the controlled panel itself. It works with a <rich:togglePanel> component to switch between different <rich:togglePanelItem> components. Refer to Section 9.6, “<rich:togglePanel>” and Section 9.6.7, “<rich:togglePanelItem>” for details on how to use the components together.

The <rich:toggleControl> implements the JSF BehaviorHolder component, which provides events to attached components and behaviors.

The <rich:toggleControl> component can switch the attached <rich:togglePanel> component in multiple ways:

This chapter covers all components related to the display of tables and grids.

The non-visual <a4j:repeat> component is used to iterate through a data model. The component renders child content for every iteration according to the current object data.

The <a4j:repeat> component extends the standard UIRepeat component to allow partial updates within iterations while sending Ajax requests. The component acts as a base for all the data iteration components detailed in this chapter.

The <a4j:repeat> component uses other attributes common to iteration components, such as the first attribute for specifying the first item for iteration, and the rows attribute for specifying the number of rows of items to display.

Specific cells, rows, and columns can be updated without sending Ajax requests for the entire collection. Components that cause the change can specify which part of the table to update through the render attribute. The render attribute specifies which part of a table to update. The updated parts relate to where the action component is placed relative to the table:

The <rich:dataTable> component is used to render a table, including the table's caption. It works in conjunction with the <rich:column> and <rich:columnGroup> components to list the contents of a data model.

The first attribute specifies which item in the data model to start from, and the rows attribute specifies the number of items to list. The header, footer, and caption facets can be used to display text, and to customize the appearance of the table through skinning. demonstrates a simple table implementation.

The keepSaved attribute defines whether this iteration component will reset saved children's state before rendering. By default, the state is reset if there are no faces messages with severity error or higher.


For details on filtering and sorting data tables, refer to Section 10.10, “Table filtering” and Section 10.11, “Table sorting”.

As <rich:dataTable> the component is based on the <a4j:repeat> component, it can be partially updated with Ajax. Refer to Section 10.1.2, “Limited views and partial updates” for details on partially updating the <rich:dataTable> component.

The <rich:dataTable> component supports master-detail markup with collapsible sub-table sections. Refer to Section 10.5, “<rich:collapsibleSubTable>” for full details on using the <rich:collapsibleSubTable> component.

Use the rows attribute to specify the number of rows to show at a time. The table is then presented in pages of rows. Pages can be navigated by using a control such as the <rich:dataScroller> component. Refer to Section 10.9, “<rich:dataScroller>” for full details on using the <rich:dataScroller> component.

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

Class (selector)Skin ParametersMapped CSS properties
.rf-dt

This class defines styles for the table.

tableBackgroundColor

background-color

tableBorderWidth

border-left-width, border-top-width

tableBorderColor

border-left-color, border-top-color

.rf-dt-cap

This class defines styles for the table caption.

No skin parameters.
.rf-dt-r

This class defines styles for a table row.

No skin parameters.
.rf-dt-fst-r

This class defines styles for the first row in a table.

No skin parameters.
.rf-dt-c

This class defines styles for a table cell.

tableBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-dt-nd

This class defines styles for a node.

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-dt-hdr

This class defines styles for a table header.

No skin parameters.
.rf-dt-hdr-fst

This class defines styles for the first header.

No skin parameters.
.rf-dt-hdr-c

This class defines styles for a header cell.

tableHeaderBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

tableHeaderTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-dt-shdr

This class defines styles for a table sub-header.

No skin parameters.
.rf-dt-shdr-fst

This class defines styles for the first sub-header.

No skin parameters.
.rf-dt-shdr-c

This class defines styles for a sub-header cell.

tableHeaderBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

tableHeaderTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-dt-ftr

This class defines styles for a table footer.

No skin parameters.
.rf-dt-ftr-fst

This class defines styles for the first footer.

No skin parameters.
.rf-dt-ftr-c

This class defines styles for a footer cell.

tableFooterBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-dt-sftr

This class defines styles for a table sub-footer.

No skin parameters.
.rf-dt-sftr-fst

This class defines styles for the first sub-footer.

No skin parameters.
.rf-dt-sftr-c

This class defines styles for a sub-footer cell.

tableFooterBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size


The <rich:column> component facilitates columns in a table. It supports merging columns and rows, sorting, filtering, and customized skinning.

The <rich:columnGroup> component combines multiple columns in a single row to organize complex parts of a table. The resulting effect is similar to using the breakRowBefore attribute of the <rich:column> component, but is clearer and easier to follow in the source code.

The <rich:columnGroup> can also be used to create complex headers in a table. Example 10.8, “Complex headers using column groups” and the resulting Figure 10.5, “Complex headers using column groups” demonstrate how complex headers can be achieved.

Example 10.8. Complex headers using column groups


The <rich:collapsibleSubTable> component acts as a child element to a <rich:dataTable> component. The <rich:collapsibleSubTable> component iterates through the child collections in the currently iterated object to create master-detail tables.

Additionally, the detail part of the table can be collapsed or expanded through different modes. The <rich:collapsibleSubTable> component works with the <rich:collapsibleSubTableToggler> component, which expands and collapses the sub-tables.

The <rich:collapsibleSubTable> component requires the same basic attributes as the <rich:dataTable> component. The value attribute points to the collection, and the var attribute specifies a variable to use when iterating through the collection.

In addition, the <rich:collapsibleSubTable> component typically needs a corresponding <rich:collapsibleSubTableToggler> component to allow expanding and collapsing. Declare the id identifier on the <rich:collapsibleSubTable> element so that the <rich:collapsibleSubTableToggler> component can reference it. Refer to Section 10.5.5, “<rich:collapsibleSubTableToggler>” for details on the <rich:collapsibleSubTableToggler> component.

Example 10.9. Basic usage


<rich:dataTable value="#{carsBean.inventoryVendorLists}" var="list">
   <f:facet name="header">
      <rich:columnGroup>
         <rich:column colspan="6">
            <h:outputText value="Cars marketplace" />
         </rich:column>
         <rich:column breakRowBefore="true">
            <h:outputText value="Model" />
         </rich:column>
         <rich:column>
            <h:outputText value="Price" />
         </rich:column>
         <rich:column>
            <h:outputText value="Mileage" />
         </rich:column>
         <rich:column>
            <h:outputText value="VIN Code" />
         </rich:column>
         <rich:column>
            <h:outputText value="Items stock" />
         </rich:column>
         <rich:column>
            <h:outputText value="Days Live" />
         </rich:column>
      </rich:columnGroup>
   </f:facet>
   <rich:column colspan="6">
      <rich:collapsibleSubTableToggler for="sbtbl" />
      <h:outputText value="#{list.vendor}" />
   </rich:column>
   <rich:collapsibleSubTable value="#{list.vendorItems}" var="item" id="sbtbl"
      expandMode="client">
      <rich:column>
         <h:outputText value="#{item.model}" />
      </rich:column>
      <rich:column>
         <h:outputText value="#{item.price}" />
      </rich:column>
      <rich:column>
         <h:outputText value="#{item.mileage}" />
      </rich:column>
      <rich:column>
         <h:outputText value="#{item.vin}" />
      </rich:column>
      <rich:column>
         <h:outputText value="#{item.stock}" />
      </rich:column>
      <rich:column>
         <h:outputText value="#{item.daysLive}" />
      </rich:column>
      <f:facet name="footer">
         <h:outputText value="Total of #{list.vendor} Cars: #{list.count}" />
      </f:facet>
   </rich:collapsibleSubTable>
</rich:dataTable>

The resulting tables contains multiple sub-tables, grouping the list of cars by vendor. Each sub-table can be expanded or collapsed using the toggle with the vendor's name. The screenshot shows all sub-tables collapsed except for the sub-table for Ford cars.


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

Class (selector)Skin ParametersMapped CSS properties
.rf-cst

This class defines styles for the table.

No skin parameters.
.rf-cst-r

This class defines styles for a table row.

No skin parameters.
.rf-cst-fst-r

This class defines styles for the first row in a table.

No skin parameters.
.rf-cst-c

This class defines styles for a table cell.

tableBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-cst-hdr

This class defines styles for a table header.

No skin parameters.
.rf-cst-hdr-fst

This class defines styles for the first header.

No skin parameters.
.rf-cst-hdr-fst-r

This class defines styles for the first row in the header.

No skin parameters.
.rf-cst-hdr-c

This class defines styles for a header cell.

tableSubHeaderBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-cst-shdr

This class defines styles for a table sub-header.

No skin parameters.
.rf-cst-shdr-fst

This class defines styles for the first sub-header.

No skin parameters.
.rf-cst-shdr-c

This class defines styles for a sub-header cell.

tableSubHeaderBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-cst-ftr

This class defines styles for a table footer.

No skin parameters.
.rf-cst-ftr-fst

This class defines styles for the first footer.

No skin parameters.
.rf-cst-ftr-c

This class defines styles for a footer cell.

tableSubFooterBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-cst-sftr

This class defines styles for a table sub-footer.

No skin parameters.
.rf-cst-sftr-fst

This class defines styles for the first sub-footer.

No skin parameters.
.rf-cst-sftr-c

This class defines styles for a sub-footer cell.

tableSubFooterBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size


The <rich:collapsibleSubTableToggler> component provides a toggle control for the user to expand and collapse sub-tables.

The <rich:collapsibleSubTableToggler> component requires the for attribute. The for attribute references the id identifier of the <rich:collapsibleSubTable> component to control.

Refer to Example 10.9, “Basic usage” for an example using the <rich:collapsibleSubTable> component. In the example, the toggle control is placed in a column that spans the width of the table. Output text next to the toggle control displays the car vendor's name for that sub-table.

The <rich:extendedDataTable> component builds on the functionality of the <rich:dataTable> component, adding features such as scrolling for the table body (both horizontal and vertical), Ajax loading for vertical scrolling, frozen columns, row selection, and rearranging of columns. It also supports all the basic table features such as sorting, filtering, and paging using the <rich:dataScroller> component.

The <rich:extendedDataTable> component includes the following main attributes not included in the <rich:dataTable> component:

Example 10.10. <rich:extendedDataTable> example

This example <rich:extendedDataTable> component demonstrates horizontal and vertical scrolling and frozen columns. Each feature is detailed in this section.


<rich:extendedDataTable value="#{carsBean.allInventoryItems}"
                        var="car" id="table" frozenColumns="2"
                        style="height:300px; width:500px;" selectionMode="none">
   <f:facet name="header">
      <h:outputText value="Cars marketplace" />
   </f:facet>
   <rich:column>
      <f:facet name="header">
         <h:outputText value="vendor" />
      </f:facet>
      <h:outputText value="#{car.vendor}" />
   </rich:column>
   <rich:column>
      <f:facet name="header">
         <h:outputText value="Model" />
      </f:facet>
      <h:outputText value="#{car.model}" />
   </rich:column>
   <rich:column>
      <f:facet name="header">
         <h:outputText value="Price" />
      </f:facet>
      <h:outputText value="#{car.price}" />
   </rich:column>
   <rich:column>
      <f:facet name="header">
         <h:outputText value="Mileage" />
      </f:facet>
      <h:outputText value="#{car.mileage}" />
   </rich:column>
   <rich:column>
      <f:facet name="header">
         <h:outputText value="VIN Code" />
      </f:facet>
      <h:outputText value="#{car.vin}" />
   </rich:column>
   <rich:column>
      <f:facet name="header">
         <h:outputText value="Items stock" />
      </f:facet>
      <h:outputText value="#{car.stock}" />
   </rich:column>
   <rich:column>
      <f:facet name="header">
         <h:outputText value="Days Live" />
      </f:facet>
      <h:outputText value="#{car.daysLive}" />
   </rich:column>
</rich:extendedDataTable>

The example table shown in Example 10.10, “<rich:extendedDataTable> example” features both horizontal and vertical scrolling. Scrolling occurs automatically when the contents of the table exceed the dimensions specified with the height and width attributes. Headers and footers remain in place and visible when the table is scrolled.

Large tables can use Ajax "lazy" loading to cache data on the client during scrolling. Use the clientRows attribute to specify the number of rows to load. The specified number of rows are loaded on the initial rendering and with every vertical scroll. If the clientRows attribute is not specified, all the rows are loaded on the client without the use of Ajax.

In addition to Ajax scrolling, the <rich:extendedDataTable> component can also be used with the <rich:dataScroller> component in the same way as a regular <rich:dataTable> component. If both the clientRows and rows attributes are included, Ajax loading occurs as defined by the clientRows attribute, but the loading is limited to the current table page as determined by the rows attribute. Refer to Section 10.9, “<rich:dataScroller>” for full details on using the <rich:dataScroller> component.

The example table shown in Example 10.10, “<rich:extendedDataTable> example” has the first two columns frozen so that they remain visible if the user scrolls horizontally through the table. Note that the horizontal scrollbar does not encompass these frozen columns. To freeze columns, use the frozenColumns attribute to specify the number of columns on the left-hand side of the table to freeze.

Row selection is determined by the selectionMode attribute. Setting the attribute to none allows for no row selection capability. The example table shown in Example 10.10, “<rich:extendedDataTable> example” does not allow row selection.

Setting the selectionMode attribute to single allows the user to select a single row at a time using the mouse. With the selectionMode attribute set to multiple, the user can select multiple rows. Holding down the Ctrl key while clicking selects additional rows with each click. Holding down the Shift key while clicking selects all the rows in a range.

The selection attribute points to a collection of objects. It holds the rowKey identifiers to track which rows are selected. Example 10.11, “Selecting multiple rows” shows how to implement multiple row selection in the same table from Example 10.10, “<rich:extendedDataTable> example”.

Example 10.11. Selecting multiple rows


<rich:extendedDataTable value="#{extTableSelectionBean.inventoryItems}" 
                        var="car" selection="#{extTableSelectionBean.selection}"
                        id="table" frozenColumns="2" 
                        style="height:300px; width:500px;" selectionMode="multiple">
   ...

The accompanying ExtSelectionBean bean handles which rows are selected. The rows are identified by their rowKey identifiers.

package org.richfaces.demo.tables;


import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import javax.faces.bean.ManagedBean;
import javax.faces.bean.ManagedProperty;
import javax.faces.bean.SessionScoped;
import javax.faces.event.AjaxBehaviorEvent;
import org.richfaces.component.UIExtendedDataTable;
import org.richfaces.demo.tables.model.cars.InventoryItem;
@ManagedBean
@SessionScoped
public class ExtTableSelectionBean implements Serializable{
   private Collection<Object> selection;
   @ManagedProperty(value = "#{carsBean.allInventoryItems}")
   private List<InventoryItem> inventoryItems;
   private List<InventoryItem> selectionItems = new ArrayList<InventoryItem>();
   public void selectionListener(AjaxBehaviorEvent event){
      UIExtendedDataTable dataTable = (UIExtendedDataTable)event.getComponent();
      Object originalKey = dataTable.getRowKey();
      selectionItems.clear();
      for (Object selectionKey: selection) {
         dataTable.setRowKey(selectionKey);
         if (dataTable.isRowAvailable()){
            selectionItems.add((InventoryItem)dataTable.getRowData());
         }
      }
      dataTable.setRowKey(originalKey);
   }
   public Collection<Object> getSelection() {
      return selection;
   }
   public void setSelection(Collection<Object> selection) {
      this.selection = selection;
   }
   public List<InventoryItem> getInventoryItems() {
      return inventoryItems;
   }
   public void setInventoryItems(List<InventoryItem> inventoryItems) {
      this.inventoryItems = inventoryItems;
   }
   public List<InventoryItem> getSelectionItems() {
      return selectionItems;
   }
   public void setSelectionItems(List<InventoryItem> selectionItems) {
      this.selectionItems = selectionItems;
   }
}

Columns in a <rich:extendedDataTable> component can be rearranged by the user by dragging each column to a different position. A graphical representation of the column is displayed during dragging. Figure 10.6, “Dragging columns” illustrates the Price column being dragged to a new location. The small blue arrow indicates where the column will be moved to if it is dropped in the current position. Figure 10.7, “Rearranged columns” shows the result of dragging the Price column.

Figure 10.6. Dragging columns


Figure 10.7. Rearranged columns


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

Class (selector)Skin ParametersMapped CSS properties
.rf-edt

This class defines styles for the table.

tableBorderWidth, tableBorderColor

border

tableBackgroundColor

background-color

.rich-edt-cnt

This class defines styles for the table content.

No skin parameters.
.rf-edt-c

This class defines styles for a table cell.

tableBorderWidth, tableBorderColor

border-bottom

tableBorderWidth, tableBorderColor

border-right

.rf-edt-c-cnt

This class defines styles for the contents of a cell.

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-edt-tbl-hdr

This class defines styles for the table header.

tableBorderWidth, tableBorderColor

border-bottom

tableHeaderTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

tableHeaderTextColor

color

.rich-edt-hdr

This class defines styles for a header.

No skin parameters.
.rf-edt-hdr-c

This class defines styles for a table header cell.

tableBorderWidth, tableBorderColor

border-bottom

tableBorderWidth, tableBorderColor

border-right

.rf-edt-hdr-c-cnt

This class defines styles for the contents of a header cell.

generalFamilyFont

font-family

generalSizeFont

font-size

tableHeaderTextColor

color

.rf-edt-tbl-ftr

This class defines styles for the table footer.

tableBorderWidth, tableBorderColor

border-top

tableFooterBackgroundColor

background-color

.rich-edt-ftr

This class defines styles for a footer.

tableBorderWidth, tableBorderColor

border-top

tableFooterBackgroundColor

background-color

.rich-edt-ftr-cnt

This class defines styles for the content of a footer.

No skin parameters.
.rf-edt-ftr-c

This class defines styles for a table footer cell.

tableBorderWidth, tableBorderColor

border-bottom

tableBorderWidth, tableBorderColor

border-right

.rf-edt-ftr-c-cnt

This class defines styles for the contents of a footer cell.

generalFamilyFont

font-family

generalSizeFont

font-size

generalTextColor

color

.rf-edt-ftr-emp

This class defines styles for an empty footer cell.

tableBorderWidth, tableBorderColor

border-right

.rich-edt-ftr-fzn

This class defines styles for a frozen footer.

No skin parameters.
.rich-edt-b

This class defines styles for the body of the table.

No skin parameters.
.rf-edt-r-sel

This class defines styles for the selected row.

tableBorderWidth, tableBorderColor

border-right

.rich-edt-r-act

This class defines styles for the active row.

No skin parameters.
.rich-edt-rsz

This class defines styles for the table resizer.

No skin parameters.
.rich-edt-rsz-cntr

This class defines styles for the resize container.

No skin parameters.
.rich-edt-rsz-mkr

This class defines styles for the resize marker.

generalTextColor

border-left

.rf-edt-rord

This class defines styles for the re-order functionality.

tableBorderWidth, tableBorderColor

border

tableHeaderBackgroundColor / tableBackgroundColor

background-color

.rich-edt-rord-mkr

This class defines styles for the re-order marker.

No skin parameters.
.rich-edt-spcr

This class defines a spacer for Internet Explorer 7 compatibility.

No skin parameters.

The <rich:dataGrid> component is used to arrange data objects in a grid. Values in the grid can be updated dynamically from the data model, and Ajax updates can be limited to specific rows. The component supports header, footer, and caption facets.

The <rich:dataGrid> component is similar in function to the JavaServer Faces <h:panelGrid> component. However, the <rich:dataGrid> component additionally allows iteration through the data model rather than just aligning child components in a grid layout.

Figure 10.8. The <rich:dataGrid> component


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

Class (selector)Skin ParametersMapped CSS properties
.rf-dg

This class defines styles for the grid.

tableBackgroundColor

background-color

tableBorderWidth

border-left-width, border-top-width

tableBorderColor

border-left-color, border-top-color

.rf-dg-cap

This class defines styles for the grid caption.

No skin parameters.
.rf-dg-r

This class defines styles for a grid row.

No skin parameters.
.rf-dg-c

This class defines styles for a grid cell.

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-dg-nd-c

This class defines styles for a node cell.

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-dg-th

This class defines styles for the grid header section.

tableBorderWidth

border-bottom-width

tableBorderColor

border-bottom-color

.rf-dg-h

This class defines styles for a grid header.

No skin parameters.
.rf-dg-h-f

This class defines styles for the first header.

No skin parameters.
.rf-dg-h-r

This class defines styles for a header row.

No skin parameters.
.rf-dg-h-c

This class defines styles for a header cell.

tableHeaderBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

tableHeaderTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

.rf-dg-f

This class defines styles for a grid footer.

No skin parameters.
.rf-dg-f-f

This class defines styles for the first footer.

No skin parameters.
.rf-dg-f-c

This class defines styles for a footer cell.

tableFooterBackgroundColor

background-color

tableBorderWidth

border-bottom-width, border-right-width

tableBorderColor

border-bottom-color, border-right-color

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size


The <rich:list> component renders a list of items. The list can be an numerically ordered list, an un-ordered bullet-point list, or a data definition list. The component uses a data model for managing the list items, which can be updated dynamically.

The <rich:dataScroller> component is used for navigating through multiple pages of tables or grids.

Figure 10.14. The <rich:dataScroller> component


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

Class (selector)Skin ParametersMapped CSS properties
.rf-ds

This class defines styles for the data scroller.

generalFamilyFont

font-family

generalSizeFont

font-size

tableBackgroundColor

background

.rf-ds-btn

This class defines styles for buttons in the data scroller.

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

tableBorderColor

border-color

headerBackgroundColor

background-color

.rf-ds-btn-first

This class defines styles for the first button.

No skin parameters.
.rf-ds-btn-fastrwd

This class defines styles for the fast rewind button.

No skin parameters.
.rf-ds-btn-prev

This class defines styles for the previous button.

No skin parameters.
.rf-ds-btn-next

This class defines styles for the next button.

No skin parameters.
.rf-ds-btn-fastfwd

This class defines styles for the fast forward button.

No skin parameters.
.rf-ds-btn-last

This class defines styles for the last button.

No skin parameters.
.rf-ds-nmb-btn

This class defines styles for page number buttons in the data scroller.

generalTextColor

color

generalFamilyFont

font-family

generalSizeFont

font-size

tableBorderColor

border-color

tableBackgroundColor

background-color

.rf-ds-press

This class defines styles for a data scroller when a control is pressed.

tableBorderColor

border-color

tableBackgroundColor

background

 
.rf-ds-act

This class defines styles for an active data scroller.

tableBorderColor

color

.rf-ds-dis

This class defines styles for a disabled data scroller.

tableBorderColor

color


Use the filterExpression attribute to define an expression that can be evaluated as a boolean value. The expression checks if each table entry satisfies the filtering condition when the table is rendered. For example, the expression might be a JSTL (JavaServer Pages Standard Tag Library) function such as contains or equals.

Use the filter attribute to define a filter interface. The attribute must use EL (Expression Language) to point to an object which implements the org.richfaces.model.Filter<T> interface. The object must provide a single accept(T t) method. The method takes each iteration object as a parameter and returns a boolean value, which determines whether the object satisfies the filter. By defining a custom filter, you can implement complex business logic to filter a table.

Use the filterValue attribute to point to an object which holds the current filtering value for the column. The attribute can be used to store filtering conditions in a session. Alternatively, use the filterValue attribute when using the JavaScript API for filtering. The attribute can store a value to pass as parameter to a JavaScript filter method.

Example 10.16. Filtering example


<rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table">

    <f:facet name="header">
        <rich:columnGroup>
            <rich:column>
                <h:outputText value="State Name" />
            </rich:column>
            <rich:column>
                <h:outputText value="State Time Zone" />
            </rich:column>
        </rich:columnGroup>
    </f:facet>
    <rich:column filter="#{filteringBean.stateFilter}">
        <f:facet name="header">
            <h:inputText value="#{filteringBean.stateFilterValue}" id="input">
                <a4j:ajax event="keyup" render="table@body">
                    <a4j:attachQueue  requestDelay="700"
                        ignoreDupResponses="true" />
                </a4j:ajax>
            </h:inputText>
        </f:facet>
        <h:outputText value="#{cap.state}" />
    </rich:column>
    <rich:column filterExpression="#{fn:containsIgnoreCase(cap.timeZone, filteringBean.zoneFilterValue)}">
        <f:facet name="header">
            <h:selectOneMenu value="#{filteringBean.zoneFilterValue}">
                <f:selectItems value="#{filteringBean.zoneList}" />
                <a4j:ajax event="change" render="table@body" />
            </h:selectOneMenu>
        </f:facet>
        <h:outputText value="#{cap.timeZone}" />
    </rich:column>
</rich:dataTable>

The example uses a filter expression on the first column and a filter method on the second column.


Tables entries can be sorted by defining external sorting algorithms. Refer to Section 10.3, “<rich:column>” for details on using the <rich:column> component in tables.

Sorting non-English tables

To sort a table whose contents are not in English, add the org.richfaces.datatableUsesViewLocale context parameter to the project's web.xml settings file. Set the value of the context parameter to true.

Set the sortBy attribute to indicate which iteration object property to use when sorting the column. By default, the target will be sorted using the compare() method.

If using custom-defined rules for sorting, use the comparator attribute instead. Set the comparator attribute to point to your comparator method, which will be used when sorting the data model.

Bind the sortOrder attribute to bean properties to manage the sorting order. The bean must handle all the sorting algorithms. Example 10.17, “Sorting” demonstrates table sorting using an external control.

Example 10.17. Sorting


<rich:dataTable value="#{dataTableScrollerBean.allCars}"
                var="category" rows="20" id="table" reRender="ds2"
                sortPriority="#{sortingBean.prioritList}">
   <rich:column id="make" sortBy="#{category.make}"
                sortOrder="#{sortingBean.makeDirection}">
      <f:facet name="header">
         <h:outputText styleClass="headerText" value="Make" />
      </f:facet>
      <h:outputText value="#{category.make}" />
   </rich:column>
   <rich:column id="model" sortBy="#{category.model}"
                sortOrder="#{sortingBean.modelDirection}">
      <f:facet name="header">
         <h:outputText styleClass="headerText" value="Model" />
      </f:facet>
      <h:outputText value="#{category.model}" />
   </rich:column>
   <rich:column id="price" sortBy="#{category.price}"
                sortOrder="#{sortingBean.priceDirection}">
      <f:facet name="header">
         <h:outputText styleClass="headerText" value="Price" />
      </f:facet>
      <h:outputText value="#{category.price}" />
   </rich:column>
   <rich:column id="mileage" sortBy="#{category.mileage}"
                sortOrder="#{sortingBean.mileageDirection}">
      <f:facet name="header">
         <h:outputText styleClass="headerText" value="Mileage" />
      </f:facet>
      <h:outputText value="#{category.mileage}" />
   </rich:column>
</rich:dataTable>

The example uses an external control to manage the table's sorting.


When multiple columns are capable of being sorted at the same time, set the priority by which the columns are sorted with the sortPriorities attribute. The attribute must contain a list of column identifiers in the order of the sorting sequence.

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.