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
2.4.6. Registering event callbacks with jQuery
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. Dynamic panel item generation
9.6.3. Toggling between components
9.6.4. JavaScript API
9.6.5. Reference data
9.6.6. <rich:itemChangeListener>
9.6.7. <rich:toggleControl>
9.6.8. <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.10.1. Filter Definition
10.10.2. Built-in filter controls
10.10.3. External filter controls
10.11. Table sorting
10.11.1. Comparator Definition
10.11.2. Built-in sort controls
10.11.3. External sort controls
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:chart>
13.1.1. Basic usage
13.1.2. Data input
13.1.3. Chart look customization
13.1.4. Advanced customization
13.1.5. Interactivity options
13.1.6. <rich:chart> server-side events
13.1.7. <rich:chart> client-side events
13.1.8. JavaScript API
13.1.9. Reference data
13.2. <rich:message>
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:messages>
13.3.1. Basic usage
13.3.2. Appearance
13.3.3. Reference data
13.3.4. Style classes and skin parameters
13.4. <rich:notify>
13.4.1. Basic usage
13.4.2. Customizing notifications
13.4.3. Reference data
13.4.4. Style classes and skin parameters
13.5. <rich:notifyMessage>
13.5.1. Basic usage
13.5.2. Reference data
13.5.3. Style classes and skin parameters
13.6. <rich:notifyMessages>
13.6.1. Reference data
13.6.2. Style classes and skin parameters
13.7. <rich:notifyStack>
13.7.1. Basic usage
13.7.2. Positioning notifications
13.7.3. Stacking notifications
13.7.4. Reference data
13.7.5. Style classes and skin parameters
13.8. <rich:progressBar>
13.8.1. Basic usage
13.8.2. Customizing the appearance
13.8.3. Update mode
13.8.4. Using set intervals
13.8.5. JavaScript API
13.8.6. Reference data
13.8.7. Style classes and skin parameters
13.9. <rich:tooltip>
13.9.1. Basic usage
13.9.2. Attaching the tool-tip to another component
13.9.3. Appearance
13.9.4. Update mode
13.9.5. <rich:tooltip> client-side events
13.9.6. JavaScript API
13.9.7. Reference data
13.9.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:jQuery
16.5. rich:findComponent
16.6. 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.2. <rich:focus>
17.2.1. Placement
17.2.2. Applying Focus
17.2.3. Validation-Aware
17.2.4. Preserving Focus
17.2.5. Delaying Focus
17.2.6. Focus Manager
17.2.7. Reference data
17.3. <rich:hotKey>
17.3.1. Basic usage
17.3.2. Event processing
17.3.3. Event handlers
17.3.4. Reference data
17.4. <rich:hashParam>
17.4.1. Basic usage
17.4.2. Reference data
17.5. <rich:placeholder>
17.5.1. Reference data
17.5.2. Style classes and skin parameters
A. Revision History

This book is a guide to the various components available in the RichFaces 4.5.5.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://showcase.richfaces.org/.

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>

Manual registration of servlet in Servlets 3.0

When you attempt to register the Push servlet manually in Servlet 3.0 environments, RichFaces will detect that the Push servlet is already registered and avoid initializing it again.

However, be sure to setup the Push servlet to support asynchronous requests - modify the servlet registration from the previous web.xml snippet as follows:


<servlet>
    <servlet-name>Push Servlet</servlet-name>
    <servlet-class>org.richfaces.webapp.PushServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
    <async-supported>true</async-supported>
</servlet>

Switching to Blocking I/O instead of asynchronous servlets

Although a container you use supports Servlets 3.0, you may experience problems with using asynchronous servlets.

It is possible to force the Atmosphere to use a blocking I/O approach with the following web.xml configuration:


<context-param>
    <param-name>org.atmosphere.useBlocking</param-name>
    <param-value>true</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.

Configuring JMS on JBoss EAP

Refer to the JBoss EAP Administration and Configuration Guide for details on configuring JMS in JBoss EAP.


Ensure the Create durable subscriber and the Delete durable subscriber options are set to true for proper 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

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 the method session.createObjectMessage(message);.

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


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


The above example demonstrates a simple use of the <a4j:push> tag that causes an immediate update of the 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:

  • img
  • object
  • applet
  • script
  • link
  • a

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 r 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.

Validation without model updates

The <rich:graphValidator> component performs a clone() method on the referenced bean instance during the validation phase. The cloned object is validated and triggers any required validation messages. As such, the model object remains clean, and the lifecycle is interrupted properly after the Process Validations phase.

Ensure the referenced object implements the Cloneable interface, and allows a deep clone if required.

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.

  • If unnamed and placed outside any forms, it monitors the status at the view level.
  • If unnamed and placed inside a form, it monitors the status at the form level.

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. Dynamic panel item generation
9.6.3. Toggling between components
9.6.4. JavaScript API
9.6.5. Reference data
9.6.6. <rich:itemChangeListener>
9.6.7. <rich:toggleControl>
9.6.8. <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.10.1. Filter Definition
10.10.2. Built-in filter controls
10.10.3. External filter controls
10.11. Table sorting
10.11.1. Comparator Definition
10.11.2. Built-in sort controls
10.11.3. External sort controls
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:chart>
13.1.1. Basic usage
13.1.2. Data input
13.1.3. Chart look customization
13.1.4. Advanced customization
13.1.5. Interactivity options
13.1.6. <rich:chart> server-side events
13.1.7. <rich:chart> client-side events
13.1.8. JavaScript API
13.1.9. Reference data
13.2. <rich:message>
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:messages>
13.3.1. Basic usage
13.3.2. Appearance
13.3.3. Reference data
13.3.4. Style classes and skin parameters
13.4. <rich:notify>
13.4.1. Basic usage
13.4.2. Customizing notifications
13.4.3. Reference data
13.4.4. Style classes and skin parameters
13.5. <rich:notifyMessage>
13.5.1. Basic usage
13.5.2. Reference data
13.5.3. Style classes and skin parameters
13.6. <rich:notifyMessages>
13.6.1. Reference data
13.6.2. Style classes and skin parameters
13.7. <rich:notifyStack>
13.7.1. Basic usage
13.7.2. Positioning notifications
13.7.3. Stacking notifications
13.7.4. Reference data
13.7.5. Style classes and skin parameters
13.8. <rich:progressBar>
13.8.1. Basic usage
13.8.2. Customizing the appearance
13.8.3. Update mode
13.8.4. Using set intervals
13.8.5. JavaScript API
13.8.6. Reference data
13.8.7. Style classes and skin parameters
13.9. <rich:tooltip>
13.9.1. Basic usage
13.9.2. Attaching the tool-tip to another component
13.9.3. Appearance
13.9.4. Update mode
13.9.5. <rich:tooltip> client-side events
13.9.6. JavaScript API
13.9.7. Reference data
13.9.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:jQuery
16.5. rich:findComponent
16.6. 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.2. <rich:focus>
17.2.1. Placement
17.2.2. Applying Focus
17.2.3. Validation-Aware
17.2.4. Preserving Focus
17.2.5. Delaying Focus
17.2.6. Focus Manager
17.2.7. Reference data
17.3. <rich:hotKey>
17.3.1. Basic usage
17.3.2. Event processing
17.3.3. Event handlers
17.3.4. Reference data
17.4. <rich:hashParam>
17.4.1. Basic usage
17.4.2. Reference data
17.5. <rich:placeholder>
17.5.1. Reference data
17.5.2. Style classes and skin parameters
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 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.


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.


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:

  • hidden, which does not display the button;
  • select, the default setting, which scrolls the calendar to the current month and selects the date; and
  • scroll, which scrolls the calendar to the month but does not select the date.
  • inactive, which displays the date but performs no action when clicked.

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.

Calendar also supports keyboard navigation, with the pop-up appearing when calendar gains focus, if enableManualInput="true" is set the pop-up can be brought up by the up arrow key.

  • arrows keys - changing days/weeks
  • pageDown, pageUp - changing months
  • shift + pageDown, pageUp - changing years
  • Enter - applying the selected date

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.


<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> 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
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-act
This class defines styles for the in-place input when it is in the editing state.

No skin parameters.

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

No skin parameters.

.rf-ii-dis
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-lbl
This class defines styles for the label of the in-place input.

generalTextColor

color

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-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:

  • When in the view state, the component displays its initial setting, such as "click to edit".
  • When in the edit state, the user can select a value from a drop-down list.
  • When in the changed state, the new value for the component has been confirmed, but it can be edited again if required.

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

Class (selector)Skin ParametersMapped CSS properties
.rf-is
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-act
This class defines styles for the in-place select when it is in the editing state.

No skin parameters.

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

No skin parameters.

.rf-is-dis
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.


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.


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 <rich:autocomplete>, where it will accept typed input. The component also supports keyboard navigation. The <rich:select> component functions similarly to the JSF UISelectOne component.

The <rich:select> can optionally be used in an auto-completing mode, where the values in the drop-down list are provided dynamically using either the autocompleteMethod or autocompleteList attributes. If these attributes are omitted, the component operates in the traditional non-auto-completing mode. Refer to the individual attribute documentation to see which attributes are applicable only with an auto-completing select list. Additionally refer to the <rich:autocomplete> section for details on configuring the ajax behaviour of the <rich:select> component.


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).


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.



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.


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.


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.


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.


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.7, “<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.8, “<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:

  • By default, the <rich:toggleControl> component will cycle through <rich:togglePanelItem> components in the order they are defined within the view.

  • The next item to switch to can be explicitly defined by including a <rich:toggleControl> component within a <rich:togglePanelItem> component. Point the targetItem to the <rich:togglePanelItem> to switch to when the state is next changed.

  • Alternatively, use the targetItem attribute with keywords to switch items. The @first, @prev, @next, and @last keywords switch to the first item, the previous item, the next item, and the last item respectively.

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.10.1. Filter Definition
10.10.2. Built-in filter controls
10.10.3. External filter controls
10.11. Table sorting
10.11.1. Comparator Definition
10.11.2. Built-in sort controls
10.11.3. External sort controls

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:


Action components outside the table
Use render=tableId:rowId:cellId to specify the cell to update. The action component updates the cell with an identifier of cellId, which is within the row with an identifier of rowId, which is within the table with an identifier of tableId.

Instead of a specific identifier, any of the references could be variables, as demonstrated in Example 10.3, “Use variables to specify references”.


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:

  • clientRows
  • frozenColumns
  • height
  • onselectionchange
  • selectedClass
  • selection
  • selectionMode

Complex sub-tables

Due to the complex mark-up involved in the <rich:extendedDataTable> component, it does not support the use of the <rich:collapsibleSubTable> component. The <rich:collapsibleSubTable> component is only available with the <rich:dataTable> component.

Similarly, complex row and column spanning using the breakRowBefore, colSpan, and rowSpan attributes is also not available with the <rich:extendedDataTable> 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. Using Ctrl+A will result in selecting all the rows throughout the table.

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.AbstractExtendedDataTable;
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){
      AbstractExtendedDataTable dataTable = (AbstractExtendedDataTable)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;
   }
}


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 7compatibility.

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.


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