for use with Red Hat JBoss Enterprise Application Platform
Legal Notice
Abstract
- 1. RichFaces Deprecation
- 2. Introduction to Red Hat JBoss Web Framework Kit
- 3. Introduction
- 4. Common Ajax attributes
- I. Ajax control components
- 5. Actions
- 5.1.
<a4j:ajax> - 5.2.
<a4j:param> - 5.3.
<a4j:actionListener> - 5.4.
<a4j:commandButton> - 5.5.
<a4j:commandLink> - 5.6.
<a4j:jsFunction> - 5.7.
<a4j:poll> - 5.8.
<a4j:push> - 5.8.1. Setting up Push
- 5.8.2. Server-side Push methods
- 5.8.3. Client-side Push methods
- 5.8.4. Push Topics
- 5.8.5. Handling a push message
- 5.8.6. Handling a push subscription
- 5.8.7. Using TopicsContext to publish message
- 5.8.8. Integrating Push with CDI events
- 5.8.9. Push and JMS integration
- 5.8.10. Reference data
- 5.1.
- 6. Resources
- 7. Containers
- 8. Validation
- 9. Processing management
- II. User interface components
- 10. Rich inputs
- 11. Panels
- 12. Tables and grids
- 13. Trees
- 14. Menus and toolbars
- 15. Output and messages
- 16. Drag and drop
- 17. Layout and appearance
- 18. Functions
- 19. Functionality extension
- A. Revision History
Chapter 1. RichFaces Deprecation
Warning
Chapter 2. Introduction to Red Hat JBoss Web Framework Kit
2.1. About Red Hat JBoss Web Framework Kit
2.2. About the JBoss Web Framework Kit Tiers
- Tier 1 - Included Components
- These are components that are based wholly or partly on open source technologies that support broad collaboration and where Red Hat maintains a leadership role; as such Red Hat is able to support these components and provide upgrades and fixes under our standard support terms and conditions.
- Tier 2 - Tested Frameworks
- These are third party frameworks where Red Hat does not have sufficient influence and does not provide upgrades and fixes under our standard support terms and conditions. Commercially reasonable support is provided by Red Hat Global Support Services for these frameworks.
- Tier 3 - Frameworks in Tested Examples
- These are third party frameworks where Red Hat does not have sufficient influence and does not provide upgrades and fixes under our standard support terms and conditions. Red Hat supports the examples these frameworks are used in and the generic use cases that these examples intend to demonstrate.
- Tier 4 - Confirmed Frameworks
- These are third party frameworks that do not receive any support from Red Hat, but Red Hat verifies that the frameworks run successfully on Red Hat JBoss Enterprise Application Platform. Frameworks and versions not listed here have not been explicitly tested and certified, and thus may be subject to support limitations.
2.3. About the JBoss Web Framework Kit Distribution
- The component frameworks are available from the Red Hat Customer Portal. They are distributed in two alternative formats: a binary for each framework or together as one Maven repository. In addition, the source code for each framework is provided for inspection.
- The third party frameworks are not distributed by Red Hat and each must be obtained from its own source.
.zip file available to download from the Red Hat Customer Portal or from http://www.jboss.org/developer-materials/ on the JBoss Developer Framework website.
- TicketMonster is a moderately complex application demonstrating a number of the JBoss Web Framework Kit frameworks working together.
- Quickstarts and Maven archeypes illustrate subsets of the JBoss Web Framework Kit frameworks used to create simple applications.
- RichFaces, Snowdrop and Seam demonstrations showcase the power of each framework in web application development.
Chapter 3. Introduction
3.1. Libraries
a4j library and the rich library.
a4jlibrary- The
a4jtag library provides core Ajax and utility components. richlibrary- The
richtag library provides ready-made, self-contained, rich user-interface components. These components have built-in Ajax support. By default, the components don't require additional configuration in order to send requests or update, but can also be customized by plugging in utility behaviors.
Chapter 4. Common Ajax attributes
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.
4.1. Data processing
4.1.1. execute
execute attribute allows JSF processing to be limited to defined components. The execute attribute can point to an id identifier of a specific component to process. Components can also be identified through the use of Expression Language (EL).
execute attribute accepts the following keywords:
@all- Every component is processed.
@none- No components are processed.
@this- The requesting component with the
executeattribute is processed. This is the default behavior for components. @form- The form that contains the requesting component is processed.
@region- The region that contains the requesting component is processed. Use the
<a4j:region>component as a wrapper element to specify regions.
4.1.2. bypassUpdates
bypassUpdates attribute is set to true, the Update Model phase of the request processing lifecycle is bypassed. This is useful if user input needs to be validated but the model does not need to be updated. This is the opposite functionality to the execute attribute in RichFaces.
4.2. Rendering
4.2.1. render
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 4.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.
Example 4.1. render example
<h:form id="form1"> <a4j:commandButton value="Basic reference" render="infoBlock, infoBlock2" /> <a4j:commandButton value="Specific reference" render=":infoBlock,:sv:infoBlock2" /> </h:form> <h:panelGrid id="infoBlock"> ... </h:panelGrid> <h:form id="sv"> <h:panelGrid id="infoBlock2"> ... </h:panelGrid> </h:form>
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
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.
render value defined with EL will not influence the request. RichFaces, however, will always use the newer values.
Conditionally-rendered component updates
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.
<a4j:outputPanel> component. The <a4j:outputPanel> component will receive the update and render the component as required.
4.2.2. ajaxRendered
ajaxRendered="true" will be re-rendered with every Ajax request, even when not referenced by the requesting component's render attribute. This can be useful for updating a status display or error message without explicitly requesting it.
ajaxRendered attribute's functionality is the basis for the <a4j:outputPanel> component. The <a4j:outputPanel> component is designed to mark parts of the page for automatic updating. Refer to Section 7.1, “<a4j:outputPanel>” for details.
limitRender="true" to the requesting component, as described in Section 4.2.3, “limitRender”.
4.2.3. limitRender
limitRender="true" specified will not cause components with ajaxRendered="true" to re-render, and only those components listed in the render attribute will be updated. This essentially overrides the ajaxRendered attribute in other components.
render attribute. The second button, however, uses limitRender="true" to override the output panel's rendering and only render the panel grid.
Example 4.2. Rendering example
<h:form id="form1"> <a4j:commandButton value="Normal rendering" render="infoBlock" /> <a4j:commandButton value="Limited rendering" render="infoBlock" limitRender="true" /> </h:form> <h:panelGrid id="infoBlock"> ... </h:panelGrid> <a4j:outputPanel ajaxRendered="true"> <h:messages /> </a4j:outputPanel>
4.3. Queuing and traffic control
4.3.1. requestDelay
requestDelay attribute specifies an amount of time in milliseconds for the request to wait in the queue before being sent to the server. If a similar request is added to the queue before the delay is over, the original request is replaced with the new one.
4.3.2. ignoreDupResponses
true, the ignoreDupResponses attribute causes responses from the server for the request to be ignored if there is another similar request in the queue. This avoids unnecessary updates on the client when another update is expected. The request is still processed on the server, but if another similar request has been queued then no updates are made on the client.
4.4. Events and JavaScript interactions
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.
4.4.1. onbeforesubmit
onbeforesubmit event attribute invokes the event listener before an Ajax request is sent. The request is canceled if the event listener defined for the onbeforesubmit event returns false.
4.4.2. onbegin
onbegin event attribute invokes the event listener after an Ajax request is sent.
4.4.3. onbeforedomupdate
onbeforedomupdate event attribute invokes the event listener after an Ajax response has been returned but before the DOM tree of the browser is updated.
4.4.4. oncomplete
oncomplete event attribute invokes the event listener after an Ajax response has been returned and the DOM tree of the browser has been updated.
4.4.4.1. data
data attribute allows additional data to be handled with the oncomplete event. Use JSF Expression Language (EL) to reference the property of the managed bean, and its value will be serialized in JavaScript Object Notation (JSON) and returned to the client side. The property can then be referenced through the event.data variable in the event attribute definitions. Both primitive types and complex types such as arrays and collections can be serialized and used with data.
Example 4.3. Data reference example
<a4j:commandButton value="Update" oncomplete="showTheName(event.data.name)" data="#{userBean.name}" />
4.4.5. onerror
onerror event attribute invokes the event listener when an error has occurred during Ajax communications.
4.4.6. Registering event callbacks with jQuery
ajaxsubmit: triggered before an Ajax request is sent.ajaxbegin: triggered after an Ajax request is sent.ajaxbeforedomupdate: triggered after an Ajax response has been returned but before the DOM tree of the browser has been updated.ajaxcomplete: triggered after an Ajax response has been returned and the DOM tree of the browser has been updated.
<h:outputScript> jQuery(document).ready(function() { jQuery(#{rich:element('form_id')}).on("ajaxsubmit", function() { // the callback will be triggered before the form is submitted using JSF AJAX console.log("ajaxsubmit"); }); jQuery(document).on("ajaxcomplete", function() { // the callback will be triggered for each completed JSF AJAX for the current page console.log("ajaxcomplete"); }); } </h:outputScript>
Part I. Ajax control components
Table of Contents
- 5. Actions
- 5.1.
<a4j:ajax> - 5.2.
<a4j:param> - 5.3.
<a4j:actionListener> - 5.4.
<a4j:commandButton> - 5.5.
<a4j:commandLink> - 5.6.
<a4j:jsFunction> - 5.7.
<a4j:poll> - 5.8.
<a4j:push> - 5.8.1. Setting up Push
- 5.8.2. Server-side Push methods
- 5.8.3. Client-side Push methods
- 5.8.4. Push Topics
- 5.8.5. Handling a push message
- 5.8.6. Handling a push subscription
- 5.8.7. Using TopicsContext to publish message
- 5.8.8. Integrating Push with CDI events
- 5.8.9. Push and JMS integration
- 5.8.10. Reference data
- 5.1.
- 6. Resources
- 7. Containers
- 8. Validation
- 9. Processing management
Chapter 5. Actions
- 5.1.
<a4j:ajax> - 5.2.
<a4j:param> - 5.3.
<a4j:actionListener> - 5.4.
<a4j:commandButton> - 5.5.
<a4j:commandLink> - 5.6.
<a4j:jsFunction> - 5.7.
<a4j:poll> - 5.8.
<a4j:push> - 5.8.1. Setting up Push
- 5.8.2. Server-side Push methods
- 5.8.3. Client-side Push methods
- 5.8.4. Push Topics
- 5.8.5. Handling a push message
- 5.8.6. Handling a push subscription
- 5.8.7. Using TopicsContext to publish message
- 5.8.8. Integrating Push with CDI events
- 5.8.9. Push and JMS integration
- 5.8.10. Reference data
5.1. <a4j:ajax>
<a4j:ajax> behavior allows Ajax capability to be added to a non-Ajax component. The non-Ajax component must implement the ClientBehaviorHolder interface for all the event attributes that support behavior rendering.
5.1.1. Basic usage
<a4j:ajax> behavior is placed as a direct child to the component that requires Ajax support.
event attribute to the standard JSF event that triggers the behavior. If the event attribute is not defined, the behavior is triggered on the event that normally provides interaction behavior for the parent component.
Example 5.1. <a4j:ajax> example
<h:panelGrid columns="2"> <h:inputText id="myinput" value="#{userBean.name}"> <a4j:ajax event="keyup" render="outtext" /> </h:inputText> <h:outputText id="outtext" value="#{userBean.name}" /> </h:panelGrid>
5.1.2. Reference data
client-behavior-renderer-type:org.ajax4jsf.behavior.Ajaxbehavior-id:org.ajax4jsf.behavior.Ajaxhandler-class:org.richfaces.view.facelets.html.AjaxHandlerbehavior-class:org.ajax4jsf.component.behavior.AjaxBehaviorclient-behavior-renderer-class:org.ajax4jsf.renderkit.AjaxBehaviorRenderer
5.2. <a4j:param>
<a4j:param> behavior combines the functionality of the JavaServer Faces (JSF) components <f:param> and <f:actionListener>.
5.2.1. Basic usage
<a4j:param> requires three main attributes:
- The
valueattribute is the initial value of the parameter. - The
assignToattribute defines the bean property. The property is updated if the parent command component performs an action event during the Process Request phase.
<a4j:param> example” shows a simple implementation along with the accompanying managed bean.
Example 5.2. <a4j:param> example
<h:form id="form"> <a4j:commandButton value="Set name to Alex" reRender="rep"> <a4j:param name="username" value="Alex" assignTo="#{paramBean.name}"/> </a4j:commandButton> <h:outputText id="rep" value="Name: #{paramBean.name}"/> </h:form>
public class ParamBean { private String name = "John"; public String getName() { return name; } public void setName(String name) { this.name = name; } }
name parameter of the bean to Alex, and displays the name in the output field.
5.2.2. Interoperability
<a4j:param> tag can be used with non-Ajax components in addition to Ajax components. This includes components which are working through the GET request, such as the <h:link> and <h:button> components. In this way, data model values can also be updated without any Java code on the server side.
converter attribute can be used to specify how to convert the value before it is submitted to the data model. The property is assigned the new value during the Update Model phase.
Validation failure
5.2.3. Passing client-side parameters
value attribute. In such an implementation, the noEscape attribute should be set to true. Using noEscape="true", the value attribute can contain any JavaScript expression or JavaScript function invocation, and the result will be sent to the server as the value attribute.
Example 5.3. Passing client-side parameters
<h:form> <a4j:commandButton value="Show Screen Size" render="infoPanel"> <a4j:param name="w" value="screen.width" assignTo="#{paramBean.screenWidth}" noEscape="true" /> <a4j:param name="h" value="screen.height" assignTo="#{paramBean.screenHeight}" noEscape="true" /> </a4j:commandButton> <h:panelGrid columns="2" id="infoPanel"> <h:outputText value="Width:" /> <h:outputText value="#{paramBean.screenWidth}" /> <h:outputText value="Height:" /> <h:outputText value="#{paramBean.screenHeight}" /> </h:panelGrid> </h:form>
<a4j:param> behaviors and renders the output text. The <a4j:param> behaviors pass client-side parameters for the screen width and height through the backing bean. These parameters are then used to populate the output text values.
5.2.4. Reference data
component-type:org.richfaces.Parametercomponent-class:org.richfaces.component.UIParametercomponent-family:javax.faces.Parameterhandler-class:org.richfaces.view.facelets.html.ParameterHandler
5.3. <a4j:actionListener>
<a4j:actionListener> tag to register an ActionListener class on a parent action component. The class provided as a listener must implement the javax.faces.event.ActionListener interface. Multiple listener methods can be registered on an action component in this way.
<a4j:actionListener> tag differs from the standard JSF tag by allowing a listener method to be defined instead of just a class. Use the listener attribute to define the listener method.
5.4. <a4j:commandButton>
<a4j:commandButton> component is similar to the JavaServer Faces (JSF) <h:commandButton> component, but additionally includes Ajax support.
The <a4j:commandButton> component executes the complete form
<a4j:commandButton> component has the execute="@form" setting by default. To limit rendering to a different scope, redefine the execute attribute.
5.4.1. Basic usage
<a4j:commandButton> requires only the value attribute to function. Use the value attribute to specify the text of the button.
<a4j:commandButton> uses the click event instead of the submit event.
5.4.2. Reference data
component-type:org.richfaces.CommandButtoncomponent-class:org.richfaces.component.UICommandButtoncomponent-family:javax.faces.Commandrenderer-type:org.richfaces.CommandButtonRenderer
5.5. <a4j:commandLink>
<a4j:commandLink> component is similar to the JavaServer Faces (JSF) <h:commandLink> component, except that it includes plugged-in Ajax behavior.
The <a4j:commandLink> component executes the complete form
<a4j:commandLink> component has the execute="@form" setting by default. To limit rendering to a different scope, redefine the execute attribute.
5.5.1. Basic usage
<a4j:commandLink> requires only the value attribute to function. Use the value attribute to specify the text of the link.
<a4j:commandLink> uses the click event instead of the submit event.
5.5.2. Reference data
component-type:org.richfaces.CommandLinkcomponent-class:org.richfaces.component.UICommandLinkcomponent-family:javax.faces.Commandrenderer-type:org.richfaces.CommandLinkRenderer
5.6. <a4j:jsFunction>
<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.
5.6.1. Basic usage
<a4j:jsFunction> component requires the data attribute. Use the data attribute to define where the retrieved server-side data is stored.
<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.
Example 5.4. <a4j:jsFunction> example
<table width="400"> <tbody> <tr> <td> <span onmouseover="updateName('Kate')" onmouseout="updateName('')">Kate</span> </td> <td> <span onmouseover="updateName('John')" onmouseout="updateName('')">John</span> </td> <td> <span onmouseover="updateName('Alex')" onmouseout="updateName('')">Alex</span> </td> </tr> <tr> <td colspan="3"> Name: <b><h:outputText id="showname" value="#{functionBean.text}" /></b> </td> </tr> </tbody> </table> <h:form> <a4j:jsFunction name="updateName" render="showname"> <a4j:param name="name" assignTo="#{functionBean.text}"/> </a4j:jsFunction> </h:form>
<a4j:jsFunction> component manages the updating and display of the name.
5.6.2. Parameters and JavaScript
<a4j:jsFunction> component allows the use of the <a4j:param> component or the JavaServer Faces <f:param> component to pass any number of parameters for the JavaScript function.
5.6.3. Reference data
component-type:org.richfaces.Functioncomponent-class:org.richfaces.component.UIFunctioncomponent-family:javax.faces.Commandrenderer-type:org.richfaces.FunctionRenderer
5.7. <a4j:poll>
<a4j:poll> component allows periodical sending of Ajax requests to the server. It is used for repeatedly updating a page at specific time intervals.
5.7.1. Timing options
interval attribute specifies the time in milliseconds between requests. The default for this value is 1000 ms (1 second).
<a4j:poll> component can be enabled and disabled using the enabled attribute. Using Expression Language (EL), the enabled attribute can point to a bean property to apply a particular attribute value.
5.7.2. Reference data
component-type:org.richfaces.Pollcomponent-class:org.richfaces.component.UIPollcomponent-family:org.richfaces.Pollrenderer-type:org.richfaces.PollRendererhandler-class:org.richfaces.view.facelets.html.AjaxPollHandler
5.8. <a4j:push>
<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.
<a4j:push> component uses the Comet model for pushing data to the client.
5.8.1. Setting up Push
5.8.1.1. Installing runtime dependencies
<a4j:push> uses an Atmosphere framework for transporting messages. In order to use the Atmosphere on the server-side, it is necessary to add Atmosphere libraries into a project.
atmosphere-runtime as a runtime dependency (its version is managed by richfaces-bom that your project should be importing, check "RichFaces Developer Guide" for details of starting with Maven-based project):
<dependency> <groupId>org.atmosphere</groupId> <artifactId>atmosphere-runtime</artifactId> </dependency>
5.8.1.2. Registering Push servlet
PushServlet registered in web application and listening for Push client connections.
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
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
web.xml configuration:
<context-param> <param-name>org.atmosphere.useBlocking</param-name> <param-value>true</param-value> </context-param>
5.8.2. Server-side Push methods
- TopicsContext - accesses a RichFaces message queue directly
- Push CDI - uses the CDI Event mechanism to fire messages
- Push JMS - the RichFaces Push consumes messages from an enterprise messaging system and exposes them to the client (tightly coupled with the JMS runtime)
5.8.3. Client-side Push methods
ondataavailableevent handler (serialized message is available)- Client behaviors attached to
dataavailableevent
5.8.4. Push Topics
TopicKey's name (e.g. someTopic).
TopicKey can optionally include a subtopic name (e.g. subtopic@anotherTopic).
<a4j:push>'s attribute address.
Push Topic relates to JMS topic
Topics with EL expressions
TopicContext.publish(TopicKey key, Object message) or using CDI events to publish message to dynamically evaluated topic key.
<a4j:push>'s attribute address accepts EL expressions.
5.8.5. Handling a push message
<a4j:push> component on the client will cause it to trigger any event handlers defined using the dataavailable event handler.
<a4j:push> component should also include the onerror event handler to inform the user when an error has occurred with the push messages.
<a4j:push> can be used for either immediate processing of messages (like in the previous example) or it can trigger a partial page update. Check out following samples:
Example 5.5. Handling a push message
<a4j:push address="chat" onerror="alert(event.rf.data)" ondataavailable="chat.addMessage(event.rf.data)" />
dataavailable event attribute with some JavaScript to update messages in a chat room. The event.rf.data parameter contains Push message data serialized to JavaScript.
Example 5.6. Updating DOM for each push message
<a4j:push address="chat" onerror="alert(event.rf.data)"> <a4j:ajax event="datavailable" render="chat" /> </a4j:push>
dataavailable event handler to trigger an AJAX request and a partial page update.
5.8.6. Handling a push subscription
<a4j:push> component establishes connection with server on complete page load (when document is ready).
onsubscribed event handler, which is triggered every time the given component is successfully subscribed to the address/topic it listens to (on a page load and on each AJAX re-render).
Example 5.7. The time-critical updates in stock application
<a4j:push address="stockUpdates" onerror="alert(event.rf.data)"> <a4j:ajax event="dataavailable" render="stocksTable" /> <a4j:ajax event="subscribed" render="stocksTable" /> </a4j:push>
subscribed event to update the table content once the push component is subscribed to the topic, ensuring that the table content is not stale.
5.8.7. Using TopicsContext to publish message
TopicsContext interface directly as in the following sample:
private TopicKey topicKey = new TopicKey("chat"); public void initializeTopic() { TopicsContext topicsContext = TopicsContext.lookup(); topicsContext.getOrCreateTopic(topicKey); } public void sendMessage(String message) throws MessageException { TopicsContext topicsContext = TopicsContext.lookup(); topicsContext.publish(topicKey, message); }
TopicsContext#getOrCreate(TopicKey) where TopicKey is the name of the topic. A message to the topic can be sent using the method: TopicsContext#publish(topicKey, message).
5.8.8. Integrating Push with CDI events
@Push annotation, which specifies an end-point (topic name).
Event.fire(T object)).
@Inject @Push(topic = "chat") Event<String> pushEvent; public void sendMessage(String message) { pushEvent.fire(message); }
5.8.9. Push and JMS integration
5.8.9.1. Enabling JMS integraction
web.xml with a following configuration:
<context-param> <param-name>org.richfaces.push.jms.enabled</param-name> <param-value>true</param-value> </context-param>
5.8.9.2. Configuring JMS backend
<a4j:push> components.
Configuring JMS on Red Hat JBoss Enterprise Application Platform
Example 5.8. JMS server configuration
- Name: datePush
- JNDI name: /topic/datePush
- Use the default settings for other options.
- Name: guest
- Send: true
- Consume: true
- Create subscriber: true
- Delete subscriber: true
- Create durable subscriber: true
- Delete durable subscriber: true
Durable subscriptions
JMS integration with custom configuration
/ConnectionFactory by default.
/topic is used for deriving JMS topic names from Push topic names.
web.xml parameters to change default values: org.richfaces.push.jms.connectionFactory, org.richfaces.push.jms.topicsNamespace.
web.xml parameters or equivalent JVM parameters to change default values: org.richfaces.push.jms.connectionUsername, org.richfaces.push.jms.connectionPassword.
5.8.9.3. Sending and receiving Push messages using JMS
session.createObjectMessage(message);.
publisher.publish(message); like in a following example:
Example 5.9. Sending messages using JMS
TopicConnection connection; TopicSession session; TopicPublisher publisher; public void sendCurrentDate() throws JMSException { String currentDate = new Date().toString(); ObjectMessage message = session.createObjectMessage(message); publisher.publish(message); } // messaging needs to be initialized before using method #sendCurrentDate() private void initializeMessaging() throws JMSException, NamingException { if (connection == null) { TopicConnectionFactory tcf = (TopicConnectionFactory) InitialContext.doLookup("java:/ConnectionFactory"); connection = tcf.createTopicConnection(); } if (session == null) { session = connection.createTopicSession(false, Session.AUTO_ACKNOWLEDGE); } if (topic == null) { topic = InitialContext.doLookup("topic/datePush"); } if (publisher == null) { publisher = session.createPublisher(topic); } }
TopicsContext or using CDI events.
Example 5.10. Receiving messages using JMS
<a4j:push id="datePush" address="datePush" ondataavailable="jQuery(#{rich:element('serverDate')}).text(event.rf.data)" /> <a4j:outputPanel id="serverDate" layout="block"> <i>waiting for event...</i> </a4j:outputPanel>
<a4j:push> tag that causes an immediate update of the page content.
5.8.10. Reference data
component-type:org.richfaces.Pushcomponent-class:org.richfaces.component.UIPushcomponent-family:org.richfaces.Pushrenderer-type:org.richfaces.PushRenderer
Chapter 6. Resources
6.1. <a4j:mediaOutput>
<a4j:mediaOutput> component is used for generating images, video, sounds, and other resources defined on the fly.
6.1.1. Basic usage
createContent attribute points to the method used for generating the displayed content.
value attribute can be used to pass input data to the content generation method specified with createContent. The cacheable attribute specifies whether the resulting content will be cached or not.
6.1.2. Handling content
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:
imgobjectappletscriptlinka
Example 6.1. <a4j:mediaOutput> example
<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" />
<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); } } }
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 */ ... }
<a4j:mediaOutput> component uses the MediaBean and MediaData classes to generate a new image on each page refresh.

Serializable interface
value attribute of <a4j:mediaOutput> should implement the Serializable interface so that it will be encoded to the URL of the resource.
6.1.3. Reference data
component-type:org.richfaces.MediaOutputcomponent-class:org.richfaces.component.UIMediaOutputcomponent-family:org.richfaces.MediaOutputrenderer-type:org.richfaces.MediaOutputRendererhandler-class:org.richfaces.view.facelets.html.MediaOutputHandler
Chapter 7. Containers
a4j tag library which define an area used as a container or wrapper for other components.
7.1. <a4j:outputPanel>
<a4j:outputPanel> component is used to group together components in to update them as a whole, rather than having to specify the components individually.
7.1.1. Aiding complex Ajax rendering
<a4j:outputPanel> component to wrap behaviors when using complex Ajax rendering. Parent components may not render correctly when attached behaviors trigger updates. Point the behaviors to the wrapping <a4j:outputPanel> component instead of the parent components. The <a4j:outputPanel> component is properly encoded to ensure the wrapped components are correctly rendered.
7.1.2. Panel appearance
layout attribute can be used to determine how the component is rendered in HTML:
layout="inline"is the default behavior, which will render the component as a pair of<span>tags containing the child components.layout="block"will render the component as a pair of<div>tags containing the child components, which will use any defined<div>element styles.
ajaxRendered="true" will cause the <a4j:outputPanel> to be updated with each Ajax response for the page, even when not listed explicitly by the requesting component. This can in turn be overridden by specific attributes on any requesting components.
7.1.3. Reference data
component-type:org.richfaces.OutputPanelcomponent-class:org.richfaces.component.UIOutputPanelcomponent-family:javax.faces.Panelrenderer-type:org.richfaces.OutputPanelRenderer
7.2. <a4j:region>
<a4j:region> component specifies a part of the JSF component tree to be processed on the server. The region causes all the a4j and rich Ajax controls to execute: decoding, validating, and updating the model. The region causes these components to execute even if not explicitly declared. As such, processing areas can more easily be marked using a declarative approach.
7.2.1. Reference data
component-type:org.richfaces.Regioncomponent-class:org.richfaces.component.UIRegioncomponent-family:org.richfaces.AjaxContainer
Chapter 8. Validation
Example 8.1. JSR-303 validation annotations
import javax.validation.constraints.Max; import javax.validation.constraints.Min; import javax.validation.constraints.Pattern; import javax.validation.constraints.Size; @ManagedBean @RequestScoped public class UserBean { @Size(min=3, max=12) private String name = null; @Pattern(regexp = "^[\\w\\-]([\\.\\w])+[\\w]+@([\\w\\-]+\\.)+[a-zA-Z]{2,4}$" , message="Bad email") private String email = null; @Min(value = 18) @Max(value = 99) private Integer age; //... //Getters and Setters }
Requirements
validation-api Java Archive and a validation provider (such as Hibernate Validator) to your application libraries.
8.1. <rich:validator> client-side validation
<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.
8.1.1. Basic usage
<rich:validator> behavior is added as a child element to any input control. The value of the input control must reference a managed bean. The content of the input control validates on the client-side based on registered server-side validators included in the managed bean.
Example 8.2. Basic usage
<h:inputText value="#{userBean.name}"> <rich:validator/> </h:inputText>
JSF validation tags
<f:validateLength> and <f:validateDoubleRange> tags, can be declared alongside <rich:validator> behaviors. However, because this duplicates the validation processes at both the view and model level, it is not recommended.
8.1.2. Messages from client-side validators
<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.
Example 8.3. Messages
<rich:panel header="User information"> <h:panelGrid columns="3"> <h:outputText value="Name:" /> <h:inputText value="#{validationBean.name}" id="name"> <rich:validator /> </h:inputText> <rich:message for="name" /> <h:outputText value="Email" /> <h:inputText value="#{validationBean.email}" id="email"> <rich:validator /> </h:inputText> <rich:message for="email" /> <h:outputText value="Age" /> <h:inputText value="#{validationBean.age}" id="age"> <rich:validator /> </h:inputText> <rich:message for="age" /> <h:outputText value="I agree the terms" /> <h:selectBooleanCheckbox value="#{validationBean.agree}" id="agree"> <rich:validator/> </h:selectBooleanCheckbox> <rich:message for="agree" /> </h:panelGrid> </rich:panel>
<rich:message> components. The validation annotations in the managed bean are outlined in Example 8.1, “JSR-303 validation annotations”.

8.1.3. Validation triggers
event attribute to specify which event on the input control triggers the validation process. By default, the <rich:validator> behavior triggers validation when the input control is changed (event="change").
Example 8.4. Validation triggers
<h:inputText value="#{userBean.name}"> <rich:validator event="keyup"/> </h:inputText>
event attribute is changed to the keyup event, such that validation takes place after each key press.
8.1.4. Ajax fall-backs
<rich:validator> behavior invokes all available client-side validators. If all the client-side validators return valid, RichFaces performs an Ajax request to invoke the remaining validators on the server side.
8.1.5. Reference data
client-behavior-renderer-type:org.richfaces.ClientValidatorRendererbehavior-id:org.richfaces.behavior.ClientValidatorhandler-class:org.richfaces.view.facelets.html.ClientValidatorHandlerbehavior-class:org.ajax4jsf.component.behavior.ClientValidatorImplclient-behavior-renderer-class:org.richfaces.renderkit.html.ClientValidatorRenderer
8.2. <rich:graphValidator> object validation
<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
<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.
Cloneable interface, and allows a deep clone if required.
8.2.1. Basic usage
<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 8.5. Basic usage
<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>
@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!")); } ... }
@AssertTrue annotation relies on the isPasswordsEqual() function to check whether the two entered passwords are equal.

8.2.2. Reference data
component-type:org.richfaces.GraphValidatorcomponent-class:org.richfaces.component.UIGraphValidatorcomponent-family:org.richfaces.GraphValidatorhandler-class:org.richfaces.view.facelets.html.GraphValidatorHandler
Chapter 9. Processing management
9.1. <a4j:queue>
<a4j:queue> component manages the JSF queue of Ajax requests. It provides additional options for a finer control of request processing.
9.1.1. Basic usage
<a4j:queue> component works in the same basic way as the standard JSF queue. It can be enabled and disabled through the enabled attribute.
Requests from other libraries
<a4j:queue> component does not handle standard JSF requests or requests from component libraries other than RichFaces.
9.1.2. Delaying requests
requestDelay attribute to add a delay between each request in the queue. Set the requestDelay attribute to the number of milliseconds to wait in between each request. Delaying requests avoids unnecessary processing for actions that would otherwise cause multiple requests, such as typing. Similar requests in the queue are combined while waiting for the request delay.
Example 9.1. Delaying requests
<a4j:queue requestDelay="1500"/>
9.1.3. Duplicate responses
ignoreDupResponses="true" to ignore duplicate responses. With this setting, the client will not update from a request if a similar request is in the queue.
9.1.4. Queue scopes
- An unnamed
<a4j:queue>component placed outside any forms becomes the default queue for all requests on the page. - An unnamed
<a4j:queue>component placed inside a form becomes the default queue for all requests within that form. - Use the
nameidentifier attribute to name an<a4j:queue>component. Named queues can be accessed with the<a4j:attachQueue>behavior to act as a queue for specific components and behaviors. Refer to Section 9.1.7, “<a4j:attachQueue>” for details.
Example 9.2. Queue scopes
<a4j:queue name="viewQueue" requestDelay="2000"/> <h:form> <a4j:queue name="formQueue" requestDelay="1500"/> ... </h:form>
9.1.5. <a4j:queue> client-side events
<a4j:queue> component features several events relating to queuing actions in addition to the common JSF events:
- The
completeevent is fired after a request is completed. The request object is passed as a parameter to the event handler, so the queue is accessible usingrequest.queueand the element which was the source of the request is accessible usingthis. - The
requestqueueevent is fired after a new request has been added to the queue. - The
requestdequeueevent is fired after a request has been removed from the queue.
9.1.6. Reference data
component-type:org.richfaces.Queuecomponent-class:org.richfaces.component.UIQueuecomponent-family:org.richfaces.Queuerenderer-type:org.richfaces.QueueRenderer
9.1.7. <a4j:attachQueue>
<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.
9.1.7.1. Overriding scope settings
<a4j:attachQueue> behavior in the same scope as a queue to override the queue settings for a particular control.
Example 9.3. Overriding scope settings
<a4j:queue requestDelay="2000"/> <h:form> <rich:panel> <h:inputText> <a4j:ajax event="keyup" /> </h:inputText> <a4j:commandButton value="submit"> <a4j:attachQueue requestDelay="0" /> </a4j:commandButton> </rich:panel> </h:form>
<a4j:attachQueue> behavior on the submit button.
9.1.7.2. Using a named queue
<a4j:queue> component using the name attribute. It can then be used by specific components through the <a4j:attachQueue> behavior. Use the name attribute of the <a4j:attachQueue> behavior to identify the name of the destination queue.
Example 9.4. Using a named queue
<a4j:queue name="viewQueue"/> <h:form> <a4j:queue name="formQueue"/> <rich:panel> <a4j:commandButton value="submit"> <a4j:attachQueue name="viewQueue" /> </a4j:commandButton> </rich:panel> </h:form>
viewQueue queue, rather than the formQueue queue.
9.1.7.3. Grouping requests
requestGroupingId attribute. Requests from multiple <a4j:attachQueue> behaviors can use the same identifier to group requests together.
Example 9.5. Grouping requests
<h:form> <a4j:queue requestDelay="2000"/> <h:inputText id="input1" value="#{queueBean.text1}"> <a4j:attachQueue requestGroupingId="registrationForm"/> </h:inputText> <h:inputText id="input2" value="#{queueBean.text2}"> <a4j:attachQueue requestGroupingId="registrationForm"/> </h:inputText> </h:form>
registrationForm identifier.
9.1.7.4. Reference data
component-type:org.richfaces.AttachQueuecomponent-class:org.richfaces.component.UIAttachQueuecomponent-family:org.richfaces.AttachQueuerenderer-type:org.richfaces.AttachQueueRendererhandler-class:org.richfaces.view.facelets.html.AttachQueueHandler
9.2. <a4j:log>
<a4j:log> component generates JavaScript that opens a debug window, logging application information such as requests, responses, and DOM changes.
9.2.1. Basic usage
<a4j:log> component doesn't require any additional attributes for basic functionality.
9.2.2. Log monitoring
mode attribute determines how the log appears on the page.
- Set
mode="inline"to place the logging data in-line on the current page. This is the default setting. - Set
mode="popup"to present the logging data in a new pop-up window. The window is set to be opened by pressing the key combination Ctrl+Shift+L; this can be partially reconfigured with thehotkeyattribute, which specifies the letter key to use in combination with Ctrl+Shift instead of L.
level attribute:
- Set
level="ERROR"to log all errors. - Set
level="FATAL"to log only fatal messages. - Set
level="INFO"to log only informational messages. - Set
level="WARN"to log only warning messages. - Set
level="ALL"to log all data. This is the default setting.
Log renewal
9.2.3. Reference data
component-type:org.richfaces.AjaxLogcomponent-class:org.richfaces.component.UIAjaxLogcomponent-family:org.richfaces.AjaxLogrenderer-type:org.richfaces.AjaxLogRenderer
9.2.4. Style classes and skin parameters
<a4j:log> component is intended primarily for debugging during development. However it is still possible to style the component if desired.
Table 9.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalTextColor
|
color
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
9.3. <a4j:status>
<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.
9.3.1. Customizing the text
- The
startTextattribute defines the text shown after the request has been started and is currently in progress. Set the styles for the text with thestartStyleandstartStyleClassattributes. Alternatively, use thestartfacet to customize the text appearance. - The
stopTextattribute defines the text shown once the request is complete. Set the styles for the text with thestopStyleandstopStyleClassattributes. Alternatively, use thestopfacet to customize the text appearance.If thestopTextattribute is not defined, and no facet exists for the stopped state, the complete status is simply not shown. In this way, only the progress of the request is displayed to the user, along with any errors. - The
errorTextattribute defines the text shown when an error has occurred. Set the styles for the text with theerrorStyleanderrorStyleClassattributes. Alternatively, use theerrorfacet to customize the text appearance.
Example 9.7. Basic <a4j:status> usage
<a4j:status startText="In progress..." stopText="Complete" />
9.3.2. Specifying a region
<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.
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.
Example 9.8. Updating a referenced <a4j:status> component
<rich:panel> <f:facet name="header"> <h:outputText value="User Details Panel" /> </f:facet> <h:panelGrid columns="3"> <h:outputText value="User name:" /> <h:inputText value="#{userBean.name}"> <a4j:ajax status="nameStatus" event="keyup" /> </h:inputText> <a4j:status name="nameStatus"> <f:facet name="start"> <h:graphicImage value="/images/ai.gif" /> </f:facet> </a4j:status> <h:outputText value="Address:" /> <h:inputText value="#{userBean.address}"> <a4j:ajax status="addressStatus" event="keyup" /> </h:inputText> <a4j:status name="addressStatus"> <f:facet name="start"> <h:graphicImage value="/images/ai.gif" /> </f:facet> </a4j:status> </h:panelGrid> </rich:panel>
9.3.3. JavaScript API
<a4j:status> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
start()- Switches status to the
startstate. stop()- Switches status to the
stopstate. error()- Switches status to the
errorstate.
9.3.4. Reference data
component-type:org.richfaces.Statuscomponent-class:org.richfaces.component.UIStatuscomponent-family:org.richfaces.Statusrenderer-type:org.richfaces.StatusRenderer
Part II. User interface components
Table of Contents
- 10. Rich inputs
- 11. Panels
- 12. Tables and grids
- 13. Trees
- 14. Menus and toolbars
- 15. Output and messages
- 16. Drag and drop
- 17. Layout and appearance
- 18. Functions
- 19. Functionality extension
Chapter 10. Rich inputs
10.1. <rich:autocomplete>
<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.
UIInput control with added validation.
10.1.1. Basic usage
value attribute stores the text entered by the user for the auto-complete box. Suggestions shown in the auto-complete list can be specified using one of two different methods:
- The
autocompleteMethodattribute points to a method which returns a list of suggestions according to a supplied prefix.clientandlazyClientmodesThe prefix is normally ignored inclientandlazyClientmodes. In these modes, the component requests the suggestion list once only, and performs filtering on the client. - The
autocompleteListattribute points to a collection of suggestions.
Example 10.1. Defining suggestion values
- Using the
autocompleteMethodattribute <rich:autocomplete value="#{bean.state}" autocompleteMethod="#{bean.autocomplete}" />
The<rich:autocomplete>component uses thebean.autocompletemethod to provide suggestions, based on the entered prefix.- Using the
autocompleteListattribute <rich:autocomplete value="#{bean.state}" autocompleteList="#{bean.suggestions}" />
The<rich:autocomplete>component retrieve the suggestion list frombean.suggestions.
10.1.2. Submission modes
mode attribute to determine how the suggestion list is requested:
- The
clientsetting pre-loads data to the client and uses the input to filter the possible suggestions. - The
ajaxsetting fetches suggestions with every input change using Ajax requests. - The
lazyClientsetting pre-loads data to the client and uses the input to filter the possible suggestions. The filtering does not start until the input length matches a minimum value. Set the minimum value with theminCharsattribute. - The
cachedAjaxsetting pre-loads data via Ajax requests when the input length matches a minimum value. Set the minimum value with theminCharsattribute. All suggestions are handled on the client until the input prefix is changed, at which point a new request is made based on the new input prefix.
10.1.3. Interactivity options
selectFirst="false".
autofill="true" causes the <rich:autocomplete> to fill the text field box with a matching suggestion as the user types.
tokens attribute. As the user types, a suggestion will present as normal. When they enter a character specified as a token, this begins a new suggestion process, and the component only uses text entered after the token character for suggestions. For example, if tokens=", " is set, the <rich:autocomplete> component uses both the comma and space characters as tokens to separate entries. When the user enters a comma or a space, a new suggestion process begins.
Using tokens
10.1.4. Customizing the filter in client and lazyClient modes
<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.
Example 10.2. Customizing the filter
clientFilterFunction attribute. The custom filter determines if the sub-string is contained anywhere in the suggestion item, instead of just at the start.
<script> function customFilter(subString, value){ if(subString.length>=1) { if(value.indexOf(subString)!=-1) return true; }else return false; }; </script> <h:form> <rich:autocomplete mode="client" minChars="0" autofill="false" clientFilterFunction="customFilter" autocompleteMethod="#{autocompleteBean.autocomplete}" /> </h:form>
10.1.5. JavaScript API
<rich:autocomplete> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()- Get the current value of the text field.
setValue(newValue)- Set the value of the text field to the
newValuestring passed as a parameter. showPopup()- Show the pop-up list of completion values.
hidePopup()- Hide the pop-up list.
10.1.6. Reference data
component-type:org.richfaces.Autocompletecomponent-class:org.richfaces.component.UIAutocompletecomponent-family:javax.faces.Inputrenderer-type:org.richfaces.AutocompleteRendererhandler-class:org.richfaces.view.facelets.AutocompleteHandler
10.1.7. Style classes and skin parameters
Table 10.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| controlBackgroundColor
|
background-color
|
| panelBorderColor
|
border-color
|
controlBackgroundColor
|
background-color
| |
| No skin parameters. | |
| headerBackgroundColor
|
background-color
|
panelBorderColor
|
border-left-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| headerBackgroundColor
|
background-color
|
generalTextColor
|
border-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
10.2. <rich:calendar>
<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.
10.2.1. Basic usage
<rich:calendar> component requires only the value attribute, which holds the currently selected date. Example 10.3, “Basic usage” shows a basic declaration, with the value pointing to a bean property. The bean property holds the selected date.
10.2.2. Behavior and appearance
<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.
enableManualInput="true". To disable the calendar from any user input, set disabled="true".
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".
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; andscroll, which scrolls the calendar to the month but does not select the date.inactive, which displays the date but performs no action when clicked.
readonly="true". This allows months and years to be browsed through with the arrow controls, but dates and times cannot be selected.
10.2.3. Time of day
<rich:calendar> component can additionally allow a time of day to be specified with the date. After selecting a date the option to set a time becomes available. The default time can be set with the defaultTime attribute. If the time is altered and a new date is selected, it will not reset unless resetTimeOnDateSelect="true" is specified.
datePattern attribute for the calendar.
Support for seconds
<rich:calendar> component supports times that include seconds. Previous versions of RichFaces only supported hours and minutes.
10.2.4. Localization and formatting
d/M/yy HH:mm a) with the datePattern attribute to format date and time strings.
locale attribute. The calendar will render month and day names in the relevant language. For example, to set the calendar to the US locale, specify locale="en/US".
- The RICH_CALENDAR_APPLY_LABEL string is the label for the button.
- The RICH_CALENDAR_TODAY_LABEL string is the label for the button.
- The RICH_CALENDAR_CLOSE_LABEL string is the label for the button.
- The RICH_CALENDAR_OK_LABEL string is the label for the button.
- The RICH_CALENDAR_CLEAN_LABEL string is the label for the button.
- The RICH_CALENDAR_CANCEL_LABEL string is the label for the button.
org.richfaces.calendar resource bundle with Java Archive files (JARs) defining the same properties.
10.2.5. Using a data model
<rich:calendar> component can be customized through the use of a data model on the server side. The component supports two different ways of loading data from the server side through defining the mode attribute.
mode attribute is not specified, the component uses the client mode. The client mode loads an initial portion of data within a set date range. The range can be defined by using the preloadDateRangeBegin and preloadDateRangeEnd attributes. Additional data requests for months outside the range are not sent.
mode="ajax" the <rich:calendar> requests portions of data from the data model every time the month is switched. The data model can be defined through the dataModel attribute, which points to an object that implements the CalendarDataModel interface. If the dataModel attribute is not defined or has a value of null, the ajax mode functions the same as the client mode.
10.2.6. Client-side customization
<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 10.4, “Client-side customization” demonstrates how client-side customization can be used to style different days in a calendar.
Example 10.4. Client-side customization
<style> .everyThirdDay { background-color: gray; } .weekendBold { font-weight: bold; font-style: italic; } </style> <script type="text/javascript"> var curDt = new Date(); function disablementFunction(day){ if (day.isWeekend) return false; if (curDt==undefined){ curDt = day.date.getDate(); } if (curDt.getTime() - day.date.getTime() < 0) return true; else return false; } function disabledClassesProv(day){ if (curDt.getTime() - day.date.getTime() >= 0) return 'rf-ca-boundary-dates'; var res = ''; if (day.isWeekend) res+='weekendBold '; if (day.day%3==0) res+='everyThirdDay'; return res; } </script> <rich:calendar dayDisableFunction="disablementFunction" dayClassFunction="disabledClassesProv" boundaryDatesMode="scroll" />
10.2.7. JavaScript API
<rich:calendar> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
showPopup()- Expand the pop-up calendar element.
hidePopup()- Collapse the pop-up calendar element.
switchPopup()- Invert the state of the pop-up calendar element.
getValue()- Return the selected date value of the calendar.
getValueAsString()- Return the selected date value of the calendar as a formatted string.
setValue(newValue)- Set the selected date value to the
newValuedate passed as a parameter. If the new date is not in the currently displayed month, a request is performed to display the correct month. resetValue()- Clear the selected date value.
today()- Select today's date.
getCurrentMonth()- Return the number of the month currently being displayed.
getCurrentYear()- Return the number of the year currently being displayed.
showSelectedDate()- Show the calendar month that contains the currently selected date.
showDateEditor()- Show the date editor pop-up.
hideDateEditor()- Hide the date editor pop-up.
showTimeEditor()- Show the time editor pop-up.
hideTimeEditor()- Hide the time editor pop-up.
10.2.8. Reference data
component-type:org.richfaces.Calendarcomponent-class:org.richfaces.component.UICalendarcomponent-family:org.richfaces.Calendarrenderer-type:org.richfaces.CalendarRendererhandler-class:org.richfaces.view.facelets.CalendarHandler
10.2.9. Style classes and skin parameters
Table 10.2. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| panelBorderColor
|
border-color
|
| No skin parameters. | |
| panelBorderColor
|
border-bottom-color
|
additionalBackgroundColor
|
background-color
| |
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| panelBorderColor
|
border-bottom-color
|
additionalBackgroundColor
|
background-color
| |
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| headerBackgroundColor
|
background-color
|
headerSizeFont
|
font-size
| |
headerFamilyFont
|
font-family
| |
headerWeightFont
|
font-weight
| |
headerTextColor
|
color
| |
| panelBorderColor
|
border-right-color, border-bottom-color
|
additionalBackgroundColor
|
background
| |
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| panelBorderColor
|
border-right-color, border-bottom-color
|
additionalBackgroundColor
|
background
| |
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| headerBackgroundColor
|
background-color
|
headerSizeFont
|
font-size
| |
headerFamilyFont
|
font-family
| |
headerWeightFont
|
font-weight
| |
headerTextColor
|
color
| |
| additionalBackgroundColor
|
background
|
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| No skin parameters. | |
| No skin parameters. | |
| calendarWeekBackgroundColor
|
background-color
|
generalTextColor
|
color
| |
tableBackgroundColor
|
border-color
| |
panelBorderColor
|
border-right-color, border-bottom-color
| |
| panelBorderColor
|
border-color
|
panelBorderColor
|
border-right-color, border-bottom-color
| |
| No skin parameters. | |
| panelBorderColor
|
border-bottom-color, border-right-color
|
tableBackgroundColor
|
background-color
| |
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| No skin parameters. | |
| calendarCurrentBackgroundColor
|
background-color
|
calendarCurrentTextColor
|
color
| |
| headerBackgroundColor
|
background-color
|
headerTextColor
|
color
| |
| calendarSpecBackgroundColor
|
background-color
|
calendarSpecTextColor
|
color
| |
| panelBorderColor
|
border-bottom-color, border-right-color
|
calendarWeekBackgroundColor
|
background-color
| |
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| calendarHolidaysBackgroundColor
|
background-color
|
calendarHolidaysTextColor
|
color
| |
| No skin parameters. | |
| buttonSizeFont
|
font-size
|
buttonFamilyFont
|
font-family
| |
| controlBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
subBorderColor
|
border-right-color, border-bottom-color
| |
| headerBackgroundColor
|
background-color, border-color
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| tableBackgroundColor
|
background
|
| shadowBackgroundColor
|
background-color
|
| No skin parameters. | |
| panelBorderColor
|
border-color
|
calendarSpecBackgroundColor
|
background
| |
| calendarCurrentBackgroundColor
|
background-color
|
calendarCurrentTextColor
|
color
| |
| additionalBackgroundColor
|
background
|
tableBackgroundColor
|
border-color
| |
panelBorderColor
|
border-right-color, border-bottom-color
| |
| additionalBackgroundColor
|
background
|
panelBorderColor
|
border-color
| |
tableBackgroundColor
|
border-right-color, border-bottom-color
| |
| No skin parameters. | |
| tableBackgroundColor
|
border-color
|
panelBorderColor
|
border-right-color, border-bottom-color
| |
| tableBackgroundColor
|
border-right-color, border-bottom-color
|
panelBorderColor
|
border-color
| |
calendarWeekBackgroundColor
|
background-color
| |
| panelBorderColor
|
border-color
|
additionalBackgroundColor
|
background
| |
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
| No skin parameters. | |
| No skin parameters. | |
| panelBorderColor
|
border-color
|
tableBackgroundColor
|
background
| |
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| additionalBackgroundColor
|
background
|
panelBorderColor
|
border-top-color
| |
| additionalBackgroundColor
|
background
|
panelBorderColor
|
border-top-color
| |
| panelBorderColor
|
border-right-color
|
10.3. <rich:editor>
<rich:editor> component is used for creating a WYSIWYG editor on a page.
<rich:editor> component is based on the CKEditor implementation.
<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.
10.3.1. Basic usage
value attribute to point to the expression for the current value of the component.
Example 10.5. Basic usage of <rich:editor>
<rich:editor value="#{backingBean.editedValue}" /> <h:outputText escape="false" value="#{backingBean.editedValue}" />
<h:outputText> component in example above).
width and height attributes.
readonly attribute can be used to switch the editor into a read-only mode.
tabindex attribute specifies the position of the current element in the tabbing order for the current document.
Note
ResourceServlet has to be registered for the url-pattern /org.richfaces.resources/* in order to serve the editor resources (JavaScript, CSS, images) correctly. Check the RichFaces Developer's Guide for further details.
Note
<rich:editor> requires the <h:body> component to be present in the view and must be an ancestor of the editor in order for the resource dependencies to render correctly.
10.3.2. Styling
style, styleClass: customizes the style of the editor and underlying textareaeditorStyle, editorClass: customizes the style of the CKEditor instancetextareaStyle, textareaClass: customizes the style of the underlying textarea
10.3.3. Editor skins
<rich:editor> is skinnable using the JavaScript API of the CKeditor. Refer to the CKeditor documentation on installing skins for details on how to customize the look and feel of the editor component.
10.3.4. Advanced configuration
<rich:editor> attributes allows you to support common use-cases for a WYSIWYG editor. However the underlying CKEditor implementation supports many more configuration options.
config attribute to define any of these advanced configuration options supported by the CKEditor. This configuration is written in JavaScript object format and its value is interpolated for EL expressions (making configuration dynamic).
config attribute or a facet named config. The facet takes precedence over attribute when both are defined.
<rich:editor config="startupFocus: #{userPreferences.startupFocus}" /> <rich:editor> <f:facet name="config"> startupFocus: #{userPreferences.startupFocus} </f:facet> </rich:editor>
<rich:editor> is configured to take focus after loading the page as defined by the userPreference bean. Definitions using either attribute or facet are equivalent.
Note
10.3.5. Toolbar customization
<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).
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>
CustomToolbar) needs to match the toolbar_<name> configuration option.
10.3.6. Internationalization and localization
<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.
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
language, as in following sample:
<rich:editor lang="fr" config="language: 'fr'" />
10.3.7. Client-side event handlers
<rich:editor> component produces set of events for handling component specific interaction.
init- once the editor is initialized and ready to be handle user interactionfocus- once the editor is focusedblur- once the editor is blurredchange- fired on blur event when editor content has been changed after previous focusdirty- fired immediately after editor content has been changed
<rich:editor value="#{backingBean.editorValue}"> <a4j:ajax event="change" render="editorOutput" /> <a4j:ajax event="dirty" render="editorOutput"> <a4j:attachQueue requestDelay="1000" /> </a4j:ajax> </rich:editor> <a4j:outputPanel id="editorOutput"> <h:outputText escape="false" value="#{backingBean.editorValue}" /> </a4j:outputPanel>
10.3.8. JavaScript API
<rich:editor> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()- Get the current value of the input control.
setValue(newValue)- Set the value of the input control to the
newValuestring passed as a parameter. getEditor()- Returns the CKEditor object instance associated to given
<rich:editor>component. getInput()- Returns the associated textarea.
focus()- Gives focus to this component
blur()- Removes focus from this component
isFocused()- Returns
trueif this component is focused isDirty()- Returns
trueif editor is focused and it was edited from last focus event (reset by blur event, by usingsetValue(newValue)call and when component is re-rendered) isValueChanged()- Returns
trueif the control's value has been changed from the default (reset bysetValue(newValue)call and when component is re-rendered) isReadonly()- Returns
trueif editor content is editable. setReadonly(readonly)- When
readonlyistrue, editor will be switched to editable state. Otherwise, it will be switched to readonly state.
10.3.9. Reference data
component-type:org.richfaces.Editorcomponent-class:org.richfaces.component.UIEditorcomponent-family:org.richfaces.Editorrenderer-type:org.richfaces.EditorRenderer
10.3.10. Style classes and skin parameters
Table 10.3. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| panelBorderColor
|
border-color
|
| editorMainBackgroundColor
|
background-color
|
| panelBorderColor
|
border-color
|
generalBackgroundColor
|
background
| |
| headerBackgroundColor
|
repeat-x
|
headerWeightFont
|
font-weight
| |
headerTextColor
|
color
| |
headerFamilyFont
|
font-family
| |
headerSizeFont
|
font-size
| |
| editorMainTextColor
|
color
|
| additionalBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
| panelBorderColor
|
border-color
|
tabBackgroundColor
|
background-color
| |
| panelBorderColor
|
border-color
|
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
controlTextColor
|
color
| |
controlBackgroundColor
|
background-color
| |
| headerBackgroundColor
|
background-color
|
panelBorderColor
|
border-left-color
|
10.4. <rich:fileUpload>
<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.
10.4.1. Basic usage
fileUploadListener attribute. Use the attribute to reference a listener function on the server side after each file is uploaded. The listener should process files as required, such as storing them in the session/db/filesystem/ directory. The component itself does not store uploaded files, so if the listener is not implemented they are not stored anywhere.
10.4.2. Upload settings
org.richfaces.fileUpload.createTempFiles context parameter of the web.xml settings file for the project. If the parameter is set to true, the files are uploaded to the temporary folder.
org.richfaces.fileUpload.maxRequestSize context parameter of the web.xml settings file for the project.
10.4.3. Sanitizing file upload input
maxFilesQuantity- The
maxFilesQuantityparameter defines maximum number of files allowed to be uploaded. After a number of files in the list equals to the value of this attribute, "Add" button disappears and nothing could be uploaded even if you clear the whole list. In order to upload files again you should rerender the component. acceptedTypes- The
acceptedTypesparameter defines comma separated list of file extensions accepted by component. The component does not provide any feedback when rejecting file. For introducing feedback for rejection, useontyperejectedparameter. ontyperejected- The
ontyperejectedparameter defines event handler when file does not meet conditions stated byacceptedTypesparameter.
10.4.4. Interactivity options
immediateUpload attribute to true to upload files as soon as they are added to the list, rather than waiting for the user to press the button.
addLabel- The
addLabelparameter sets the label for the button. clearAllLabel- The
clearAllLabelparameter sets the label for the button. clearLabel- The
clearLabelparameter sets the label for the button. uploadLabel- The
uploadLabelparameter sets the label for the button.
<rich:fileUpload> component provides a built-in progress bar to indicate the progress of each file that is uploaded. This progress bar can be replaced with a <rich:progressBar> component added to the progress facet. Refer to Section 15.8, “<rich:progressBar>” for details on the <rich:progressBar> component.
<rich:fileUpload> component, use the disabled attribute.
10.4.5. <rich:fileUpload> client-side events
<rich:fileUpload> component:
filesubmitis triggered before a file is uploaded.uploadcompleteis triggered after all files in the list have finished uploading.
10.4.6. Reference data
component-type:org.richfaces.FileUploadcomponent-class:org.richfaces.component.UIFileUploadcomponent-family:org.richfaces.FileUploadrenderer-type:org.richfaces.FileUploadRendererhandler-class:org.richfaces.view.facelets.FileUploadHandler
10.4.7. Style classes and skin parameters
Table 10.4. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
| headerBackgroundColor
|
background-color, border-color
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| trimColor
|
background-color
|
panelBorderColor
|
border-color
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| tableFooterBackgroundColor
|
background-color
|
tableFooterBackgroundColor
|
border-color
| |
| tabDisabledTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| trimColor
|
background-color
|
panelBorderColor
|
border-color
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| trimColor
|
background-color
|
panelBorderColor
|
border-color
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| panelBorderColor
|
border-bottom-color
|
| No skin parameters. | |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| generalLinkColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| No skin parameters. | |
| No skin parameters. | |
10.5. <rich:inplaceInput>
<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.
10.5.1. Basic usage
value attribute to point to the expression for the current value of the component. Validation and conversion rules for the JSF UIInput control apply as usual.
10.5.2. Interactivity options
defaultLabel attribute. Alternatively, if the initial value is already set through the value attribute, this is displayed instead.
value attribute. The use of the default label and value is shown in Example 10.7, “Default label and value”.
Example 10.7. Default label and value
<rich:inplaceInput value="#{bean.value}" defaultLabel="click to edit"/>
editEvent attribute to specify a different event.
- By default, pressing the Enter key will confirm and save the input.
- If
showControls="true"is set, buttons for confirming or canceling are added to the component. - If
saveOnBlur="true"is set, the input is saved on the component's blur event.
10.5.3. JavaScript API
<rich:inplaceInput> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()- Get the current value of the input control.
setValue(newValue)- Set the value of the input control to the
newValuestring passed as a parameter. isEditState()- Returns
trueif the control is currently in the edit state, orfalseif the control is currently in the view state. isValueChanged()- Returns
trueif the control's value has been changed from the default. save()- Saves the current item as the control's value.
cancel()- Cancel editing the value.
getInput()- Return the DOM element for the input.
10.5.4. Reference data
component-type:org.richfaces.InplaceInputcomponent-class:org.richfaces.component.UIInplaceInputcomponent-family:org.richfaces.InplaceInputrenderer-type:org.richfaces.InplaceInputRenderer
10.5.5. Style classes and skin parameters
Table 10.5. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| editorBackgroundColor
|
background-color
|
generalTextColor
|
border-bottom-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| editBackgroundColor
|
background-color, border-bottom-color
|
generalTextColor
|
color
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| generalTextColor
|
color
|
generalSizeFont
|
font-size
| |
| No skin parameters. | |
| tabBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
| tabBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
10.6. <rich:inplaceSelect>
<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.
- 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.
10.6.1. Basic usage
value attribute to point to the expression for the current value of the component and a list of items. The list of items can be defined using the JSF components <f:selectItem/> and <f:selectItems/>.
Example 10.8. Defining list items for <rich:inplaceSelect>
<rich:inplaceSelect value="#{bean.inputValue}" defaultLabel="click to edit" > <f:selectItems value="#{bean.selectItems}" /> <f.selectItem itemValue="1" itemLabel="Item 1" /> <f.selectItem itemValue="2" itemLabel="Item 2" /> <f.selectItem itemValue="3" itemLabel="Item 3" /> <f.selectItem itemValue="4" itemLabel="Item 4" /> </rich:inplaceSelect>
10.6.2. Interactivity options
defaultLabel attribute, such as defaultLabel="click to edit". Alternatively, if the initial value is already set through the value attribute, this is displayed instead.
editEvent attribute to specify a different event. When switching to edit mode, the drop-down list of possible values will automatically be displayed; this can be deactivated by setting openOnEdit="false".
- Once the user selects an item from the drop-down list, the item is saved as the new control value. This is the default setting. If
saveOnSelect="false"is set, the component applies the selected item but remains in the edit state so a different selection could be chosen. The value is then applied when the Enter key is pressed. - If
saveOnBlur="true"is set, the selected item is saved as the new control value when the control loses focus. - If
showControls="true"is set, buttons are added to the control to confirm or cancel the selection. The new control value is only saved once the user confirms the selection using the button.
10.6.3. JavaScript API
<rich:inplaceSelect> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()- Get the current value of the select control.
setValue(newValue)- Set the value of the select control to the
newValuestring passed as a parameter. isEditState()- Returns
trueif the control is currently in the edit state, orfalseif the control is currently in the view state. isValueChanged()- Returns
trueif the control's value has been changed from the default. save()- Saves the current item as the control's value.
cancel()- Cancel editing the value.
getInput()- Return the input entered into the control by the user.
getLabel()- Return the default label of the control.
setLabel(newLabel)- Set the default label of the control to the
newLabelstring passed as a parameter. showPopup()- Show the pop-up list of possible values.
hidePopup()- Hide the pop-up list.
10.6.4. Reference data
component-type:org.richfaces.InplaceSelectcomponent-class:org.richfaces.component.UIInplaceSelectcomponent-family:org.richfaces.Selectrenderer-type:org.richfaces.InplaceSelectRenderer
10.6.5. Style classes and skin parameters
Table 10.6. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| editorBackgroundColor
|
background-color
|
generalTextColor
|
border-bottom-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| editBackgroundColor
|
background
|
generalTextColor
|
color
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| generalTextColor
|
border-color
|
| generalTextColor
|
border-color
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| tabBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
| tabBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
| No skin parameters. | |
| No skin parameters. | |
| editBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
10.7. <rich:inputNumberSlider>
<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.
10.7.1. Basic usage
value attribute is used for storing the currently selected value of the slider. Standard conversion and validation for the JSF UIInput component is applied.
10.7.2. Interactivity options
showInput="false".
minValue, maxValue, and step.
showBoundaryValues="false". The tool-tip showing the current value can be hidden by setting showToolTip="false".
showArrows="true". Clicking the arrows move the slider indicator in that direction by the gradient step, and clicking and holding the arrows moves the indicator continuously. The time delay for each step when updating continuously can be defined using the delay attribute.
10.7.3. JavaScript API
<rich:inputNumberSlider> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()- Get the current value of the slider control.
setValue(newValue)- Set the value of the slider control to the
newValueinteger passed as a parameter. increase()- Increase the value of the slider control by the gradient step amount.
decrease()- Decrease the value of the slider control by the gradient step amount.
10.7.4. Reference data
component-type:org.richfaces.InputNumberSlidercomponent-class:org.richfaces.component.html.HtmlInputNumberSlidercomponent-family:org.richfaces.Inputrenderer-type:org.richfaces.InputNumberSliderRenderer
10.7.5. Style classes and skin parameters
Table 10.7. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| controlBackgroundColor
|
background-color
|
panelBorderColor
|
border-bottom-color
| |
| No skin parameters. | |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
generalTextColor
|
color
| |
panelBorderColor
|
border-left-color
| |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
generalTextColor
|
color
| |
panelBorderColor
|
border-right-color
| |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
generalTextColor
|
color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
generalTextColor
|
color
| |
tipBorderColor
|
border
| |
tipBackgroundColor
|
background-color
| |
10.8. <rich:inputNumberSpinner>
<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.
10.8.1. Basic usage
minValue, maxValue, and step respectively. The starting value of the spinner is the minimum value unless otherwise specified with the value attribute.
10.8.2. Interactivity options
cycled="false", which will cause the buttons to stop responding when the reach the maximum or minimum value.
enableManualInput="false".
10.8.3. JavaScript API
<rich:inputNumberSpinner> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()- Get the current value of the spinner control.
setValue(newValue)- Set the value of the spinner control to the
newValueinteger passed as a parameter. increase()- Increase the value of the spinner control by the gradient step amount.
decrease()- Decrease the value of the spinner control by the gradient step amount.
10.8.4. Reference data
component-type:org.richfaces.InputNumberSpinnercomponent-class:org.richfaces.component.html.HtmlInputNumberSpinnercomponent-family:org.richfaces.Inputrenderer-type:org.richfaces.InputNumberSpinnerRenderer
10.8.5. Style classes and skin parameters
Table 10.8. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| panelBorderColor
|
border-color
|
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
generalTextColor
|
color
| |
controlBackgroundColor
|
background-color
| |
| headerBackgroundColor
|
background-color
|
panelBorderColor
|
border-left-color
| |
| No skin parameters. | |
| No skin parameters. | |
10.9. <rich:select>
<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.
<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 Section 10.1, “<rich:autocomplete>” for details on configuring the ajax behaviour of the <rich:select> component.
10.9.1. Basic usage
<rich:select> component requires the value attribute to store the selected value. Additionally, child tags to manage the list of selections are required. The child tags can either be a number of <f:selectItem> tags or a <f:selectItems> tag which points to a data model containing a list of selection items. The value attribute is used to store the current selection.
Example 10.9. Selection items
- Using multiple
<f:selectItem>tags <rich:select> <f:selectItem itemValue="0" itemLabel="Option 1" /> <f:selectItem itemValue="1" itemLabel="Option 2" /> <f:selectItem itemValue="2" itemLabel="Option 3" /> <f:selectItem itemValue="3" itemLabel="Option 4" /> <f:selectItem itemValue="4" itemLabel="Option 5" /> </rich:select>
- Using a single
<f:selectItems>tag <rich:select> <f:selectItems value="#{bean.options}" /> </rich:select>
10.9.2. Using manual input
<rich:select> component allows the user to type into a text field to scroll through or filter the list. By default, the <rich:select> component functions as a drop-down list with no manual input. To add keyboard support for manual input, set enableManualInput="true".
<h:selectOne> component does not offer this extended keyboard support. However, since the <rich:select> component is still based on the JSF UISelectOne component, it will not accept a value that does not match any items in the drop-down list. If an invalid value is entered, it is highlighted as erroneous and validation messages appear with the submission.
10.9.3. Advanced options
defaultLabel attribute to set a place-holder label, such as defaultLabel="select an option".
<h:selectOneMenu> component. As such, custom objects used for selection items should use the same converters as for an <h:selectOneMenu> component.
10.9.4. JavaScript API
<rich:select> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()- Get the current value of the text field.
setValue(newValue)- Set the value of the text field to the
newValuestring passed as a parameter. getLabel()- Return the default label of the control.
showPopup()- Show the pop-up list of completion values.
hidePopup()- Hide the pop-up list.
10.9.5. Reference data
component-type:org.richfaces.Selectcomponent-class:org.richfaces.component.UISelectcomponent-family:org.richfaces.Selectrenderer-type:org.richfaces.SelectRendererhandler-class:org.richfaces.view.facelets.AutocompleteHandler
10.9.6. Style classes and skin parameters
Table 10.9. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| panelBorderColor
|
border-color
|
| controlBackgroundColor
|
background-color
|
| No skin parameters. | |
| generalTextColor
|
color
|
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| generalTextColor
|
border-color
|
| No skin parameters. | |
| headerBackgroundColor
|
background-color
|
panelBorderColor
|
border-left-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
10.10. <rich:orderingList>
<rich:orderingList> is a component for ordering items in a list (client-side).
10.10.1. Basic usage
<rich:orderingList> bind the value attribute to the list to be ordered. The var attribute specifies a variable to use when iterating through the list values. The var attribute is used within the itemLabel to assign the object value to be displayed. Similarly, the var attribute is used within the itemValue attribute to specify the object value mapped by the display value. If the itemValue is not of type String, a converter must be specified for this itemValue using either the converter attribute, or a nested <f:converter> tag.
Example 10.10. ItemLabel/ItemValue use
- Using the
itemLabelanditemValueattributes <rich:orderingList value="#{listSelectBean.capitals}" var="capital" itemValue="#{capital}" itemLabel="#{capital.name}"> <f:converter converterId="CapitalsConverter" /> </rich:orderingList>
10.10.2. Column Layout
<rich:orderingList> supports a columnar layout of the itemValues to be sorted. This is achieved by nesting <rich:column> tags within the orderingList, and referencing the var attribute from within the <rich:column> EL.
Example 10.11. Nested <rich:column> tags
- Using
<rich:column>tags nested within the<rich:orderingList> <rich:orderingList value="#{listSelectBean.capitals}" var="capital" listWidth="300px"> <f:converter converterId="CapitalsConverter" /> <rich:column> <f:facet name="header">Flag</f:facet> <h:graphicImage value="#{capital.stateFlag}" alt="flag" width="33"/> </rich:column> <rich:column> <f:facet name="header">Name</f:facet> #{capital.name} </rich:column> <rich:column> <f:facet name="header">State</f:facet> #{capital.state} </rich:column> </rich:orderingList>
<rich:column> tags to layout the <rich:orderingList> items, the itemLabel attribute is irrelevant, and may be left out.
10.10.3. JavaScript API
<rich:orderingList> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getList()- Returns the javascript list object backing the
<rich:orderingList>. This list can be used to select/unselect item(s). up()- Move the currently selected item(s) up one step.
down()- Move the currently selected item(s) down one step.
upTop()- Move the currently selected item(s) to the top of the list.
downBottom()- Move the currently selected item(s) to the bottom of the list.
toggleButtons()- Activate/de-activate the orderingList buttons based on the current component item state.
10.10.4. Reference data
component-type:org.richfaces.OrderingListcomponent-class:org.richfaces.component.UIOrderingListcomponent-family:org.richfaces.SelectManyrenderer-type:org.richfaces.OrderingListRenderer
10.10.5. Style classes and skin parameters
Table 10.10. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| No skin parameters. | |
| headerTextColor
|
color
|
headerSizeFont
|
font-size
| |
headerFamilyFont
|
font-family
| |
headerWeightFont
|
font-weight
| |
| No skin parameters. | |
| headerBackgroundColor
|
background-color
|
headerTextColor
|
color
| |
headerSizeFont
|
font-size
| |
headerFamilyFont
|
font-family
| |
headerWeightFont
|
font-weight
| |
| generalTextColor
|
color
|
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| generalTextColor
|
border-color
|
| No skin parameters. | |
| headerBackgroundColor
|
background-color
|
panelBorderColor
|
border-left-color
| |
| No skin parameters. | |
| No skin parameters. | |
10.11. <rich:pickList>
<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.
10.11.1. Basic usage
<rich:pickList> bind the value attribute to the target list, where the selected items will be stored. The list of source items is provided by nesting a SelectItem source, such as a <f:selectItems> tag, or a list of <f:selectItem> tags. If the itemValue of the SelectItem is not of type String, a converter must be specified for this itemValue using either the converter attribute, or a nested <f:converter> tag.
Example 10.12. Simple pickList use
- Using the default
SelectItemitemLabel to generate the pickList source and target items. <rich:pickList value="#{listSelectBean.selectedCapitals}" sourceCaption="Available cities" targetCaption="Selected cities" listWidth="170px" listHeight="100px" orderable="true"> <f:selectItems value="#{listSelectBean.capitals}" var="capital" itemValue="#{capital}" itemLabel="#{capital.name}" /> <f:converter converterId="CapitalsConverter" /> </rich:pickList>
orderable attribute of the <rich:pickList> tag to true. The arrow keys on a keyboard can then be used to highlight different items in the target list, and pressing the ctrl modifier with the arrow keys will move the selected item up or down within the target list.
10.11.2. Column Layout
SelectItem itemLabel display, the <rich:pickList> supports a columnar layout of the items to be selected. This is achieved by adding a var attribute used to represent the collection of nested SelectItems, and nesting <rich:column> tags within the pickList. The var attribute of the <f:selectItem> is then referenced from within the <rich:column> EL.
Example 10.13. Nested <rich:column> tags
- Using
<rich:column>tags nested within the<rich:pickList> <rich:pickList value="#{listSelectBean.selectedCapitals}" var="capital" listHeight="200px"> <f:selectItems value="#{listSelectBean.capitals}" /> <f:converter converterId="CapitalsConverter" /> <rich:column> <f:facet name="header">Flag</f:facet> <h:graphicImage value="#{capital.stateFlag}" alt="flag" width="33"/> </rich:column> <rich:column> <f:facet name="header">Name</f:facet> #{capital.name} </rich:column> <rich:column> <f:facet name="header">State</f:facet> #{capital.state} </rich:column> </rich:pickList>
10.11.3. JavaScript API
<rich:pickList> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getSourceList()- Returns the javascript list object backing the
<rich:pickList>source list. This list can be used to select/unselect item(s). getTargetList()- Returns the javascript list object backing the
<rich:pickList>target list. This list can be used to select/unselect item(s). add()- Add the currently selected items to the target list, removing them from the source list.
addAll()- Add all the source items to the target list, removing them from the source list.
remove()- Remove the currently selected items from the target list, adding them to the source list.
removeAll()- Remove all the source items from the target list, adding them to the source list.
toggleButtons()- Activate/de-activate the pickList buttons based on the current component item state.
10.11.4. Reference data
component-type:org.richfaces.PickListcomponent-class:org.richfaces.component.UIPickListcomponent-family:org.richfaces.SelectManyrenderer-type:org.richfaces.PickListRenderer
10.11.5. Style classes and skin parameters
Table 10.11. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| headerTextColor
|
color
|
headerSizeFont
|
font-size
| |
headerFamilyFont
|
font-family
| |
headerWeightFont
|
font-weight
| |
| No skin parameters. | |
| headerBackgroundColor
|
background-color
|
headerTextColor
|
color
| |
headerSizeFont
|
font-size
| |
headerFamilyFont
|
font-family
| |
headerWeightFont
|
font-weight
| |
| generalTextColor
|
color
|
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
| |
| generalTextColor
|
border-color
|
| No skin parameters. | |
| headerBackgroundColor
|
background-color
|
panelBorderColor
|
border-left-color
| |
| No skin parameters. | |
| No skin parameters. | |
Chapter 11. Panels
11.1. <rich:panel>
<rich:panel> component is a bordered panel with an optional header.
11.1.1. Basic usage
<rich:panel> without any attributes defined renders a bordered region with no header.
11.1.2. Adding a header
header attribute to specify the text to appear in the header. Alternatively the header can be constructed using a header facet. Example 11.1, “Adding a header” demonstrates the two different approaches.
Example 11.1. Adding a header
<rich:panel header="This is the panel header"> <h:outputText value="This is the panel content" /> </rich:panel>
<rich:panel> <f:facet name="header"> <h:outputText value="This is the panel header"> </f:facet> <h:outputText value="This is the panel content" /> </rich:panel>
11.1.3. Reference data
component-type:org.richfaces.Panelcomponent-class:org.richfaces.component.UIPanelcomponent-family:org.richfaces.Panelrenderer-type:org.richfaces.PanelRenderer
11.1.4. Style classes and skin parameters
Table 11.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalBackgroundColor
|
background-color
|
panelBorderColor
|
color
| |
| headerBackgroundColor
|
background-color, border-color
|
headerTextColor
|
color
| |
headerSizeFont
|
font-size
| |
headerWeightFont
|
font-weight
| |
headerFamilyFont
|
font-family
| |
| generalTextColor
|
color
|
generalSizeFont
|
font-size
| |
generalFamilyFont
|
font-family
|
11.2. <rich:accordion>
<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.
11.2.1. Basic usage
<rich:accordion> component requires no attributes for basic usage. The component can contain any number of <rich:accordionItem> components as children. The headers of the <rich:accordionItem> components control the expanding and collapsing when clicked. Only a single <rich:accordionItem> can be displayed at a time. Refer to Section 11.2.8, “<rich:accordionItem>” for details on the <rich:accordionItem> component.
Form elements required
<rich:tabPanel> components should be wrapped in a form element when using either ajax or server mode, as usual for submitting components.
11.2.2. Switching panels
activeItem attribute holds the active panel name. This name is a reference to the name identifier of the active child <rich:accordionItem> component.
switchType attribute, which can have one of the following three values:
server- The default setting. Activation of a
<rich:accordionItem>component causes the parent<rich:accordion>component to perform a common submission, completely refreshing the page. Only one panel at a time is rendered to the client side. ajax- Activation of a
<rich:accordionItem>component causes the parent<rich:accordion>component to perform an Ajax form submission, and the content of the panel is rendered. Only one panel at a time is rendered to the client side. client- Activation of a
<rich:accordionItem>component causes the parent<rich:accordion>component to perform updates on the client side. All the panels are rendered on the client side during the initial page render. JavaScript changes the styles such that one panel component becomes hidden while the other is shown.
11.2.3. <rich:accordion> client-side events
<rich:accordion> component uses the client-side events common to all switchable panels:
- The
itemchangeevent points to the function to perform when the switchable item is changed. - The
beforeitemchangeevent points to the function to perform when before the switchable item is changed.
11.2.4. <rich:accordion> server-side events
<rich:accordion> component uses the server-side events common to all switchable panels:
- The
ItemChangeEventevent occurs on the server side when an item is changed through Ajax using theservermode. It can be processed using theItemChangeListenerattribute. Refer to Section 11.6.6, “<rich:itemChangeListener>” for details on the<rich:itemChangeListener>tag.
11.2.5. JavaScript API
<rich:accordion> component can be controlled through the JavaScript API. The JavaScript API provides the following functions, which are common to all switchable panels:
getItems()- Return an array of the items contained in the accordion control.
getItemsNames()- Return an array of the names of the items contained in the accordion control.
switchToItem(itemName)- Switch to and display the item identified by the
itemNamestring passed as a parameter. firstItem(),prevItem(),nextItem(),lastItem()- Get the name of the first item, the previous item, the next item, or the last item.
11.2.6. Reference data
component-type:org.richfaces.Accordioncomponent-class:org.richfaces.component.UIAccordioncomponent-family:org.richfaces.Accordionrenderer-type:org.richfaces.AccordionRendererhandler-class:org.richfaces.view.facelets.html.TogglePanelTagHandler
11.2.7. Style classes and skin parameters
Table 11.2. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| panelBorderColor
|
border-color
|
generalBackgroundColor
|
background
| |
| panelBorderColor
|
border-bottom-color
|
headerBackgroundColor
|
background-color
| |
headerTextColor
|
color
| |
headerWeightFont
|
font-weight
| |
headerFamilyFont
|
font-family
| |
headerSizeFont
|
font-size
| |
| No skin parameters. | |
| tabDisabledTextColor
|
color
|
| No skin parameters. | |
| panelBorderColor
|
border-bottom-color
|
generalTextColor
|
color
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
11.2.8. <rich:accordionItem>
<rich:accordionItem> component is a panel for use with the <rich:accordion> component. <rich:accordionItem> components can be added dynamically using iteration models with the <c:forEach> tag.
11.2.8.1. Basic usage
<rich:accordionItem> component requires the header attribute, which provides the text on the panel header. The panel header is all that is visible when the accordion item is collapsed.
header facet could be used in place of the header attribute. This would allow for additional styles and custom content to be applied to the tab.
11.2.8.2. <rich:accordionItem> client-side events
<rich:accordionItem> component uses the client-side events common to all switchable panel items:
- The
enterevent points to the function to perform when the mouse enters the panel. - The
leaveevent points to the function to perform when the mouse leaves the panel.
11.2.8.3. Reference data
component-type:org.richfaces.AccordionItemcomponent-class:org.richfaces.component.UIAccordionItemcomponent-family:org.richfaces.AccordionItemrenderer-type:org.richfaces.AccordionItemRenderer
11.3. <rich:collapsiblePanel>
<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.
11.3.1. Basic usage
header attribute, or by the headerExpanded/headerCollapsed facets. Additionally the panel requires content to display when it is expanded. Content is added as child elements like a standard panel.
11.3.2. Expanding and collapsing the panel
switchType attribute, which can have one of the following three values:
server- This is the default setting. The
<rich:collapsiblePanel>component performs a common submission, completely refreshing the page. Only one panel at a time is rendered to the client side. ajax- The
<rich:collapsiblePanel>component performs an Ajax form submission, and only the content of the panel is refreshed. Only one panel at a time is rendered to the client side. client- The
<rich:collapsiblePanel>component changes the state on the client side without any additional requests being sent.
11.3.3. Appearance
<rich:collapsiblePanel> component can be customized using facets. The headerExpanded and headerCollapsed CSS fclasses are used to style the appearance of the panel when it is expanded and collapsed respectively.
11.3.4. <rich:collapsiblePanel> server-side events
<rich:collapsiblePanel> component uses the following unique server-side events:
- The
PanelToggleEventevent occurs on the server side when the<rich:collapsiblePanel>component is expanded or collapsed in either theajaxorservermodes. It can be processed using thepanelTogglerListenerattribute.
11.3.5. JavaScript API
<rich:collapsiblePanel> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
switchPanel()- Switch the state of the collapsible panel (expanded or collapsed).
11.3.6. Reference data
component-type:org.richfaces.CollapsiblePanelcomponent-class:org.richfaces.component.UICollapsiblePanelcomponent-family:org.richfaces.CollapsiblePanelrenderer-type:org.richfaces.CollapsiblePanelRendererhandler-class:org.richfaces.view.facelets.html.CollapsiblePanelTagHandler
11.3.7. Style classes and skin parameters
Table 11.3. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| panelBorderColor
|
color
|
generalBackgroundColor
|
background
| |
| headerBackgroundColor
|
background-color, border-color
|
headerTextColor
|
color
| |
headerWeightFont
|
font-weight
| |
headerFamilyFont
|
font-family
| |
headerSizeFont
|
font-size
| |
| No skin parameters. | |
| No skin parameters. | |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
11.3.8. <rich:panelToggleListener>
<rich:panelToggleListener> tag to register a PanelToggleListener class on a parent <rich:collapsiblePanel> component. The class provided as a listener must implement the org.richfaces.event.PanelToggleListener interface. The processPanelToggle method accepts an org.richface.event.PanelToggleEvent event as a parameter.
11.4. <rich:popupPanel>
<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.
11.4.1. Basic usage
<rich:popupPanel> does not require any compulsory attributes, though certain use cases require different attributes.
11.4.2. Showing and hiding the pop-up
show="true" then the pop-up panel will display when the page is first loaded.
<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:
- Using the
<rich:componentControl>component. For details on the component, refer to Section 19.1, “<rich:componentControl>”. - Using the
rich:componentfunction. For details on the function, refer to Section 18.2, “rich:component”.
id identifier.
<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.
Example 11.2. <rich:popupPanel> example
<h:commandButton value="Show the panel"> <rich:componentControl target="popup" operation="show" /> </h:commandButton> ... <rich:popupPanel id="popup"> <p><a href="#" onclick="#{rich:component('popup')}.hide()">Hide the panel</a></p> </rich:popupPanel>
Placement
<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.
<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.
11.4.3. Modal and non-modal panels
<rich:popupPanel> appears as a modal window that blocks interaction with the other objects on the page. To implement a non-modal window instead, set modal="false". This will allow interaction with other objects outside the pop-up panel.
11.4.4. Size and positioning
minWith and minHeight attributes. These abilities can be deactivated by setting resizable or movable to false as necessary.
autosized attribute is set to true.
Embedded objects in the panel
<embed> tag could be rendered in front of a <rich:popupPanel> component in some browsers. The <rich:popupPanel> component can be forcibly rendered in front of these objects by setting overlapEmbedObjects="true".
overlapEmbedObjects attribute, applications can suffer from decreased performance. As such, overlapEmbedObjects should only be set to true when <embed> or <object> tags are being used in the parent view. Do not set it to true for applications that do not require it.
11.4.5. Header and controls
<rich:popupPanel> component through the use of facets. The header facet displays a title for the panel, and the controls facet can be customized to allow window controls such as a button for closing the pop-up. Example 11.3, “Header and controls” demonstrates the use of the facets.
Example 11.3. Header and controls
<h:commandLink value="Show pop-up"> <rich:componentControl target="popup" operation="show" /> </h:commandLink> ... <rich:popupPanel id="popup" modal="false" autosized="true" resizeable="false"> <f:facet name="header"> <h:outputText value="The title of the panel" /> </f:facet> <f:facet name="controls"> <h:graphicImage value="/pages/close.png" style="cursor:pointer" onclick="#{rich:component('popup')}.hide()" /> </f:facet> <p> This is the content of the panel. </p> </rich:popupPanel>
11.4.6. Contents of the pop-up
<rich:popupPanel> component can contain any other rich component just like a normal panel.
<rich:popupPanel> component which are positioned relatively may be trimmed if they extend beyond the borders of the pop-up panel. For certain in-line controls this behavior may be preferable, but for other dynamic controls it could be undesirable. If the trimOverlayedElements attribute is set to false then child components will not be trimmed if they extend beyond the borders of the pop-up panel. For example, if using a calendar, select, or other pop-up component, set trimOverlayedElements="false".
11.4.7. JavaScript API
<rich:popupPanel> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getTop()- Return the top co-ordinate for the position of the pop-up panel.
getLeft()- Return the left co-ordinate for the position of the pop-up panel.
moveTo(top,left)- Move the pop-up panel to the co-ordinates specified with the
topandleftparameters. resize(width,height)- Resize the pop-up panel to the size specified with the
widthandheightparameters. show()- Show the pop-up panel.
hide()- Hide the pop-up panel.
11.4.8. Reference data
component-type:org.richfaces.PopupPanelcomponent-class:org.richfaces.component.UIPopupPanelcomponent-family:org.richfaces.PopupPanelrenderer-type:org.richfaces.PopupPanelRenderer
11.4.9. Style classes and skin parameters
Table 11.4. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| No skin parameters. | |
| panelBorderColor
|
border
|
generalBackgroundColor
|
background
| |
| headerBackgroundColor
|
background
|
| headerTextColor
|
color
|
headerWeightFont
|
font-weight
| |
headerFamilyFont
|
font-family
| |
headerSizeFont
|
font-size
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| generalBackgroundColor
|
background
|
| No skin parameters. | |
| No skin parameters. | |
11.5. <rich:tabPanel>
<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 11.5.7, “<rich:tab>” for further details on the <rich:tab> component.
Form elements required
<rich:tabPanel> components should be wrapped in a form element when using either ajax or server mode, as usual for submitting components.
11.5.1. Switching panels
activeItem attribute holds the active tab name. This name is a reference to the name identifier of the active child <rich:tab> component.
switchType attribute, which can have one of the following three values:
server- The default setting. Activation of a
<rich:tab>component causes the parent<rich:tabPanel>component to perform a common submission, completely refreshing the page. Only one tab at a time is rendered to the client side. ajax- Activation of a
<rich:tab>component causes the parent<rich:tabPanel>component to perform an Ajax form submission, and the content of the tab panel is refreshed. Only one tab at a time is rendered to the client side. client- Activation of a
<rich:tab>component causes the parent<rich:tabPanel>component to update on the client side. All the tabs are rendered to the client during the initial page render. JavaScript changes the styles such that one tab becomes hidden while the other is shown.
11.5.2. <rich:tabPanel> client-side events
<rich:tabPanel> component uses the client-side events common to all switchable panels:
- The
itemchangeevent points to the function to perform when the switchable item is changed. - The
beforeitemchangeevent points to the function to perform when before the switchable item is changed.
11.5.3. <rich:tabPanel> server-side events
<rich:tabPanel> component uses the server-side events common to all switchable panels:
- The
ItemChangeEventevent occurs on the server side when an item is changed through Ajax using theservermode. It can be processed using theItemChangeListenerattribute. Refer to Section 11.6.6, “<rich:itemChangeListener>” for details on the<rich:itemChangeListener>tag.
11.5.4. JavaScript API
<rich:tabPanel> component can be controlled through the JavaScript API. The JavaScript API provides the following functions, which are common to all switchable panels:
getItems()- Return an array of the tabs contained in the tab panel.
getItemsNames()- Return an array of the names of the tabs contained in the tab panel.
switchToItem(itemName)- Switch to and display the item identified by the
itemNamestring passed as a parameter. firstItem(),prevItem(),nextItem(),lastItem()- Get the name of the first item, the previous item, the next item, or the last item.
11.5.5. Reference data
component-type:org.richfaces.TabPanelcomponent-class:org.richfaces.component.UITabPanelcomponent-family:org.richfaces.TabPanelrenderer-type:org.richfaces.TabPanelRendererhandler-class:org.richfaces.view.facelets.html.TogglePanelTagHandler
11.5.6. Style classes and skin parameters
Table 11.5. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| panelBorderColor
|
border
|
tabBackgroundColor
|
background-color
| |
generalTextColor
|
color
| |
| additionalBackgroundColor
|
background-color
|
| No skin parameters. | |
| tabDisabledTextColor
|
color
|
| additionalBackgroundColor
|
background-color
|
panelBorderColor
|
border-color
| |
| No skin parameters. | |
| panelBorderColor
|
border-bottom
|
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
| No skin parameters. | |
| additionalBackgroundColor
|
background
|
panelBorderColor
|
border
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| additionalBackgroundColor
|
background
|
panelBorderColor
|
border
| |
generalFamilyFont
|
font-family
| |
| tabBackgroundColor
|
background
|
panelBorderColor
|
border
| |
| generalBackgroundColor
|
background
|
panelBorderColor
|
border
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
11.5.7. <rich:tab>
<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.
11.5.7.1. Basic usage
<rich:tab> component requires only the tab header and tab content. No additional attributes are required.
header attribute provides the text on the tab header. The content of the tab is then detailed inside the <rich:tab> tags.
header facet could be used in place of the header attribute. This would allow custom components to be applied to the tab header. The component also supports three facets to customize the appearance depending on the current state of the tab:
headerActivefacet- This facet is used when the tab is the currently active tab.
headerInactivefacet- This facet is used when the tab is not currently active.
headerDisabledfacet- This facet is used when the tab is disabled.
header facet is used in place of any state-based facet that has not been defined.
11.5.7.2. Switching tabs
switchType attribute of the parent <rich:tabPanel> component, or set individually for each <rich:tab> component. Refer to Section 11.5, “<rich:tabPanel>” for details on the switchType attribute.
disabled="true". Disabled tabs cannot be activated or switched to.
11.5.7.3. <rich:tab> client-side events
<rich:tab> component uses the client-side events common to all switchable panel items:
- The
enterevent points to the function to perform when the mouse enters the tab. - The
leaveattribute points to the function to perform when the mouse leaves the tab.
11.5.7.4. Reference data
component-type:org.richfaces.Tabcomponent-class:org.richfaces.component.UITabcomponent-family:org.richfaces.Tabrenderer-type:org.richfaces.TabRenderer
11.5.7.5. Style classes and skin parameters
<rich:tab> component uses the same styles as those applied to the parent <rich:tabPanel> component. Refer to Section 11.5.6, “Style classes and skin parameters” for details.
11.6. <rich:togglePanel>
<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.
<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.
<rich:toggleControl>” and Section 11.6, “<rich:togglePanel>” for details on how to use the components together.
11.6.1. Basic usage
activeItem attribute, which points to a child component to display. Alternatively, if no activeItem attribute is defined, the initial state will be blank until the user activates a panel component with a connected <rich:toggleControl> behavior.
Form elements required
<rich:tabPanel> components should be wrapped in a form element when using either ajax or server mode, as usual for submitting components.
Example 11.4. Basic usage
<rich:togglePanel id="layout" activeItem="item1"> <rich:togglePanelItem name="item1"> <!--content--> </rich:togglePanelItem> <rich:togglePanelItem name="item2"> <!--content--> </rich:togglePanelItem> </rich:togglePanel> <h:commandButton> <rich:toggleControl targetPanel="layout"/> <!--cycles through the states--> </h:commandButton>
11.6.2. Dynamic panel item generation
<rich:togglePanel>, <rich:accordion> component and the <rich:tabPanel>) can leverage the <a4j:repeat> tag to dynamically create child components. This can be useful when the definition of the panel items is determined at run-time from a backing bean list.
11.6.3. Toggling between components
switchType attribute, which can have one of the following three values:
server- The default setting. Activation of a child component causes the parent
<rich:togglePanel>component to perform a common submission, completely refreshing the page. Only one child at a time is rendered to the client side. ajax- Activation of a child component causes the parent
<rich:togglePanel>component to perform an Ajax form submission, and the content of the panel is refreshed. Only one child at a time is rendered to the client side. client- Activation of a child component causes the parent
<rich:togglePanel>component to update on the client side. All the items are rendered to the client side during the initial page render. JavaScript changes the styles such that one child component becomes hidden while the other is shown.
11.6.4. JavaScript API
<rich:togglePanel> component can be controlled through the JavaScript API. The JavaScript API provides the following functions, which are common to all switchable panels:
getItems()- Return an array of the items contained in the toggle panel.
getItemsNames()- Return an array of the names of the items contained in the toggle panel.
switchToItem(itemName)- Switch to and display the item identified by the
itemNamestring passed as a parameter. firstItem(),prevItem(),nextItem(),lastItem()- Get the name of the first item, the previous item, the next item, or the last item.
11.6.5. Reference data
component-type:org.richfaces.TogglePanelcomponent-class:org.richfaces.component.UITogglePanelcomponent-family:org.richfaces.TogglePanelrenderer-type:org.richfaces.TogglePanelRendererhandler-class:org.richfaces.view.facelets.html.TogglePanelTagHandler
11.6.6. <rich:itemChangeListener>
<rich:itemChangeListener> tag to register an ItemChangeListener class on a parent panel component. The class provided as a listener must implement the org.richfaces.event.ItemChangeListener interface. The processItemChange method accepts an org.richface.event.ItemChangeEvent event as a parameter.
<rich:itemChangeListener> tag can be used with any of the switchable panel components:
<rich:togglePanel>(refer to Section 11.6, “<rich:togglePanel>”)<rich:accordion>(refer to Section 11.2, “<rich:accordion>”)<rich:tabPanel>(refer to Section 11.5, “<rich:tabPanel>”)<rich:panelMenu>(refer to Section 14.4, “<rich:panelMenu>”)
11.6.7. <rich:toggleControl>
<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 11.6, “<rich:togglePanel>” and Section 11.6.8, “<rich:togglePanelItem>” for details on how to use the components together.
<rich:toggleControl> implements the JSF BehaviorHolder component, which provides events to attached components and behaviors.
11.6.7.1. Basic usage
<rich:toggleControl> component is positioned inside a <rich:togglePanel> component, no panel attachment attributes need to be defined, as the control is assumed to switch through the <rich:togglePanelItem> components of its parent <rich:togglePanel> component.
<rich:toggleControl> component can be located outside the <rich:togglePanel> component it needs to switch. Where this is the case, the <rich:togglePanel> is identified using the targetPanel attribute.
11.6.7.2. Specifying the next state
<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.Example 11.5. Default switching
<rich:togglePanel id="layout"> <rich:togglePanelItem> <!--content--> </rich:togglePanelItem> <rich:togglePanelItem> <!--content--> <rich:togglePanelItem> </rich:togglePanel> <h:commandButton> <rich:toggleControl targetPanel="layout"/> <!--cycles through the states--> </h:commandButton>
- The next item to switch to can be explicitly defined by including a
<rich:toggleControl>component within a<rich:togglePanelItem>component. Point thetargetItemto the<rich:togglePanelItem>to switch to when the state is next changed.Example 11.6. Explicit switching
<rich:togglePanel activeItem="item1"> <rich:togglePanelItem id="item1"> <!--content--> <h:commandButton> <rich:toggleControl targetItem="item2"> <!--switches to item2 --> </h:commandButton> </rich:togglePanelItem> <rich:togglePanelItem id="item2"> <!--content--> <h:commandButton> <rich:toggleControl targetItem="item1"> <!--switches to item1 --> </h:commandButton> <rich:togglePanelItem> </rich:togglePanel>
- Alternatively, use the
targetItemattribute with keywords to switch items. The@first,@prev,@next, and@lastkeywords switch to the first item, the previous item, the next item, and the last item respectively.Example 11.7. Keyword-based switching
<rich:togglePanel activeItem="item1"> <rich:togglePanelItem id="item1"> <!--content--> <h:commandButton> <rich:toggleControl targetItem="@next"> <!--switches to next item (item2)--> </h:commandButton> </rich:togglePanelItem> <rich:togglePanelItem id="item2"> <!--content--> <h:commandButton> <rich:toggleControl targetItem="@prev"> <!--switches to previous item (item1)--> </h:commandButton> <rich:togglePanelItem> </rich:togglePanel>
11.6.7.3. Reference data
client-behavior-renderer-type:org.richfaces.component.behavior.ToggleControlbehavior-id:org.richfaces.component.behavior.ToggleControlhandler-class:org.richfaces.view.facelets.html.CustomBehaviorHandlerbehavior-class:org.richfaces.component.behavior.ToggleControlclient-behavior-renderer-class:org.richfaces.renderkit.html.ToggleControlRenderer
11.6.8. <rich:togglePanelItem>
<rich:togglePanelItem> component is a switchable panel for use with the <rich:togglePanel> component. Use the <rich:togglePanelItem> component to define the content for a panel using nested components. Switching between <rich:togglePanelItem> components is handled by the <rich:toggleControl> behavior.
11.6.8.1. Reference data
component-type:org.richfaces.TogglePanelItemcomponent-class:org.richfaces.component.UITogglePanelItemcomponent-family:org.richfaces.TogglePanelItemrenderer-type:org.richfaces.TogglePanelItemRenderer
Chapter 12. Tables and grids
12.1. <a4j:repeat>
<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.
<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.
12.1.1. Basic usage
value attribute. The var attribute names the object to use when iterating through the collection. This object is then referenced in the relevant child components. Example 12.1, “<a4j:repeat> example” shows how to use <a4j:repeat> to maintain a simple table.
Example 12.1. <a4j:repeat> example
<table> <tbody> <a4j:repeat value="#{repeatBean.items}" var="item"> <tr> <td><h:outputText value="#{item.code}" id="item1" /></td> <td><h:outputText value="#{item.price}" id="item2" /></td> </tr> </a4j:repeat> </tbody> </table>
repeatBeans.items data model.
12.1.2. Limited views and partial updates
<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.
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 inside the table
- Use
where the component identified by componentID is in the same row as the action component. The action component updates the single specified component, as demonstrated in Example 12.2, “Update a single component”.render=componentIDExample 12.2. Update a single component
<rich:column> <a4j:commandButton render="col"></a4j:commandButton> </rich:column> <rich:column> <h:outputText value="#{car.model}" id="col"/> </rich:column>
- Action components outside the table
- Use
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.render=tableId:rowId:cellIdInstead of a specific identifier, any of the references could be variables, as demonstrated in Example 12.3, “Use variables to specify references”.Example 12.3. Use variables to specify references
render=tableId:@rows(bean.rowToUpdate):cellIdThe@rowsfunction accepts a collection of row keys to be updated. Similarly thetable@bodyshorthand can be used to specify that the entire table body should be updated.
12.1.3. Reference data
component-type:org.richfaces.Repeatcomponent-class:org.richfaces.component.UIRepeatcomponent-family:javax.faces.Datarenderer-type:org.richfaces.RepeatRendererhandler-class:org.richfaces.taglib.html.RepeatHandler
12.2. <rich:dataTable>
<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.
<rich:extendedDataTable>
<rich:dataTable> component does not include extended table features, such as data scrolling (including lazy Ajax loading), row selection, and column reordering. These features are available as part of the <rich:extendedDataTable> component; refer to Section 12.6, “<rich:extendedDataTable>” for further details.
12.2.1. Basic usage
value attribute points to the data model, and the var attribute specifies a variable to use when iterating through the data model.
<rich:column> components to define the content of the table.
12.2.2. Customizing the table
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.
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.
Example 12.4. <rich:dataTable> example
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> <f:facet name="caption"> <h:outputText value="United States Capitals" /> </f:facet> <f:facet name="header"> <h:outputText value="Capitals and States Table" /> </f:facet> <rich:column> <f:facet name="header">State Flag</f:facet> <h:graphicImage value="#{cap.stateFlag}"/> <f:facet name="footer">State Flag</f:facet> </rich:column> <rich:column> <f:facet name="header">State Name</f:facet> <h:outputText value="#{cap.state}"/> <f:facet name="footer">State Name</f:facet> </rich:column> <rich:column > <f:facet name="header">State Capital</f:facet> <h:outputText value="#{cap.name}"/> <f:facet name="footer">State Capital</f:facet> </rich:column> <rich:column> <f:facet name="header">Time Zone</f:facet> <h:outputText value="#{cap.timeZone}"/> <f:facet name="footer">Time Zone</f:facet> </rich:column> <f:facet name="footer"> <h:outputText value="Capitals and States Table" /> </f:facet> </rich:dataTable>
12.2.3. Partial updates
<rich:dataTable> the component is based on the <a4j:repeat> component, it can be partially updated with Ajax. Refer to Section 12.1.2, “Limited views and partial updates” for details on partially updating the <rich:dataTable> component.
<rich:dataTable> component supports master-detail markup with collapsible sub-table sections. Refer to Section 12.5, “<rich:collapsibleSubTable>” for full details on using the <rich:collapsibleSubTable> component.
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 12.9, “<rich:dataScroller>” for full details on using the <rich:dataScroller> component.
12.2.4. Meta-components
- @scroll: The scrollable part of the table
- @header: The table header
- @footer: The table footer
- @body: The table body
12.2.5. JavaScript API
<rich:dataTable> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
expandAllSubTables()- Expand any sub-tables contained in the data table.
collapseAllSubTables()- Collapse any sub-tables contained in the data table.
switchSubTable(subtableId)- Switch the expanded or collapsed state of any sub-tables contained in the data table.
filter(columnId, newFilterValue, [isClearPreviousFilters])- Filter the table based on the column specified with the
columnIdparameter. Use thenewFilterValueparameter as the filter value. The optionalisClearPreviousFiltersparameter is a boolean value which, if set totrue, will clear any previous filters applied to the table. sort(columnId, [direction], [isClearPreviousSorting])- Sort the table based on the column specified with the
columnIdparameter. The optiondirectionparameter specifies whether to sort in ascending or descending order. The optionalisClearPreviousSortingparameter is a boolean value which, if set totrue, will clear any previous sorting applied to the table.
12.2.6. Reference data
component-type:org.richfaces.DataTablecomponent-class:org.richfaces.component.UIDataTablecomponent-family:org.richfaces.Datarenderer-type:org.richfaces.DataTableRendererhandler-class:org.richfaces.taglib.DataTableHandler
12.2.7. Style classes and skin parameters
Table 12.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| tableBackgroundColor
|
background-color
|
tableBorderWidth
|
border-left-width, border-top-width
| |
tableBorderColor
|
border-left-color, border-top-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| tableBorderWidth
|
border-bottom-width, border-right-width
|
tableBorderColor
|
border-bottom-color, border-right-color
| |
generalTextColor
|
color
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
12.3. <rich:column>
<rich:column> component facilitates columns in a table. It supports merging columns and rows, sorting, filtering, and customized skinning.
12.3.1. Basic usage
<rich:column> component is used in the same was as the JavaServer Faces (JSF) <h:column> component. It requires no extra attributes for basic usage, as shown in Example 12.5, “Basic column example”.
Example 12.5. Basic column example
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> <rich:column> <f:facet name="header">State Flag</f:facet> <h:graphicImage value="#{cap.stateFlag}"/> </rich:column> <rich:column> <f:facet name="header">State Name</f:facet> <h:outputText value="#{cap.state}"/> </rich:column> <rich:column > <f:facet name="header">State Capital</f:facet> <h:outputText value="#{cap.name}"/> </rich:column> <rich:column> <f:facet name="header">Time Zone</f:facet> <h:outputText value="#{cap.timeZone}"/> </rich:column> </rich:dataTable>
12.3.2. Spanning columns
colspan attribute to specify how many normal columns to span. The colspan attribute is used in conjunction with the breakRowBefore attribute on the next column to determine how the merged columns are laid out. Example 12.6, “Column spanning example”.
Example 12.6. Column spanning example
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> <rich:column colspan="3"> <h:graphicImage value="#{cap.stateFlag}"/> </rich:column> <rich:column breakBefore="true"> <h:outputText value="#{cap.state}"/> </rich:column> <rich:column > <h:outputText value="#{cap.name}"/> </rich:column> <rich:column> <h:outputText value="#{cap.timeZone}"/> </rich:column> </rich:dataTable>
12.3.3. Spanning rows
rowspan attribute can be used to merge and span rows. Again the breakRowBefore attribute needs to be used on related <rich:column> components to define the layout. Example 12.7, “Row spanning example” and the resulting Figure 12.5, “Complex headers using column groups” show the first column of the table spanning three rows.
Example 12.7. Row spanning example
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> <rich:column rowspan="3"> <f:facet name="header">State Flag</f:facet> <h:graphicImage value="#{cap.stateFlag}"/> </rich:column> <rich:column> <f:facet name="header">State Info</f:facet> <h:outputText value="#{cap.state}"/> </rich:column> <rich:column breakBefore="true"> <h:outputText value="#{cap.name}"/> </rich:column> <rich:column breakBefore="true"> <h:outputText value="#{cap.timeZone}"/> </rich:column> </rich:dataTable>
12.3.4. Reference data
component-type:org.richfaces.Columncomponent-class:org.richfaces.component.UIColumncomponent-family:org.richfaces.Column
12.4. <rich:columnGroup>
<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.
12.4.1. Complex headers
<rich:columnGroup> can also be used to create complex headers in a table. Example 12.8, “Complex headers using column groups” and the resulting Figure 12.5, “Complex headers using column groups” demonstrate how complex headers can be achieved.
Example 12.8. Complex headers using column groups
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5" id="sublist"> <f:facet name="header"> <rich:columnGroup> <rich:column rowspan="2"> <h:outputText value="State Flag"/> </rich:column> <rich:column colspan="3"> <h:outputText value="State Info"/> </rich:column> <rich:column breakBefore="true"> <h:outputText value="State Name"/> </rich:column> <rich:column> <h:outputText value="State Capital"/> </rich:column> <rich:column> <h:outputText value="Time Zone"/> </rich:column> </rich:columnGroup> </f:facet> <rich:column> <h:graphicImage value="#{cap.stateFlag}"/> </rich:column> <rich:column> <h:outputText value="#{cap.state}"/> </rich:column> <rich:column> <h:outputText value="#{cap.name}"/> </rich:column> <rich:column> <h:outputText value="#{cap.timeZone}"/> </rich:column> </rich:dataTable>
12.4.2. Reference data
component-type:org.richfaces.ColumnGroupcomponent-class:org.richfaces.component.UIColumnGroupcomponent-family:org.richfaces.ColumnGrouprenderer-type:org.richfaces.ColumnGroupRenderer
12.5. <rich:collapsibleSubTable>
<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.
<rich:collapsibleSubTable> component works with the <rich:collapsibleSubTableToggler> component, which expands and collapses the sub-tables.
12.5.1. Basic usage
<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.
<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 12.5.5, “<rich:collapsibleSubTableToggler>” for details on the <rich:collapsibleSubTableToggler> component.
Example 12.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>

12.5.2. Expanding and collapsing the sub-table
expanded attribute to control the current state of the sub-table.
expandMode attribute, which can have one of the following three values:
server- The default setting. Expansion of the
<rich:collapsibleSubTable>component performs a common submission, completely re-rendering the page. ajax- Expansion of the
<rich:collapsibleSubTable>component performs an Ajax form submission, and the content of the data table is rendered. client- Expansion of the
<rich:collapsibleSubTable>component updates the data table on the client side.
12.5.3. Reference data
component-type:org.richfaces.CollapsibleSubTablecomponent-class:org.richfaces.component.UICollapsibleSubTablecomponent-family:org.richfaces.Datarenderer-type:org.richfaces.CollapsibleSubTableRendererhandler-class:org.richfaces.taglib.CollapsibleSubTableHandler
12.5.4. Style classes
Table 12.2. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
12.5.5. <rich:collapsibleSubTableToggler>
<rich:collapsibleSubTableToggler> component provides a toggle control for the user to expand and collapse sub-tables.
12.5.5.1. Basic usage
<rich:collapsibleSubTableToggler> component requires the for attribute. The for attribute references the id identifier of the <rich:collapsibleSubTable> component to control.
<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.
12.5.5.2. Appearance
<rich:collapsibleSubTableToggler> component can be customized. Use the collapsedIcon and expandedIcon attributes to specify icons for the toggler when it is collapsed and expanded respectively. Use the collapsedLabel and expandedLabel attributes to specify labels for the toggler when it is collapsed and expanded respectively.
12.5.5.3. Reference data
component-type:org.richfaces.CollapsibleSubTableTogglercomponent-class:org.richfaces.component.UICollapsibleSubTableToggleControlcomponent-family:org.richfaces.CollapsibleSubTableTogglerrenderer-type:org.richfaces.CollapsibleSubTableTogglerRenderer
12.5.5.4. Style classes and skin parameters
Style classes (selectors)
- .rf-csttg
- This class defines styles for a toggle control.
- .rf-csttg-exp
- This class defines styles for a toggle control which expands the sub-table.
- .rf-csttg-colps
- This class defines styles for a toggle control which collapses the sub-table.
12.6. <rich:extendedDataTable>
<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.
<rich:extendedDataTable> component includes the following main attributes not included in the <rich:dataTable> component:
clientRowsfrozenColumnsheightonselectionchangeselectedClassselectionselectionMode
Complex sub-tables
<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.
breakRowBefore, colSpan, and rowSpan attributes is also not available with the <rich:extendedDataTable> component.
12.6.1. Basic usage
<rich:extendedDataTable> component requires the value and var attributes, the same as with the <rich:dataTable> component. In addition, a set of columns must be included to define the table content. Refer to Section 12.2, “<rich:dataTable>” for details.
12.6.2. Table appearance
<rich:dataTable> component, the look of the <rich:extendedDataTable> component can be customized using the header and footer facets.
12.6.3. Extended features
Example 12.10. <rich:extendedDataTable> 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>

12.6.3.1. Scrolling
<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.
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.
<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 12.9, “<rich:dataScroller>” for full details on using the <rich:dataScroller> component.
12.6.3.2. Frozen columns
<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.
12.6.3.3. Row selection
selectionMode attribute. Setting the attribute to none allows for no row selection capability. The example table shown in Example 12.10, “<rich:extendedDataTable> example” does not allow row selection.
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.
selection attribute points to a collection of objects. It holds the rowKey identifiers to track which rows are selected. Example 12.11, “Selecting multiple rows” shows how to implement multiple row selection in the same table from Example 12.10, “<rich:extendedDataTable> example”.
Example 12.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"> ...
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; } }

12.6.3.4. Rearranging columns
<rich:extendedDataTable> component can be rearranged by the user by dragging each column to a different position. A graphical representation of the column is displayed during dragging. Figure 12.6, “Dragging columns” illustrates the Price column being dragged to a new location. The small blue arrow indicates where the column will be moved to if it is dropped in the current position. Figure 12.7, “Rearranged columns” shows the result of dragging the Price column.
12.6.3.5. State saving
tableState attribute of the <rich:extendedDataTable> component can be used to bind state of the table (column width, sequence, sorting, filtering) to a backing-bean string property, for a later use. This state can be for example saved to a database, and it is different from standard JSF state saving mechanism.
12.6.3.6. Meta-components
- @scroll: The scrollable part of the table
- @header: The table header
- @footer: The table footer
- @body: The table body
12.6.3.7. Filtering and sorting
<rich:extendedDataTable> component can include filtering and sorting in the same way as a regular <rich:dataTable> component. For full details on filtering tables, refer to Section 12.10, “Table filtering”. For full details on sorting tables, refer to Section 12.11, “Table sorting”.
12.6.4. JavaScript API
<rich:extendedDataTable> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
sort()- Sort the data table.
filter()- Filter the data table.
clearSorting()- Clear any sorting that is currently applied to the table.
clearFiltering()- Clear any filtering that is currently applied to the table.
selectRow(index)- Select the row specified by the
indexparameter. selectRows([startIndex, stopIndex])- Select all the rows in the table. Optionally, select only those rows between the indexes specified with the
startIndexandstopIndexparameters. deselectRow- Deselect the row that is currently selected.
setActiveRow(index)- Set the active row to that specified by the
indexparameter.
12.6.5. Reference data
component-type:org.richfaces.ExtendedDataTablecomponent-class:org.richfaces.component.UIExtendedDataTablecomponent-family:org.richfaces.Datarenderer-type:org.richfaces.ExtendedDataTableRendererhandler-class:org.richfaces.taglib.ExtendedDataTableHandler
12.6.6. Style classes and skin parameters
Table 12.3. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| tableBorderWidth, tableBorderColor
|
border
|
tableBackgroundColor
|
background-color
| |
| No skin parameters. | |
| tableBorderWidth, tableBorderColor
|
border-bottom
|
tableBorderWidth, tableBorderColor
|
border-right
| |
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
| tableBorderWidth, tableBorderColor
|
border-bottom
|
tableHeaderTextColor
|
color
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
tableHeaderTextColor
|
color
| |
| No skin parameters. | |
| tableBorderWidth, tableBorderColor
|
border-bottom
|
tableBorderWidth, tableBorderColor
|
border-right
| |
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
tableHeaderTextColor
|
color
| |
| tableBorderWidth, tableBorderColor
|
border-top
|
tableFooterBackgroundColor
|
background-color
| |
| tableBorderWidth, tableBorderColor
|
border-top
|
tableFooterBackgroundColor
|
background-color
| |
| No skin parameters. | |
| tableBorderWidth, tableBorderColor
|
border-bottom
|
tableBorderWidth, tableBorderColor
|
border-right
| |
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
generalTextColor
|
color
| |
| tableBorderWidth, tableBorderColor
|
border-right
|
| No skin parameters. | |
| No skin parameters. | |
| tableBorderWidth, tableBorderColor
|
border-right
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| generalTextColor
|
border-left
|
| tableBorderWidth, tableBorderColor
|
border
|
tableHeaderBackgroundColor / tableBackgroundColor
|
background-color
| |
| No skin parameters. | |
| No skin parameters. | |
12.7. <rich:dataGrid>
<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.
<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.
12.7.1. Basic usage
<rich:dataGrid> component requires the value attribute, which points to the data model, and the var attribute, which holds the current variable for the collection of data.
12.7.2. Customizing the grid
columns attribute, and the number of elements to layout among the columns is determined with the elements attribute. The first attribute references the zero-based element in the data model from which the grid starts.
Example 12.12. <rich:dataGrid> example
<rich:panel style="width:150px;height:200px;"> <h:form> <rich:dataGrid value="#{dataTableScrollerBean.allCars}" var="car" columns="2" elements="4" first="1"> <f:facet name="header"> <h:outputText value="Car Store"></h:outputText> </f:facet> <rich:panel> <f:facet name="header"> <h:outputText value="#{car.make} #{car.model}"></h:outputText> </f:facet> <h:panelGrid columns="2"> <h:outputText value="Price:" styleClass="label"></h:outputText> <h:outputText value="#{car.price}"/> <h:outputText value="Mileage:" styleClass="label"></h:outputText> <h:outputText value="#{car.mileage}"/> </h:panelGrid> </rich:panel> <f:facet name="footer"> <rich:dataScroller></rich:dataScroller> </f:facet> </rich:dataGrid> </h:form> </rich:panel>
12.7.3. Partial updates
<rich:dataGrid> the component is based on the <a4j:repeat> component, it can be partially updated with Ajax. Refer to Section 12.1.2, “Limited views and partial updates” for details on partially updating the <rich:dataGrid> component.
12.7.4. Reference data
component-type:org.richfaces.DataGridcomponent-class:org.richfaces.component.UIDataGridcomponent-family:org.richfaces.Datarenderer-type:org.richfaces.DataGridRendererhandler-class:org.richfaces.taglib.DataGridHandler
12.7.5. Style classes and skin parameters
Table 12.4. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| tableBackgroundColor
|
background-color
|
tableBorderWidth
|
border-left-width, border-top-width
| |
tableBorderColor
|
border-left-color, border-top-color
| |
| No skin parameters. | |
| No skin parameters. | |
| tableBorderWidth
|
border-bottom-width, border-right-width
|
tableBorderColor
|
border-bottom-color, border-right-color
| |
generalTextColor
|
color
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| tableBorderWidth
|
border-bottom-width, border-right-width
|
tableBorderColor
|
border-bottom-color, border-right-color
| |
generalTextColor
|
color
| |
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| tableBorderWidth
|
border-bottom-width
|
tableBorderColor
|
border-bottom-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
| No skin parameters. | |
| No skin parameters. | |
| 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
| |
12.8. <rich:list>
<rich:list> component renders a list of items. The list can be an numerically ordered list, an un-ordered bullet-point list, or a data definition list. The component uses a data model for managing the list items, which can be updated dynamically.
12.8.1. Basic usage
var attribute names a variable for iterating through the items in the data model. The items to iterate through are determined with the value attribute by using EL (Expression Language).
12.8.2. Type of list
type attribute is used to specify different list types:
unordered- The default presentation. The list is presented as a series of bullet-points, similar to the
<ul>HTML element. ordered- The list is presented as a numbered series of items, similar to the
<ol>HTML element. definitions- The list is presented as a series of data definitions. Part of the data model, specified as the term, is listed prominently. The other associated data is listed after each term.The term is marked using the
termfacet. The facet is required for all definition lists. Use of the facet is shown in Example 12.13, “Data definition list”.Example 12.13. Data definition list
<h:form> <rich:list var="car" value="#{dataTableScrollerBean.allCars}" type="definitions" rows="5" title="Cars"> <f:facet name="term"> <h:outputText value="#{car.make} #{car.model}"></h:outputText> </f:facet> <h:outputText value="Price:" styleClass="label"></h:outputText> <h:outputText value="#{car.price}" /><br/> <h:outputText value="Mileage:" styleClass="label"></h:outputText> <h:outputText value="#{car.mileage}" /><br/> </rich:list> </h:form>
12.8.3. Bullet and numeration appearance
12.8.4. Customizing the list
first attribute specifies which item in the data model to start from, and the rows attribute specifies the number of items to list. The title attribute is used for a floating tool-tip. Example 12.14, “<rich:list> example” shows a simple example using the <rich:list> component.
Example 12.14. <rich:list> example
<h:form> <rich:list var="car" value="#{dataTableScrollerBean.allCars}" rows="5" type="unordered" title="Car Store"> <h:outputText value="#{car.make} #{car.model}"/><br/> <h:outputText value="Price:" styleClass="label"></h:outputText> <h:outputText value="#{car.price} "/><br/> <h:outputText value="Mileage:" styleClass="label"></h:outputText> <h:outputText value="#{car.mileage} "/><br/> </rich:list> </h:form>
12.8.5. Reference data
component-type:org.richfaces.Listcomponent-class:org.richfaces.component.UIListcomponent-family:org.richfaces.Listrenderer-type:org.richfaces.ListRendererhandler-class:org.richfaces.taglib.ListHandler
12.8.6. Style classes and skin parameters
Table 12.5. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
|
12.9. <rich:dataScroller>
<rich:dataScroller> component is used for navigating through multiple pages of tables or grids.
12.9.1. Basic usage
<rich:dataScroller> must be placed in a facet of the table or grid it needs to control. Alternatively, use the for attribute to bind the parent table or grid to the scroller.
rows attribute defined to limit the number of rows per page.
<rich:dataScroller> component must be re-rendered whenever a filter changes on the bound table, so that the scroller matches the current model for the table.
Example 12.15. Basic usage
<rich:dataTable id="table" value="#{capitalsBean.capitals}" var="cap" rows="5"> <!-- table content --> ... </rich:dataTable> <rich:dataScroller for="table" maxPages="5"> <f:facet name="first"> <h:outputText value="First" /> </f:facet> <f:facet name="last"> <h:outputText value="Last" /> </f:facet> </rich:dataScroller>
12.9.2. Appearance and interactivity
page attribute is a value-binding attribute used to define and save the current page number.
<rich:dataScroller> component provides a range of controllers for scrolling through tables and grids:
- Controls for scrolling by a specific amount
- The component includes controls for switching to the first page, the last page, the next page, and the previous page, as well as controls for fast-forwarding or rewinding by a set amount. Use the
fastStepattribute to set the number of pages to skip when fast-forwarding or rewinding.The appearance of these controls can be customized using the following facets:first,last,next,previous,fastForward, andfastRewind. Additionally, there are facets for the controls' disabled states:first_disabled,last_disabled,next_disabled,previous_disabled,fastForward_disabled, andfastRewind_disabled. - Page controls
- The component also features a series of numbered controls to jump to a specific page. Use the
maxPagesattribute to limit the number of page controls that appear. The current page control is highlighted.
controlsSeparator facet.
12.9.3. JavaScript API
<rich:dataScroller> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
switchToPage(pageIndex)- Switch to the page specified with the
pageIndexparameter. next()- Switch to the next page.
previous()- Switch to the previous page.
first()- Switch to the first page.
last()- Switch to the last page.
fastForward()- Step forward through the pages by the
fastStepamount. fastRewind()- Step backward through the pages by the
fastStepamount.
12.9.4. Reference data
component-type:org.richfaces.DataScrollercomponent-class:org.richfaces.component.UIDataScrollercomponent-family:org.richfaces.DataScrollerrenderer-type:org.richfaces.DataScrollerRendererhandler-class:org.richfaces.taglib.DataScrollerHandler
12.9.5. Style classes and skin parameters
Table 12.6. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
tableBackgroundColor
|
background
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
tableBorderColor
|
border-color
| |
headerBackgroundColor
|
background-color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
tableBorderColor
|
border-color
| |
tableBackgroundColor
|
background-color
| |
| tableBorderColor
|
border-color
|
tableBackgroundColor
|
background
| |
| tableBorderColor
|
color
|
| tableBorderColor
|
color
|
12.10. Table filtering
<rich:column>” for details on using the <rich:column> component in tables.
12.10.1. Filter Definition
filter or filterExpression attributes, then use the filterValue attribute to point to an object which holds the current filtering value for the column. The attribute can be used to store filtering conditions in a session.
filterExpression attribute to define an expression that can be evaluated as a boolean value. The expression checks if each table entry satisfies the filtering condition when the table is rendered. For example, the expression might be a JSTL (JavaServer Pages Standard Tag Library) function such as contains or equals.
filter attribute to define a filter interface. The attribute must use EL (Expression Language) to point to an object which implements the org.richfaces.model.Filter<T> interface. The object must provide a single accept(T t) method. The method takes each iteration object as a parameter and returns a boolean value, which determines whether the object satisfies the filter. By defining a custom filter, you can implement complex business logic to filter a table.
12.10.2. Built-in filter controls
<rich:column> component allow the user to enter text to use as the filtering value. The value of the built-in filter control is bound to the filterValue attribute, which can either be an initial filtering value on the page, or a value binding on the server. The filterValue is then applied to the filter defined either by the filterExpression or filter column attributes.
String. Conversion is either done implicitly via EL in the filterExpression, or explicitly within the filter function. The filter is processed and the table is rendered when the onblur event occurs for the column.
Example 12.16. Basic filtering
<rich:extendedDataTable value="#{carsBean.allInventoryItems}" var="car" filterVar="filterValue"> <f:facet name="header"> <h:outputText value="Cars marketplace"/> </f:facet> <rich:column filterExpression="#{empty filterValue or fn:startsWith(car.model, filterValue)}" filterValue="#{carsFilteringBean.modelFilter}"> <f:facet name="header">Model</f:facet> <h:outputText value="#{car.model}"/> </rich:column> <rich:column filterExpression="#{empty filterValue or car.price ge filterValue}" filterValue="#{carsFilteringBean.priceFilter}" filterConverterMessage="Error converting the 'Price' filter value"> <f:facet name="header">Price</f:facet> <h:outputText value="#{car.price}"/> </rich:column> </rich:extendedDataTable>
12.10.3. External filter controls
<rich:column> component. With custom filter controls you can tailor the filter control, allowing for advanced use cases like select menus, checkboxes, etc. To use a custom filter control with the extendedDataTable component, one must first disable the built-in filter control.
Disabling built-in filter controls
filterType="custom". Alternatively one can disable filter controls for the whole application via the following context-param in the web.xml:
<context-param> <param-name>org.richfaces.builtin.filter.enabled</param-name> <param-value>false</param-value> </context-param>
Example 12.17. Filtering example
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table"> <f:facet name="header"> <rich:columnGroup> <rich:column> <h:outputText value="State Name" /> </rich:column> <rich:column> <h:outputText value="State Time Zone" /> </rich:column> </rich:columnGroup> </f:facet> <rich:column filter="#{filteringBean.stateFilter}"> <f:facet name="header"> <h:inputText value="#{filteringBean.stateFilterValue}" id="input"> <a4j:ajax event="keyup" render="table@body"> <a4j:attachQueue requestDelay="700" ignoreDupResponses="true" /> </a4j:ajax> </h:inputText> </f:facet> <h:outputText value="#{cap.state}" /> </rich:column> <rich:column filterExpression="#{fn:containsIgnoreCase(cap.timeZone, filteringBean.zoneFilterValue)}"> <f:facet name="header"> <h:selectOneMenu value="#{filteringBean.zoneFilterValue}"> <f:selectItems value="#{filteringBean.zoneList}" /> <a4j:ajax event="change" render="table@body" /> </h:selectOneMenu> </f:facet> <h:outputText value="#{cap.timeZone}" /> </rich:column> </rich:dataTable>

12.11. Table sorting
<rich:column>” for details on using the <rich:column> component in tables.
Sorting non-English tables
org.richfaces.datatableUsesViewLocale context parameter to the project's web.xml settings file. Set the value of the context parameter to true.
12.11.1. Comparator Definition
comparator attribute of the <rich:column> to specify the comparator to use when sorting. If no comparator is specified, the sorting algorithm will invoke the entries compareTo method of the sortBy values if they implement the java.lang.Comparable interface. As a final fall back, the algorithm implements a null sort, sorting elements based on whether or not they are null.
12.11.2. Built-in sort controls
<rich:column> component allow a user to click the sort icons of a column to sort it in ascending or descending order.
sortBy attribute to indicate which value to use when sorting the column. Expressions in the sortBy attribute must refer to the variable declared in the table's var attribute, which is used to fill the contents of the table.
Example 12.18. Basic sorting
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px"> <rich:column sortBy="#{cap.state}"> <f:facet name="header"> <h:outputText value="State Name"/> </f:facet> <h:outputText value="#{cap.state}"/> </rich:column> <rich:column sortBy="#{cap.name}"> <f:facet name="header"> <h:outputText value="State Capital"/> </f:facet> <h:outputText value="#{cap.name}"/> </rich:column> </rich:dataTable>
sortOrder attribute to set how the table's contents are sorted when it is first loaded. By default, the value of the sortOrder attribute is unsorted, so that table entries appear in the order the are contained in the data model. Use sortOrder="ascending" to sort the entries in ascending alphabetical or numerical order. Use sortOrder="descending" to sort the entries in descending alphabetical or numerical order. The sortOrder attribute can also be used to externally set the sort order of a table when using the external sorting method; refer to Section 12.11.3, “External sort controls” for details.
12.11.3. External sort controls
sortBy attribute to indicate which iteration object property to use when sorting the column. If using custom-defined rules for sorting, use the comparator attribute instead. Set the comparator attribute to point to your comparator method, which will be used when sorting the data model.
Disabling built-in sort controls
sortType="custom". Alternatively one can disable sort controls for the whole application via the following context-param in the web.xml:
<context-param> <param-name>org.richfaces.builtin.sort.enabled</param-name> <param-value>false</param-value> </context-param>
sortOrder attribute to bean properties to manage the sorting order. The bean must handle all the sorting algorithms. Example 12.19, “Sorting” demonstrates table sorting using an external control.
Example 12.19. Sorting
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table"> <rich:column> <f:facet name="header"> State Flag </f:facet> <h:graphicImage value="#{cap.stateFlag}" alt="flag" /> </rich:column> <rich:column sortBy="#{cap.name}" id="name" sortOrder="#{capitalsSortingBean.capitalsOrder}"> <f:facet name="header"> <a4j:commandLink value="Sort by Capital Name" render="table" action="#{capitalsSortingBean.sortByCapitals}" /> </f:facet> <h:outputText value="#{cap.name}" /> </rich:column> <rich:column sortBy="#{cap.state}" id="state" sortOrder="#{capitalsSortingBean.statesOrder}"> <f:facet name="header"> <a4j:commandLink value="Sort by State Name" render="table" action="#{capitalsSortingBean.sortByStates}" /> </f:facet> <h:outputText value="#{cap.state}" /> </rich:column> <rich:column sortBy="#{cap.timeZone}" id="timeZone" comparator="#{capitalsSortingBean.timeZoneComparator}" sortOrder="#{capitalsSortingBean.timeZonesOrder}"> <f:facet name="header"> <a4j:commandLink value="Sort by Time Zone" render="table" action="#{capitalsSortingBean.sortByTimeZones}" /> </f:facet> <h:outputText value="#{cap.timeZone}" /> </rich:column> </rich:dataTable>
sortPriorities attribute. The attribute must contain a list of column identifiers in the order of the sorting sequence.
Chapter 13. Trees
13.1. <rich:tree>
<rich:tree> component provides a hierarchical tree control. Each <rich:tree> component typically consists of <rich:treeNode> child components. The appearance and behavior of the tree and its nodes can be fully customized.
13.1.1. Basic usage
<rich:tree> component requires the value attribute to point to the data model for populating the tree. The data model must be either an org.richfaces.model.TreeNode interface, an org.richfaces.model.TreeDataModel interface, or a javax.swing.tree.TreeNode interface. The var attribute declares the variable used for iterating through the data model, so that child <rich:treeNode> components can reference each iteration.
<rich:tree> component needs one or more <rich:treeNode> components to work with the data model. However if no <rich:treeNode> components are provided the tree creates default nodes instead.
Example 13.1. Basic usage
<rich:tree> component using an org.richfaces.model.TreeNode data model.
org.richfaces.model.TreeNodeImpl and add the data fields you require, with appropriate accessor methods, as in:
import org.richfaces.model.TreeNodeImpl; public class DataHolderTreeNodeImpl extends TreeNodeImpl { private Object data; public DataHolderTreeNodeImpl() { super(); } public DataHolderTreeNodeImpl(boolean leaf, Object data) { super(leaf); this.data = data; } public Object getData() { return data; } @Override public String toString() { return super.toString() + " >> " + data; } }
private DataHolderTreeNodeImpl stationRoot; private DataHolderTreeNodeImpl rootNodes; public DataHolderTreeNodeImpl getRootNodes() { if (rootNodes == null) { String[] kickRadioFeed = {"Hall & Oates - Kiss On My List", "David Bowie - Let's Dance", "Lyn Collins - Think (About It)", "Kim Carnes - Bette Davis Eyes", "KC & the Sunshine Band - Give It Up"}; stationRoot = new DataHolderTreeNodeImpl(false, "KickRadio"); for (int i = 0; i<kickRadioFeed.length; i++) { DataHolderTreeNodeImpl child = new DataHolderTreeNodeImpl(true, kickRadioFeed[i]); stationRoot.addChild(i, child); } rootNodes = new DataHolderTreeNodeImpl(); rootNodes.addChild(0, stationRoot); } return rootNodes; }
station variable:
<rich:tree value="#{stations.stationNodes}" var="station"> <rich:treeNode> <h:outputText value="#{station}" /> </rich:treeNode> </rich:tree>

13.1.2. Appearance
nodeType attribute to differentiate the types of nodes; the node is then rendered according to the <rich:treeNode> component with the corresponding type attribute. Example 13.2, “nodeType attribute” shows a <rich:tree> component with three different child <rich:treeNode> components defined to represent three different node appearances. Refer to Section 13.1.10.2, “Appearance” for details on customizing the appearance of <rich:treeNode> components.
Example 13.2. nodeType attribute
<rich:tree style="width:300px" value="#{library.data}" var="item" nodeType="#{item.type}"> <rich:treeNode type="artist" iconExpanded="/images/tree/singer.png" iconCollapsed="/images/tree/singer.png"> <h:outputText value="#{item.name}" /> </rich:treeNode> <rich:treeNode type="album" iconExpanded="/images/tree/disc.png" iconCollapsed="/images/tree/disc.png"> <h:outputText value="#{item.album}" /> </rich:treeNode> <rich:treeNode type="song" iconLeaf="/images/tree/song.png"> <h:outputText value="#{item.title}" /> </rich:treeNode> </rich:tree>

nodeType attribute returns null, the node is rendered as a "typeless" (or default) node. The typeless node is the first child <rich:treeNode> component with a valid rendered attribute, but without a defined type attribute.
nodeType attribute is not included and there are no child <rich:treeNode> components, the tree constructs a default node itself.
iconLeaf- The
iconLeafattribute points to the icon to use for any node that does not contain any child nodes. iconExpandedandiconCollapsed- The
iconExpandedandiconCollapsedattributes point to the icons to use for expanded and collapsed nodes respectively. If these attributes are defined, theiconattribute is not used.
13.1.3. Expanding and collapsing tree nodes
toggleType attribute, which can have one of the following three values:
ajax- This is the default setting. The
<rich:tree>component performs an Ajax form submission, and only the content of the tree is rendered. server- The
<rich:tree>component performs a common submission, completely refreshing the page. client- The
<rich:tree>component updates on the client side through JavaScript, without any additional requests or updates. All nodes are rendered to the client during the initial page rendering.
toggleNodeEvent attribute.
13.1.4. Selecting tree nodes
selectionType attribute, which can have one of the following three values:
ajax- This is the default setting. The
<rich:tree>component performs an Ajax form submission, and only the content of the tree is rendered. client- The
<rich:tree>component updates on the client side using JavaScript, without any additional requests or updates.
13.1.5. Identifying nodes with the rowKeyConverter attribute
<rich:tree> component uses a custom data model, the data model provides unique keys for tree nodes so they can be identified during a client request. The <rich:tree> component can use strings as key values. These strings may contain special characters that are not allowed by browsers, such as the left angle bracket (<) and ampersand (&). To allow these characters in the keys, a row key converter must be provided.
<rich:tree> component, define it with the rowKeyConverter attribute.
13.1.6. Event handling
<rich:tree> component uses the following client-side events:
- The
nodetoggleevent is triggered when a node is expanded or collapsed. - The
beforenodetoggleevent is triggered before a node is expanded or collapsed. - The
selectionchangeevent is triggered when a node is selected. - The
beforeselectionchangeevent is triggered before a node is selected.
<rich:tree> component uses the following server-side listeners:
- The
toggleListenerlistener processes expand and collapse events. - The
selectionChangeListenerlistener processes the request when a node is selected.
13.1.7. Reference data
component-type:org.richfaces.Treecomponent-class:org.richfaces.component.UItreecomponent-family:org.richfaces.Treerenderer-type:org.richfaces.TreeRendererhandler-class:org.richfaces.view.facelets.TreeHandler
13.1.8. Style classes
<rich:tree> component is mostly applied to the tree nodes. Refer to Section 13.1.10.5, “Style classes and skin parameters” for details on styling tree nodes. In addition, the <rich:tree> component can make use of the style classes outlined in Style classes (selectors).
Style classes (selectors)
- .rf-tr-nd
- This class defines styles for the nodes in a tree.
- .rf-tr-nd-last
- This class defines styles for last node in a tree.
- .rf-tr-nd-colps
- This class defines styles for a collapsed tree node.
- .rf-tr-nd-exp
- This class defines styles for an expanded tree node.
13.1.9. <rich:treeSelectionChangeListener>
<rich:treeSelectionChangeListener> tag to register a TreeSelectionChangeListener class on a parent <rich:tree> component. The class provided as a listener must implement the org.richfaces.event.TreeSelectionChangeListener interface. The processTreeSelectionChange method accepts an org.richface.event.TreeSelectionChangeEvent event as a parameter.
13.1.10. <rich:treeNode>
<rich:treeNode> component is a child component of the <rich:tree> component. It represents nodes in the parent tree. The appearance and functionality of each tree node can be customized.
13.1.10.1. Basic usage
<rich:treeNode> component must be a child of a <rich:tree> component or a tree adaptor component. It does not need any attributes declared for basic usage, but can provide markup templates for tree nodes of particular types. Default markup is used if the tree node type is not specified. Refer to Example 13.1, “Basic usage” for an example of basic <rich:treeNode> component usage.
Example 13.3. Basic usage
<rich:tree nodeType="#{node.type}" var="node" value="#{treeBean.rootNodes}"> <rich:treeNode type="country"> #{node.name} </rich:treeNode> <rich:treeNode type="state"> #{node.name} </rich:treeNode> <rich:treeNode type="city"> #{node.name} </rich:treeNode> </rich:tree>
13.1.10.2. Appearance
<rich:tree> component for details and examples on styling nodes and icons. Icon styling for individual <rich:treeNode> components uses the same attributes as the parent <rich:tree> component: iconLeaf, iconExpanded, and iconCollapsed. Icon-related attributes specified for child <rich:treeNode> components overwrite any global icon attributes of the parent <rich:tree> component.
rendered attribute to determine whether the node should actually be rendered in the tree or not. Using the rendered attribute in combination with the <rich:treeNode> type attribute can allow further style differentiation between node content.
13.1.10.3. Interactivity
<rich:tree> component. Refer to Section 13.1.3, “Expanding and collapsing tree nodes” and Section 13.1.6, “Event handling” for further details.
expanded attribute to determine whether the node is expanded or collapsed.
13.1.10.4. Reference data
component-type:org.richfaces.TreeNodecomponent-class:org.richfaces.component.UITreeNodecomponent-family:org.richfaces.TreeNoderenderer-type:org.richfaces.TreeNodeRendererhandler-class:org.richfaces.view.facelets.TreeNodeHandler
13.1.10.5. Style classes and skin parameters
Table 13.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
| No skin parameters. | |
| No skin parameters. | |
| additionalBackgroundColor
|
background
|
| additionalBackgroundColor
|
background
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
13.1.10.6. <rich:treeToggleListener>
<rich:treeToggleListener> tag to register a TreeToggleListener class on a parent <rich:treeNode> component. The class provided as a listener must implement the org.richfaces.event.TreeToggleListener interface. The processTreeToggle method accepts an org.richface.event.TreeToggleEvent event as a parameter.
13.2. Tree adaptors
13.2.1. <rich:treeModelAdaptor>
<rich:treeModelAdaptor> component takes an object which implements the Map or Iterable interfaces. It adds all the object entries to the parent node as child nodes.
13.2.1.1. Basic usage
<rich:treeModelAdaptor> component is added as a nested child component to a <rich:tree> component, or to another tree adaptor component.
<rich:treeModelAdaptor> component requires the nodes attribute for basic usage. The nodes attribute defines a collection of elements to iterate through for populating the nodes.
<rich:treeNode> component. Refer to Section 13.1.10, “<rich:treeNode>” for details on the <rich:treeNode> component.
13.2.1.2. Identifying nodes
Map interfaces or models with non-string keys require a row key converter in order to correctly identify nodes. Refer to Section 13.1.5, “Identifying nodes with the rowKeyConverter attribute” for details on the use of the rowKeyConverter attribute.
Iterable interfaces have simple integer row keys. A default converter is provided and does not need to be referenced explicitly.
13.2.1.3. Reference data
component-type:org.richfaces.treeModelAdaptorcomponent-class:org.richfaces.component.UITreeModelAdaptorcomponent-family:org.richfaces.TreeModelAdaptorhandler-class:org.richfaces.view.facelets.TreeModelAdaptorHandler
13.2.2. <rich:treeModelRecursiveAdaptor>
<rich:treeModelRecursiveAdaptor> component iterates through recursive collections in order to populate a tree with hierarchical nodes, such as for a file system with multiple levels of directories and files.
13.2.2.1. Basic usage
<rich:treeModelRecursiveAdaptor> component is an extension of the <rich:treeModelAdaptor> component. As such, the <rich:treeModelRecursiveAdaptor> component uses all of the same attributes. Refer to Section 13.2.1, “<rich:treeModelAdaptor>” for details on the <rich:treeModelAdaptor> component.
<rich:treeModelRecursiveAdaptor> component requires the roots attribute. The roots attribute defines the collection to use at the top of the recursion. For subsequent levels, the nodes attribute is used for the collection.
<rich:treeModelRecursiveAdaptor> component can be used in conjunction with the <rich:treeModelAdaptor> component to recursively iterate through a file system and create a tree of directories and files.
Example 13.4. Basic usage
<rich:tree var="item"> <rich:treeModelRecursiveAdaptor roots="#{fileSystemBean.sourceRoots}" nodes="#{item.directories}" > <rich:treeNode> #{item.shortPath} </rich:treeNode> <rich:treeModelAdaptor nodes="#{item.files}"> <rich:treeNode>#{item}</rich:treeNode> </rich:treeModelAdaptor> </rich:treeModelRecursiveAdaptor> </rich:tree>
<rich:treeModelRecursiveAdaptor> component references the FileSystemBean class as the source for the data.
@ManagedBean @RequestScoped public class FileSystemBean { private static final String SRC_PATH = "/WEB-INF"; private List<FileSystemNode> srcRoots; public synchronized List<FileSystemNode> getSourceRoots() { if (srcRoots == null) { srcRoots = new FileSystemNode(SRC_PATH).getDirectories(); } return srcRoots; } }
FileSystemBean class in turn uses the FileSystemNode class to recursively iterate through the collection.
public class FileSystemNode { ... public synchronized List<FileSystemNode> getDirectories() { if (directories == null) { directories = Lists.newArrayList(); Iterables.addAll(directories, transform(filter(getResourcePaths(), containsPattern("/$")), FACTORY)); } return directories; } public synchronized List<String> getFiles() { if (files == null) { files = new ArrayList<String>(); Iterables.addAll(files, transform(filter(getResourcePaths(), not(containsPattern("/$"))), TO_SHORT_PATH)); } return files; } private Iterable<String> getResourcePaths() { FacesContext facesContext = FacesContext.getCurrentInstance(); ExternalContext externalContext = facesContext.getExternalContext(); Set<String> resourcePaths = externalContext.getResourcePaths(this.path); if (resourcePaths == null) { resourcePaths = Collections.emptySet(); } return resourcePaths; } ... }
getDirectories() function is used recursively until the object has the collection of children. The model adaptor calls the getFiles() function at each level in order to add the file nodes.

13.2.2.2. Identifying nodes
Map interfaces or models with non-string keys require a row key converter in order to correctly identify nodes. Refer to Section 13.1.5, “Identifying nodes with the rowKeyConverter attribute” for details on the use of the rowKeyConverter attribute.
Iterable interfaces have simple integer row keys. A default converter is provided and does not need to be referenced explicitly.
13.2.2.3. Reference data
component-type:org.richfaces.TreeModelRecursiveAdaptorcomponent-class:org.richfaces.component.UITreeModelRecursiveAdaptorcomponent-family:org.richfaces.TreeModelRecursiveAdaptorhandler-class:org.richfaces.view.facelets.TreeModelRecursiveAdaptorHandler
Chapter 14. Menus and toolbars
14.1. <rich:dropDownMenu>
<rich:dropDownMenu> component is used for creating a drop-down, hierarchical menu. It can be used with the <rich:toolbar> component to create menus in an application's toolbar.
14.1.1. Basic usage
<rich:dropDownMenu> component only requires the label attribute for basic usage. Use the label attribute to define the text label that appears as the title of the menu. Clicking on the title drops the menu down.
label facet to define the menu title. If the label facet is used, the label attribute is not necessary.
14.1.2. Menu content
<rich:menuItem>, <rich:menuGroup>, and <rich:menuSeparator> components. These components are detailed in Section 14.3, “Menu sub-components”.
14.1.3. Appearance
jointPoint and direction attributes to determine the direction and location of the menu when it appears. The jointPoint and direction attributes both use the following settings:
topLeft,topRight,bottomLeft,bottomRight- When used with the
jointPointattribute, the menu is attached to the top-left, top-right, bottom-left, or bottom-right of the control as appropriate.When used with thedirectionattribute, the menu appears to the top-left, top-right, bottom-left, or bottom-right of the joint location as appropriate. auto- The direction or joint location is determined automatically.
autoLeft,autoRight,topAuto,bottomAuto- When used with the
jointPointattribute, the joint location is determined automatically, but defaults to either the left, right, top, or bottom of the control as appropriate.When used with thedirectionattribute, the menu direction is determined automatically, but defaults to either the left, right, top, or bottom of the joint location as appropriate.
14.1.4. Expanding and collapsing the menu
showEvent attribute to define the event instead.
show()- The
show()method shows the menu. hide()- The
hide()method hides the menu. activateItem(menuItemId)- The
activateItem(menuItemId)activates the menu item with themenuItemIdidentifier.
mode attribute to determine how the menu requests are submitted:
server, the default setting, submits the form normally and completely refreshes the page.ajaxperforms an Ajax form submission, and re-renders elements specified with therenderattribute.clientcauses theactionandactionListeneritems to be ignored, and the behavior is fully defined by the nested components or custom JavaScript instead of responses from submissions.
14.1.5. Reference data
component-type:org.richfaces.DropDownMenucomponent-class:org.richfaces.component.UIDropDownMenucomponent-family:org.richfaces.DropDownMenurenderer-type:org.richfaces.DropDownMenuRenderer
14.1.6. Style classes and skin parameters
Table 14.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| headerFamilyFont
|
font-family
|
| tabDisabledTextColor
|
color
|
| headerFamilyFont
|
font-family
|
| No skin parameters. | |
| No skin parameters. | |
| panelBorderColor
|
border-color
|
additionalBackgroundColor
|
background-color
| |
| additionalBackgroundColor
|
border-color
|
| No skin parameters. | |
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
| headerBackgroundColor
|
border-color
|
tabBackgroundColor
|
background-color
| |
| No skin parameters. | |
| tabDisabledTextColor
|
color
|
| generalTextColor
|
color
|
| No skin parameters. | |
| No skin parameters. | |
| panelBorderColor
|
border-top-color
|
| No skin parameters. | |
14.2. <rich:contextMenu>
<rich:contextMenu> component is used for creating a hierarchical context menu that are activated on events like onmouseover , onclick etc. The component can be applied to any element on the page.
14.2.1. Basic usage
<rich:menuItem>, <rich:menuGroup>, and <rich:menuSeparator> components. These components are detailed in Section 14.3, “Menu sub-components”.
14.2.2. Appearance
direction attribute to determine the direction of the menu when it appears. The direction attribute uses the following settings:
topLeft,topRight,bottomLeft,bottomRight- The menu appears to the top-left, top-right, bottom-left, or bottom-right of the activation point.
auto- The direction is determined automatically.
autoLeft,autoRight,topAuto,bottomAuto- The menu direction is determined automatically, but defaults to either the left, right, top, or bottom of the activation point as appropriate.
14.2.3. Expanding and collapsing the menu
contextmenu event is observed (ie. a right-click). To activate on a different event, use the showEvent attribute to define the event instead.
show()- The
show()method shows the menu. hide()- The
hide()method hides the menu. activateItem(menuItemId)- The
activateItem(menuItemId)activates the menu item with themenuItemIdidentifier.
mode attribute to determine how the menu requests are submitted:
server, the default setting, submits the form normally and completely refreshes the page.ajaxperforms an Ajax form submission, and re-renders elements specified with therenderattribute.clientcauses theactionandactionListeneritems to be ignored, and the behavior is fully defined by the nested components or custom JavaScript instead of responses from submissions.
14.2.4. Reference data
component-type:org.richfaces.ContextMenucomponent-class:org.richfaces.component.UIContextMenucomponent-family:org.richfaces.ContextMenurenderer-type:org.richfaces.ContextMenuRenderer
14.2.5. Style classes and skin parameters
Table 14.2. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| headerFamilyFont
|
font-family
|
| tabDisabledTextColor
|
color
|
| headerFamilyFont
|
font-family
|
| No skin parameters. | |
| No skin parameters. | |
| panelBorderColor
|
border-color
|
additionalBackgroundColor
|
background-color
| |
| additionalBackgroundColor
|
border-color
|
| No skin parameters. | |
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
| headerBackgroundColor
|
border-color
|
tabBackgroundColor
|
background-color
| |
| No skin parameters. | |
| tabDisabledTextColor
|
color
|
| generalTextColor
|
color
|
| No skin parameters. | |
| No skin parameters. | |
| panelBorderColor
|
border-top-color
|
| No skin parameters. | |
14.3. Menu sub-components
<rich:menuItem>, <rich:menuGroup>, and <rich:menuSeparator> components are used to construct menus for the <rich:dropDownMenu> component. Refer to Section 14.1, “<rich:dropDownMenu>” for more details on the <rich:dropDownMenu> component.
14.3.1. <rich:menuItem>
<rich:menuItem> component represents a single item in a menu control. The <rich:menuItem> component can be also be used as a seperate component without a parent menu component, such as on a toolbar.
14.3.1.1. Basic usage
<rich:menuItem> component requires the label attribute for basic usage. The label attribute is the text label for the menu item.
14.3.1.2. Appearance
icon attribute specifies the normal icon, while the iconDisabled attribute specifies the icon for a disabled item.
icon and iconDisabled to set the icons. If facets are defined, the icon and iconDisabled attributes are ignored. Using facets for icons allows more complex usage; example shows a checkbox being used in place of an icon.
Example 14.1. Icon facets
<rich:menuItem value="Show comments"> <f:facet name="icon"> <h:selectBooleanCheckbox value="#{bean.property}"/> </f:facet> </rich:menuItem>
14.3.1.3. Submission modes
submitMode attribute to determine how the menu item requests are submitted:
server, the default setting, submits the form normally and completely refreshes the page.ajaxperforms an Ajax form submission, and re-renders elements specified with therenderattribute.clientcauses theactionandactionListeneritems to be ignored, and the behavior is fully defined by the nested components instead of responses from submissions.
14.3.1.4. JavaScript API
<rich:menuItem> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
activate()- Activate the menu item as though it were selected.
14.3.1.5. Reference data
component-type:org.richfaces.MenuItemcomponent-class:org.richfaces.component.UIMenuItemcomponent-family:org.richfaces.DropDownMenurenderer-type:org.richfaces.MenuItemRenderer
14.3.2. <rich:menuGroup>
<rich:menuGroup> component represents an expandable sub-menu in a menu control. The <rich:menuGroup> component can contain a number of <rich:menuItem> components, or further nested <rich:menuGroup> components.
14.3.2.1. Basic usage
<rich:menuGroup> component requires the label attribute for basic usage. The label attribute is the text label for the menu item. Alternatively, use the label facet to define content for the label.
<rich:menuGroup> component must contain child <rich:menuItem> components or <rich:menuGroup> components.
14.3.2.2. Appearance
icon attribute specifies the normal icon, while the iconDisabled attribute specifies the icon for a disabled group.
<rich:menuGroup> component can be positioned using the jointPoint and direction attributes, the same as the parent menu control. For details on the jointPoint and direction attributes, refer to Section 14.1.3, “Appearance”.
14.3.2.3. JavaScript API
<rich:menuGroup> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
show()- Show the menu group.
hide()- Hide the menu group.
14.3.2.4. Reference data
component-type:org.richfaces.MenuGroupcomponent-class:org.richfaces.component.UIMenuGroupcomponent-family:org.richfaces.DropDownMenurenderer-type:org.richfaces.MenuGroupRenderer
14.3.3. <rich:menuSeparator>
<rich:menuSeparator> component represents a separating divider in a menu control.
14.3.3.1. Basic usage
<rich:menuSeparator> component does not require any attributes for basic usage. Add it as a child to a menu component to separator menu items and menu groups.
14.3.3.2. Reference data
component-type:org.richfaces.MenuSeparatorcomponent-class:org.richfaces.component.UIMenuSeparatorcomponent-family:org.richfaces.DropDownMenurenderer-type:org.richfaces.MenuSeparatorRenderer
14.4. <rich:panelMenu>
<rich:panelMenu> component is used in conjunction with <rich:panelMenuItem> and <rich:panelMenuGroup> to create an expanding, hierarchical menu. The <rich:panelMenu> component's appearance can be highly customized, and the hierarchy can stretch to any number of sub-levels.
Example 14.2. richpanelMenu
<rich:panelMenu mode="ajax" topGroupExpandedRightIcon="chevronUp" topGroupCollapsedRightIcon="chevronDown" groupExpandedLeftIcon="disc" groupCollapsedLeftIcon="disc"> <rich:panelMenuGroup label="Group 1"> <rich:panelMenuItem label="Item 1.1"/> <rich:panelMenuItem label="Item 1.2"/> <rich:panelMenuItem label="Item 1.3"/> </rich:panelMenuGroup> <rich:panelMenuGroup label="Group 2"> <rich:panelMenuItem label="Item 2.1"/> <rich:panelMenuItem label="Item 2.2"/> <rich:panelMenuItem label="Item 2.3"/> <rich:panelMenuGroup label="Group 2.4"> <rich:panelMenuItem label="Item 2.4.1"/> <rich:panelMenuItem label="Item 2.4.2"/> <rich:panelMenuItem label="Item 2.4.3"/> </rich:panelMenuGroup> <rich:panelMenuItem label="Item 2.5"/> </rich:panelMenuGroup> <rich:panelMenuItem label="Item 3"/> </rich:panelMenu>

14.4.1. Basic usage
<rich:panelMenu> component does not need any extra attributes declared for basic usage. However, it does require child <rich:panelMenuGroup> and <rich:panelMenuItem> components. Refer to Section 14.4.9, “<rich:panelMenuGroup>” and Section 14.4.10, “<rich:panelMenuItem>” for details on these child components.
14.4.2. Interactivity options
activeItem attribute is used to point to the name of the currently selected menu item.
expandEvent attribute to specify a different event to expand menus. Multiple levels of sub-menus can be expanded in one action. Set expandSingle="true" to only expand one sub-menu at a time.
collapseEvent attribute to specify a different event to collapse menus.
disabled="true" to disable the <rich:panelMenu> comonent. Child menu components can be disabled in the same way.
14.4.3. Appearance
topGroupExpandedLeftIcon,topGroupExpandedRightIcon- These attributes determine the icons for the top level menu when it is expanded.
topGroupCollapsedLeftIcon,topGroupCollapsedRightIcon- These attributes determine the icons for the top level menu when it is collapsed.
topGroupDisabledLeftIcon,topGroupDisabledRightIcon- These attributes determine the icons for the top level menu when it is disabled.
topItemLeftIcon,topItemRightIcon- These attributes determine the icons for a top level menu item.
topItemDisabledLeftIcon,topItemDisabledRightIcon- These attributes determine the icons for a top level menu item when it is disabled.
groupExpandedLeftIcon,groupExpandedRightIcon- These attributes determine the icons for sub-menus that are not the top-level menu when they are expanded.
groupCollapsedLeftIcon,groupCollapsedRightIcon- These attributes determine the icons for sub-menus that are not the top-level menu when they are collapsed.
groupDisabledLeftIcon,groupDisabledRightIcon- These attributes determine the icons for sub-menus that are not the top-level menu when they are disabled.
itemLeftIcon,itemRightIcon- These attributes determine the icons for items in the menus.
itemDisabledLeftIcon,itemDisabledRightIcon- These attributes determine the icons for items in the menus when they are disabled.
<Standard icons>”.
<rich:panelMenuGroup> and <rich:panelMenuItem> components overwrite the relevant icons declared with the parent <rich:panelMenu> component.
14.4.4. Submission modes
itemMode attribute defines the submission mode for normal menu items that link to content, and the groupMode attribute defines the submission mode for menu items that expand and collapse. The settings for these attributes apply to the entire menu unless a menu item defines its own individual itemMode or groupMode. The possible values for itemMode and groupMode are as follows:
server, the default setting, which submits the form normally and completely refreshes the page.ajax, which performs an Ajax form submission, and re-renders elements specified with therenderattribute.client, which causes theactionandactionListeneritems to be ignored, and the behavior is fully defined by the nested components instead of responses from submissions.
14.4.5. <rich:panelMenu> server-side events
<rich:panelMenu> component fires the ItemChangeEvent event on the server side when the menu is changed. The event only fires in the server and ajax submission modes. The event provides the itemChangeListener attribute to reference the event listener. Refer to Section 11.6.6, “<rich:itemChangeListener>” for details on the <rich:itemChangeListener> tag.
14.4.6. JavaScript API
<rich:panelMenu> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
expandAll()- Expand all the panel menu groups in the component.
collapseAll()- Collapse all the panel menu groups in the component.
selectItem(id)- Select the menu item with the
ididentifier.
14.4.7. Reference data
component-type:org.richfaces.PanelMenucomponent-class:org.richfaces.component.UIPanelMenucomponent-family:org.richfaces.PanelMenurenderer-type:org.richfaces.PanelMenuRendererhandler-class:org.richfaces.view.facelets.html.PanelMenuTagHandler
14.4.8. Style classes and skin parameters
Table 14.3. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| panelBorderColor
|
border-top-color
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| panelBorderColor
|
border-top-color
|
generalTextColor
|
color
| |
| No skin parameters. | |
| additionalBackgroundColor
|
background-color
|
| No skin parameters. | |
| tabDisabledTextColor
|
color
|
| No skin parameters. | |
| No skin parameters. | |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
| panelBorderColor
|
border-top-color
|
| No skin parameters. | |
| No skin parameters. | |
| generalTextColor
|
color
|
| additionalBackgroundColor
|
background
|
| tabDisabledTextColor
|
color
|
| No skin parameters. | |
| No skin parameters. | |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
| No skin parameters. | |
| panelBorderColor
|
border-color
|
generalTextColor
|
color
| |
| No skin parameters. | |
| headerTextColor
|
color
|
| No skin parameters. | |
| tabDisabledTextColor
|
color
|
| No skin parameters. | |
| No skin parameters. | |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
| panelBorderColor
|
border-color
|
| No skin parameters. | |
| No skin parameters. | |
| headerTextColor
|
color
|
headerBackgroundColor
|
background-color
| |
| tabDisabledTextColor
|
color
|
additionalBackgroundColor
|
background-color
| |
| No skin parameters. | |
| No skin parameters. | |
| generalSizeFont
|
font-size
|
generalFamilyFont
|
font-family
| |
| No skin parameters. | |
14.4.9. <rich:panelMenuGroup>
<rich:panelMenuGroup> component defines a group of <rich:panelMenuItem> components inside a <rich:panelMenu>.
14.4.9.1. Basic usage
<rich:panelMenuGroup> component needs the label attribute declared, which specifies the text to show for the menu entry. Alternatively, the label facet can be used to specify the menu text.
<rich:panelMenuGroup> component at least one <rich:panelMenuGroup> or <rich:panelMenuItem> components as child elements.
14.4.9.2. Appearance
<rich:panelMenu> component. Refer to Section 14.4.3, “Appearance” for details on icon attributes and facets. Alternatively, the menu group's icons can be re-defined at the <rich:panelMenuGroup> component level, and these settings will be used instead of the parent component's settings.
14.4.9.3. Submission modes
mode attribute is unspecified, the submission behavior for the group is inherited from the parent <rich:panelMenu>. Otherwise, the groupMode setting of the panel menu is used instead of the parent's behavior. Refer to Section 14.4.4, “Submission modes” for submission mode settings.
14.4.9.4. <rich:panelMenuGroup> server-side events
<rich:panelMenuGroup> component fires the ActionEvent event on the server side when the menu group receives a user action. The event only fires in the server and ajax submission modes. The event provides the action attribute to specify the user action method, and the actionListener attribute to reference the event listener.
14.4.9.5. JavaScript API
<rich:panelMenuGroup> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
expand()- Expand this panel menu group.
collapse()- Collapse this panel menu group.
select(id)- Select the menu item with the
ididentifier.
14.4.9.6. Reference data
component-type:org.richfaces.PanelMenuGroupcomponent-class:org.richfaces.component.UIPanelMenuGroupcomponent-family:org.richfaces.PanelMenuGroup
14.4.10. <rich:panelMenuItem>
<rich:panelMenuItem> component represents a single item inside a <rich:panelMenuGroup> component, which is in turn part of a <rich:panelMenu> component.
14.4.10.1. Basic usage
<rich:panelMenuItem> component needs the label attribute declared, which specifies the text to show for the menu entry. Alternatively, the label facet can be used to specify the menu text.
14.4.10.2. Appearance
<rich:panelMenu> or <rich:panelMenuGroup> component. Refer to Section 14.4.3, “Appearance” for details on icon attributes and facets. Alternatively, the menu item's icons can be re-defined at the <rich:panelMenuItem> component level, and these settings will be used instead of the parent component's settings.
14.4.10.3. Submission modes
mode is unspecified, the submission behavior for the item is inherited from the parent <rich:panelMenu>. Otherwise, the itemMode setting from the panel menu is used instead of the parent's behavior.
14.4.10.4. <rich:panelMenuItem> server-side events
<rich:panelMenuItem> component fires the ActionEvent event on the server side when the menu item receives a user action. The event only fires in the server and ajax submission modes. The event provides the action attribute to specify the user action performed, and the actionListener attribute to reference the event listener.
14.4.10.5. JavaScript API
<rich:panelMenuItem> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
select()- Select this menu item.
14.4.10.6. Reference data
component-type:org.richfaces.PanelMenuItemcomponent-class:org.richfaces.component.UIPanelMenuItemcomponent-family:org.richfaces.PanelMenuItem
14.5. <rich:toolbar>
<rich:toolbar> component is a horizontal toolbar. Any JavaServer Faces (JSF) component can be added to the toolbar.
14.5.1. Basic usage
<rich:toolbar> component does not require any attributes to be defined for basic usage. Add child components to the <rich:toolbar> component to have them appear on the toolbar when rendered.
Example 14.3. Basic usage
<rich:toolbar> <h:commandLink value="News" /> <h:commandLink value="Reviews" /> <h:commandLink value="Galleries" /> </rich:toolbar>
14.5.2. Appearance
width and height attributes.
itemSeparator attribute to specify one of the standard separator styles:
none, the default appearance, does not show any item separators.discshows a small circular disc to separate items:
gridshows a grid pattern to separate items:
lineshows a vertical line to separate items:
squareshows a small square to separate items:
itemSeparator attribute to specify a URL to an image. The image is then used as an item separator. The appearance of the item separator can be additionally customized by using the itemSeparator facet.
14.5.3. Grouping items
<rich:toolbarGroup> child component. Refer to Section 14.5.6, “<rich:toolbarGroup>” for full details on the <rich:toolbarGroup> component.
14.5.4. Reference data
component-type:org.richfaces.Toolbarcomponent-class:org.richfaces.component.UIToolbarcomponent-family:org.richfaces.Toolbarrenderer-type:org.richfaces.ToolbarRenderer
14.5.5. Style classes and skin parameters
Table 14.4. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| panelBorderColor
|
border-color
|
headerTextColor
|
color
| |
headerBackgroundColor
|
background-color
| |
headerFamilyFont
|
font-family
| |
headerSizeFont
|
font-size
| |
headerWeightFont
|
font-weight
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
14.5.6. <rich:toolbarGroup>
<rich:toolbarGroup> component is a child component of the <rich:toolbar> component. The <rich:toolbarGroup> component is used to group a number of items together on a toolbar.
14.5.6.1. Basic usage
<rich:toolbar> parent component, the <rich:toolbarGroup> component does not require any extra attributes for basic functionality. Add child components to the <rich:toolbarGroup> component to have them appear grouped on the parent toolbar when rendered.
14.5.6.2. Appearance
<rich:toolbar> component, items within a <rich:toolbarGroup> can be separated by specifying the itemSeparator attribute. Refer to Section 14.5.2, “Appearance” for details on using the itemSeparator attribute.
location="right".
Example 14.4. <rich:toolbarGroup>
<rich:toolBar height="26" itemSeparator="grid"> <rich:toolBarGroup> <h:graphicImage value="/images/icons/create_doc.gif"/> <h:graphicImage value="/images/icons/create_folder.gif"/> <h:graphicImage value="/images/icons/copy.gif"/> </rich:toolBarGroup> <rich:toolBarGroup> <h:graphicImage value="/images/icons/save.gif"/> <h:graphicImage value="/images/icons/save_as.gif"/> <h:graphicImage value="/images/icons/save_all.gif"/> </rich:toolBarGroup> <rich:toolBarGroup location="right"> <h:graphicImage value="/images/icons/find.gif"/> <h:graphicImage value="/images/icons/filter.gif"/> </rich:toolBarGroup> </rich:toolBar>

14.5.6.3. Reference data
component-type:org.richfaces.ToolbarGroupcomponent-class:org.richfaces.component.UIToolbarGroupcomponent-family:org.richfaces.Toolbarrenderer-type:org.richfaces.ToolbarGroupRenderer
Chapter 15. Output and messages
15.1. <rich:chart>
<rich:chart> component allows the user to plot data and to create line, bar or pie charts. It uses up to five children tags: <rich:chartSeries>, <rich:chartLegend>, <rich:chartXAxis>, <rich:chartYAxis> and <rich:chartPoint>. Each child tag customizes a particular aspect of the chart. At least one <rich:chartSeries> tag is required and the others are optional.
<rich:chart> component allows one to handle events using either a client-side JavaScript or using server-side listeners.
15.1.1. Basic Usage
<rich:chart> tag and its optional children tags generate and customize the chart. The chart type is selected by a <rich:chartSeries> attribute. The only requirements for using the <rich:chart> are selection of the chart type and passing of at least one series of data. This is explained in more detail below.
15.1.2. Data Input
<rich:chart> component accepts data by two means: by facelet iteration, and by creating a DataModel object.
15.1.2.1. Facelet Iteration
<a4j:repeat> and a collection of objects inside the <rich:chartSeries> tag and specify what you want to be plotted on the x and y axis using the <rich:chartPoint> tag. The <a4j:repeat> approach can also be used at the <rich:chartSeries> level.
Example 15.1. rich:chart facelet iteration example
<rich:chart id="barChart" title="Countries by vehicles per capita"> <rich:chartSeries type="bar"> <a4j:repeat value="#{bean.records}" var="record"> <rich:chartPoint x="#{record.country}" y="#{record.count}"/> </a4j:repeat> </rich:chartSeries> <rich:chartYAxis label="Motor vehicles per 1000 people"/> </rich:chart>
15.1.2.2. Create a DataModel Object
<rich:chartSeries> data attribute. To do this, create an instance of one of the child classes of ChartDataModel - NumberChartDataModel, StringChartDataModel or DateChartDataModel (not yet fully supported). Select the class according to the data type used on the x-axis. Add values to the model using the put() method and pass it to the <rich:chartSeries> tag using the data attribute.
Example 15.2. rich:chart DataModel object example
<rich:chart id="barChart" title="Countries by vehicles per capita"> <rich:chartSeries type="bar" data="#{bean.cars}"/> <rich:chartYAxis label="Motor vehicles per 1000 people"/> </rich:chart>
cars = new StringChartDataModel(ChartDataModel.ChartType.bar); cars.put("San Marino", 1263); cars.put("United States", 797); ...
<rich:chartSeries> data attribute, any nested <rich:chartPoint> tags are ignored. If the data attribute is not used, then nested <rich:chartPoint> tags are expected.
15.1.3. Chart Customization
<rich:chartXAxis> or <rich:chartYAxis> tag. The <rich:chartLegend> allows you to set up the position of the legend and the order of the labels within it.
div with the CSS class .richfaces-chart.
15.1.4. Advanced Customization
<rich:chart> can also be customized directly through JavaScript to allow the use of plugins or objects that are not directly supported by the component.
<h:outputScript> var hooks = { processOptions: [function(plot,options) { options.xaxes[0].tickFormatter = function (value, axis) { return value.toLocaleString('en-US', {minimumFractionDigits: 2}); }; }] }; </h:outputScript> <rich:chart hooks="hooks" />
<rich:chart> <f:facet name="hooks"> { processOptions: [function(plot,options) { options.xaxes[0].tickFormatter = function (value, axis) { return value.toLocaleString('en-US', {minimumFractionDigits: 2}); }; }] } </f:facet> </rich:chart>
<rich:chart> is configured to display the label on x-axis according to US locale (e.g. 45,324.23).
Note
15.1.5. Interactivity Options
<rich:chart> component can create interactive charts.
- It allows the user to zoom line charts when the
<rich:chart>attribute zoom is set true. To reset zoom you can use the JavaScript API. - You can also add functions to handle events fired by components. Event handlers are set up using proper
<rich:chart>attributes. They handle events fired by any series. If you want to handle an event only fired by a particular series, set up handlers using the<rich:chartSeries>attributes.
15.1.6. <rich:chart> Server-side Events
- The
PlotClickEventis fired when the user clicks a point in the chart. To set a listener use theClickListenerattribute.
15.1.7. <rich:chart> Client-side Events
- The
plothoverevent points to the client-side function to execute when the mouse cursor is over the chart point. - The
plotclickevent points to the client-side function to execute when the user clicks the chart point. - The
mouseoutevent points to the cient-side function to execute when the mouse cursor leaves the chart grid.
plothover and plotclick handlers are given an event-object that contains the deatils of which point fired the event.
function log(e){ console.log("Series index: "+ e.data.seriesIndex +" DataIndex: "+ e.data.dataIndex+' ['+e.data.x+','+e.data.y+']'); }
15.1.8. JavaScript API
resetZoom()displays the chart without scaling.getPlotObject()returns a JavaScript object containing chart data and options.
Example 15.3. jQuery Widget Example
<rich:chart id="priceChart">
$(document.getElementById("priceChart")).chart("resetZoom")
15.1.9. Reference Data
component-type: org.richfaces.Chartcomponent-class: org.richfaces.component.UIChartcomponent-family: org.richfaces.Chartrenderer-type: org.richfaces.ChartRendererhandler-class: org.richfaces.ChartTagHandler
15.2. <rich:message>
<rich:message> component renders a single FacesMessage message instance added for the component. The appearance of the message can be customized, and tool-tips can be used for further information about the message.
<rich:message> component is rendered in the same way as the standard <h:message> component, but allows separate styling of the message summary and detail. It allows unified icons to be set using background images in predefined classes.
15.2.1. Basic usage
<rich:message> component needs the for attribute to point to the id identifier of the related component. The message is displayed after the FacesMessage message instance is created and added for the client identifier of the related component.
<rich:message> component is automatically rendered after an Ajax request. This occurs without the use of an <a4j:outputPanel> component or a specific reference through the render attribute of the Ajax request source.
Example 15.4. rich:message example
<h:outputText value="Zip:" /> <h:inputText label="Zip" id="zip" required="true" value="#{userBean.zip}"> <f:validateLength minimum="4" maximum="9" /> </h:inputText> <rich:message for="zip" ajaxRendered="true"/>
<rich:message> component references the input box, and reports any messages relating to the input validation.
15.2.2. Appearance
showSummary attribute specifies whether to display only a summary of the full message. The full message can be displayed in a tool-tip when hovering the mouse over the summary.
<rich:message> component. To use a custom icon, set the background-image property to the icon graphic, as shown in Example 15.5, “Message icons”. Refer to Section 15.2.4, “Style classes and skin parameters” for a complete list of style classes for the <rich:message> component.
Example 15.5. Message icons
.rf-msg-err{
background-image: url('#{facesContext.externalContext.requestContextPath}/images/icons/error.gif');
}
15.2.3. Reference data
component-type:org.richfaces.Messagecomponent-class:org.richfaces.component.html.HtmlMessagecomponent-family:javax.faces.Messagerenderer-type:org.richfaces.MessageRenderer
15.2.4. Style classes and skin parameters
Table 15.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
| errorColor
|
color
|
| errorColor
|
color
|
| generalTextColor
|
color
|
| warningTextColor
|
color
|
| generalTextColor
|
color
|
| No skin parameters. | |
15.3. <rich:messages>
<rich:messages> components works similarly to the <rich:message> component, but can display all the validation messages added for the current view instead of just a single message. Refer to Section 15.2, “<rich:message>” for details on the <rich:message> component.
15.3.1. Basic usage
<rich:messages> component doesn't require any extra attributes for basic usage. It displays all messages relating to requests from components.
for attribute to reference the component's identifier.
globalOnly="true".
<rich:messages> component is automatically rendered after an Ajax request. This occurs without the use of an <a4j:outputPanel> component or a specific reference through the render attribute of the Ajax request source.
15.3.2. Appearance
<rich:messages> component displays error messages for each validating component in the same container.
<rich:messages> component can be further styled through CSS, the same as for the <rich:message> component. Refer to Section 15.2.2, “Appearance” for an example of message styling, and refer to Section 15.3.4, “Style classes and skin parameters” for a complete list of style classes for the <rich:message> component.
- Display messages in a list with no icons
- To display the messages in a list format without the default icons, override the message styles as follows:
.rf-msg-err, .rf-msgs-err, .rf-msg-ftl, .rf-msgs-ftl, .rf-msg-inf, .rf-msgs-inf, .rf-msg-wrn, .rf-msgs-wrn, .rf-msg-ok, .rf-msgs-ok { display: list-item; margin-left: 20px; padding-left: 0px; } .rf-msg-err, .rf-msgs-err{ background-image:none; } - Display in-line messages
- To display the messages in line with text, override the message styles as follows:
.rf-msg-err, .rf-msgs-err, .rf-msg-ftl, .rf-msgs-ftl, .rf-msg-inf, .rf-msgs-inf, .rf-msg-wrn, .rf-msgs-wrn, .rf-msg-ok, .rf-msgs-ok { display:inline; }
15.3.3. Reference data
component-type:org.richfaces.Messagescomponent-class:org.richfaces.component.html.HtmlMessagescomponent-family:javax.faces.Messagesrenderer-type:org.richfaces.MessagesRenderer
15.3.4. Style classes and skin parameters
Table 15.2. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalFamilyFont
|
font-family
|
generalSizeFont
|
font-size
| |
| errorColor
|
color
|
| errorColor
|
color
|
| generalTextColor
|
color
|
| warningTextColor
|
color
|
| generalTextColor
|
color
|
| No skin parameters. | |
15.4. <rich:notify>
<rich:notify> component serves for advanced user interaction, using notification boxes to give the user instant feedback on what's happening within the application. Each time this component is rendered, a floating notification box is displayed in the selected corner of the browser screen.
15.4.1. Basic usage
<rich:notify> has two message customization attributes: summary is short text summarizing the message, while detail configures the detailed body of the message. Both attributes have their counterparts in form of facets with the same names as the corresponding attributes.
15.4.2. Customizing notifications
<rich:notifyStack> component.
sticky: notifications does not disappear automatically, they needs to be closed explicitly with close button (this attribute can't be used together withnonblockingandstayTime)stayTime: configures how long notification stays on the screen before it disappears (in miliseconds)styleClass: defines the class customizing the notificationnonblocking: defines notifications which becomes partially transparent and user can click through. Non-blocking notifications don't have close button.nonblockingOpacity: defines opacity of nonblocking notifications when mouse hovers over notification (decimal number between 0 and 1)showShadow: defines whether shadow will be displayed under the notification
Note
15.4.3. Reference data
component-type:org.richfaces.Notifycomponent-class:org.richfaces.component.UINotifycomponent-family:org.richfaces.Notifyrenderer-type:org.richfaces.NotifyRenderer
15.4.4. Style classes and skin parameters
<rich:notify>, <rich:notifyMessage> and <rich:notifyMessages>
Table 15.3. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| headerBackgroundColor
|
background-color
|
headerTextColor
|
color
| |
| panelBorderColor
|
border-color
|
generalBackgroundColor
|
background-color
| |
panelTextColor
|
color
| |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
15.5. <rich:notifyMessage>
15.5.1. Basic usage
<rich:notifyMessage> component is built on top of <rich:notify>, the difference is in usage. The <rich:notifyMessage> component displays FacesMessages associated with a given component, similar to <rich:message>: one notification is displayed for first FacesMessage in the stack that is risen either programatically or during conversion/validation of the component. The severity of the message determines the color and icon of the resulting notification.
<rich:notify>.
15.5.2. Reference data
component-type:org.richfaces.NotifyMessagecomponent-class:org.richfaces.component.html.HtmlNotifyMessagecomponent-family:javax.faces.Messagerenderer-type:org.richfaces.NotifyMessageRenderer
15.5.3. Style classes and skin parameters
<rich:notifyMessage> shares common classes with <rich:notify>, since there is exactly one notification rendered for each JSF message.
<rich:notifyMessage> specific classes are redefining the look for various message severity levels.
Table 15.4. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| generalTextColor
|
color
|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
15.6. <rich:notifyMessages>
<rich:notifyMessages> component is the same as the <rich:notifyMessage> component, but each of the available messages generates one notification.
<rich:notifyMessages> shares the same set of attributes with <rich:notifyMessage>
15.6.1. Reference data
component-type:org.richfaces.NotifyMessagescomponent-class:org.richfaces.component.html.HtmlNotifyMessagescomponent-family:javax.faces.Messagesrenderer-type:org.richfaces.NotifyMessagesRenderer
15.6.2. Style classes and skin parameters
<rich:notifyMessages> shares style classes with <rich:notifyMessage>.
15.7. <rich:notifyStack>
<rich:notify>, <rich:notifyMessage> and <rich:notifyMessages> are displayed in top-right corner of the screen by default.
<rich:notifyStack> which defines where messages will appear and handles their stacking.
15.7.1. Basic usage
- wrapping: nesting
<rich:notify>,<rich:notifyMessage>or<rich:notifyMessages>binds notifications with the stack in which they are wrapped - binding by id: notification can be bound directly to a stack using it's
componentIdin thestackattribute - using default stack: a default stack is used when no other binding is defined for a given notification
<rich:notifyStack position="bottomRight"> <rich:notifyMessages /> </rich:notifyStack>
<rich:notifyStack id="leftStack" position="topLeft" /> <rich:notify stack="leftStack" />
15.7.2. Positioning notifications
<rich:notifyStack> uses the position attribute to place the stack and it's notifications into one of four corners: topRight (default), bottomRight, bottomLeft, topLeft.
15.7.3. Stacking notifications
method: defines where new notifications are placed and how they are removed. Options:first(default),last.direction: defines in which direction will be messages stacked. Options:vertical(default),horizontal
<rich:notifyStack method="first" />
last provides a method to place messages on the end of the stack, and when removing a notification, it is removed from the start, causing all other notifications to shift.
15.7.4. Reference data
component-type:org.richfaces.NotifyStackcomponent-class:org.richfaces.component.UINotifyStackcomponent-family:org.richfaces.NotifyStackrenderer-type:org.richfaces.NotifyStackRenderer
15.7.5. Style classes and skin parameters
Table 15.5. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
15.8. <rich:progressBar>
<rich:progressBar> component displays a progress bar to indicate the status of a process to the user. It can update either through Ajax or on the client side, and the look and feel can be fully customized.
15.8.1. Basic usage
<rich:progressBar> component requires the value attribute, which points to the property that holds the current progress value. When the value is greater than or equal to the minimum value (0 by default), the progress bar becomes active, and starts sending Ajax requests if in ajax mode.
15.8.2. Customizing the appearance
0 and the maximum value of the progress bar is 100. These values can be customized using the minValue and maxValue attributes respectively.
- Using the
labelattribute - The content of the
labelattribute is displayed over the progress bar.Example 15.7. Using the
labelattribute<rich:progressBar value="#{bean.incValue}" id="progrs" label="#{bean.incValue} % complete"/>
- Using nested child components
- Child components, such as the JSF
<h:outputText>component, can be nested in the<rich:progressBar>component to display over the progress bar.Example 15.8. Using nested child components
<rich:progressBar value="#{bean.incValue}"> <h:outputText value="#{bean.incValue} % complete"/> </rich:progressBar>
initial and finish facets to customize the progress bar's appearance before progress has started and after progress has finished. When the current progress bar value is less than the minimum value, the initial facet is displayed. When the current progress bar is greater than the maximum value, the finish facet is displayed.
Example 15.9. Initial and finished states
<rich:progressBar value="#{bean.incValue1}"> <f:facet name="initial"> <h:outputText value="Process has not started"/> </f:facet> <f:facet name="finish"> <h:outputText value="Process has completed"/> </f:facet> </rich:progressBar>
15.8.3. Update mode
mode attribute, which can have one of the following values:
ajax- The progress bar updates in the same way as the
<a4j:poll>component. The<rich:progressBar>component repeatedly polls the server for the current progress value. client- The progress bar must be explicitly updated on the client side through the JavaScript API.
15.8.4. Using set intervals
<rich:progressBar> component can be set to constantly poll for updates at a constant interval. Use the interval component to set the interval in milliseconds. The progress bar is updated whenever the polled value changes. Polling is only active when the enabled attribute is set to true.
Example 15.10. Using set intervals
<rich:progressBar value="#{bean.incValue1}" id="progress" interval="900" enabled="#{bean.enabled1}"/>
15.8.5. JavaScript API
<rich:progressBar> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()- Return the current value displayed on the progress bar.
setValue()- Set the current value to display on the progress bar.
getMinValue()- Return the minimum value for the progress bar.
getMaxValue()- Return the maximum value for the progress bar.
disable()- Disables the progress bar.
enable()- Enables the progress bar.
isEnabled()- Returns a boolean value indicating whether the progress bar is enabled.
15.8.6. Reference data
component-type:org.richfaces.ProgressBarcomponent-class:org.richfaces.component.UIProgressBarcomponent-family:org.richfaces.ProgressBarrenderer-type:org.richfaces.ProgressBarRenderer
15.8.7. Style classes and skin parameters
Table 15.6. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| panelBorderColor
|
border-color
|
selectControlColor
|
background-color
| |
| generalTextColor
|
color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
15.9. <rich:tooltip>
<rich:tooltip> component provides an informational tool-tip. The tool-tip can be attached to any control and is displayed when hovering the mouse cursor over the control.
15.9.1. Basic usage
value attribute. The <rich:tooltip> component is then automatically attached to the parent element, and is usually shown when the mouse cursor hovers.
<rich:tooltip> tags, and the value attribute is not used. This allows HTML tags to be used to define the content, and provides for rich content such as images, links, buttons, and other RichFaces components.
Example 15.11. Defining tool-tip content
- Basic content
<rich:panel> <rich:tooltip value="This is a tool-tip."/> </rich:panel>
- Rich content
<rich:panel> <rich:tooltip> This is a <b>tool-tip</b>. </rich:tooltip> </rich:panel>
15.9.2. Attaching the tool-tip to another component
target attribute is used to attach the tool-tip to another component, pointing to the target component's id identifier. This allows the <rich:tooltip> component to be specified outside the target element. This approach is demonstrated in Example 15.12, “Attaching the tool-tip”.
Example 15.12. Attaching the tool-tip
<rich:panel id="panelId"> ... </rich:panel> <rich:tooltip value="This is a tool-tip." target="panelId"/>
<rich:tooltip> component can alternatively be left unattached, and is instead invoked through an event handler on the target component. To leave the <rich:tooltip> component unattached, set attached="false", and define the event handler to trigger the tool-tip on the target component. This approach is demonstrated in Example 15.13, “Unattached tool-tips”. When leaving the <rich:tooltip> component unattached, ensure it has an id identifier defined. If it is defined outside the target element, it must be nested in an <h:form> component.
Example 15.13. Unattached tool-tips
<rich:panel id="panelId" onclick="#{rich:component('tooltipId')}.show(event);" /> <h:form> <rich:tooltip id="toolTipId" attached="false" value="This is a tool-tip."/> </h:form>
15.9.3. Appearance
<rich:tooltip> component is positioned intelligently based on the position of the mouse cursor. Use the jointPoint attribute to specify a corner of the target component at which to display the tool-tip instead, and use the direction attribute to specify the direction the tool-tip will appear relative to that corner. Possible values for both attributes are: auto, autoLeft, autoRight, bottomAuto, bottomLeft, bottomRight, topAuto, topLeft, topRight. Use the horizontalOffset and verticalOffset attributes to specify the horizontal offset and vertical offset at which to display the tool-tip.
showEvent attribute to specify when the tool-tip is shown. By default it appears when the attached component is hovered-over with the mouse. Use the hideEvent attribute to specify when the tool-tip is hidden. The default value is none, so the tool-tip remains shown. However, it can be linked to an event on the target component, such as the mouseout event.
followMouse="true" to cause the tool-tip to follow the user's mouse movements.
15.9.4. Update mode
mode attribute, which can have one of the following values:
ajax- The tool-tip content is requested from the server with every activation.
client- The tool-tip content is rendered once on the server. An external submit causes the content to re-render.
mode="ajax", define the loading facet. The tool-tip displays the content of the loading facet while loading the actual content from the server.
Example 15.14. Advanced tool-tip usage
<h:commandLink value="Simple Link" id="link"> <rich:tooltip followMouse="true" direction="topRight" mode="ajax" value="#{bean.toolTipContent}" horizontalOffset="5" verticalOffset="5" layout="block"> <f:facet name="loading"> <f:verbatim>Loading...</f:verbatim> </f:facet> </rich:tooltip> </h:commandLink>
15.9.5. <rich:tooltip> client-side events
<rich:tooltip> component supports the following client-side events:
click- This event is activated when the tool-tip is clicked with the mouse.
dblclick- This event is activated when the tool-tip is double-clicked with the mouse.
mouseout- This event is activated when the mouse cursor leaves the tool-tip.
mousemove- This event is activated when the mouse cursor moves over the tool-tip.
mouseover- This event is activated when the mouse cursor hovers over the tool-tip.
show- This event is activated when the tool-tip is shown.
complete- This event is activated when the tool-tip is completed.
hide- This event is activated when the tool-tip is hidden.
15.9.6. JavaScript API
<rich:tooltip> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
show(event)- Show the tool-tip.
hide()- Hide the tool-tip.
15.9.7. Reference data
component-type:org.richfaces.Tooltipcomponent-class:org.richfaces.component.UITooltipcomponent-family:org.richfaces.Tooltiprenderer-type:org.richfaces.TooltipRenderer
15.9.8. Style classes and skin parameters
Table 15.7. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| tipBorderColor
|
border-color
|
generalFamilyFont
|
font-family
| |
generalSizeFont
|
font-size
| |
Chapter 16. Drag and drop
16.1. <rich:dragSource>
<rich:dragSource> component can be added to a component to indicate it is capable of being dragged by the user. The dragged item can then be dropped into a compatible drop area, designated using the <rich:dropTarget> component.
16.1.1. Basic usage
<rich:dragSource> component as a child element.
type attribute must be specified, and can be any identifying string. Dragged items can only be dropped in drop zones where the type attribute of the <rich:dragSource> component is listed in the acceptedTypes attribute of the <rich:dropTarget> component.
16.1.2. Dragging an object
dragIndicator parameter to customize the appearance of a dragged object while it is being dragged. The dragIndicator parameter must point to the id identifier of a <rich:dragIndicator> component. If the dragIndicator attribute is not defined, the drag indicator appears as a clone of the <rich:dragSource> component's parent control.
dragValue attribute. The dragValue attribute specifies a server-side object, which is then bound to the parent component when it is dragged. This facilitates handling event data during a drop event.
16.1.3. Reference data
component-type:org.richfaces.DragSourcecomponent-class:org.richfaces.component.UIDragSourcecomponent-family:org.richfaces.DragSourcerenderer-type:org.richfaces.DragSourceRenderer
16.2. <rich:dropTarget>
<rich:dropTarget> component can be added to a component so that the component can accept dragged items. The dragged items must be defined with a compatible drop type for the <rich:dragSource> component.
16.2.1. Basic usage
<rich:dropTarget> component as a child element to the component.
acceptedTypes attribute must be specified. The acceptedTypes attribute is a comma-separated list of strings that match the types of dragged items. Dragged items can only be dropped in drop zones where the type attribute of the <rich:dragSource> component is listed in the acceptedTypes attribute of the <rich:dropTarget> component.
acceptedTypes attribute can optionally be set to either @none or @all. If set to @none, the component will not accept any type of dropped object. If set to @all, the component accepts all dropped objects. If the acceptedTypes attribute is not specified, the default value is null, which is the same as a @none setting.
16.2.2. Handling dropped data
dropValue attribute.
<rich:dropTarget> component raises the DropEvent server-side event when an object is dropped. The event uses the following parameters:
- The
dragSourceidentifies the component being dragged (the parent of the<rich:dragSource>component). - The
dragValueparameter is the content of the<rich:dragSource>component'sdragValueattribute. - The
dropValueparameter is the content of the<rich:dropTarget>component'sdropValueattribute.
16.2.3. Reference data
component-type:org.richfaces.DropTargetcomponent-class:org.richfaces.component.UIDropTargetcomponent-family:org.richfaces.DropTargetrenderer-type:org.richfaces.DropTargetRendererhandler-class:org.richfaces.view.facelets.DropHandler
16.3. <rich:dragIndicator>
<rich:dragIndicator> component defines a graphical element to display under the mouse cursor during a drag-and-drop operation.
16.3.1. Basic usage
16.3.2. Styling the indicator
acceptClass- The
acceptClassattribute specifies the style when the dragged element is over an acceptable drop target. It indicates that thetypeattribute of the element's<rich:dragSource>component matchesacceptedTypesattribute of the drop target's<rich:dropTarget>component. rejectClass- The
rejectClassattribute specifies the style when the dragged element is over a drop target that is not acceptable. It indicates that thetypeattribute of the element's<rich:dragSource>component is not found in theacceptedTypesattribute of the drop target's<rich:dropTarget>component. draggingClass- The
draggingClassattribute specifies the style when the dragged element is being dragged. It indicates that the dragged element is not over a drop target.
16.3.3. Reference data
component-type:org.richfaces.DragIndicatorcomponent-class:org.richfaces.component.UIDragIndicatorcomponent-family:org.richfaces.DragIndicatorrenderer-type:org.richfaces.DragIndicatorRenderer
16.3.4. Style classes
Style classes (selectors)
- .rf-ind
- This class defines styles for the drag indicator.
- .rf-ind-drag.accept
- This class defines styles for the indicator when it is over an acceptable drop target.
- .rf-ind-drag.reject
- This class defines styles for the indicator when it is over an unacceptable drop target.
- .rf-ind-drag.default
- This class defines styles for the indicator when it is being dragged, and is not over any drop targets.
Chapter 17. Layout and appearance
17.1. <rich:jQuery>
<rich:jQuery> component applies styles and custom behavior to both JSF (JavaServer Faces) objects and regular DOM (Document Object Model) objects. It uses the jQuery JavaScript framework to add functionality to web applications.
17.1.1. Basic usage
<rich:jQuery> component is specified using the query attribute.
17.1.2. Defining a selector
selector attribute. The selector attribute references objects using the following method:
- The
selectorattribute can refer to the elements by using syntax of the jQuery Selectors (a superset of CSS selectors defined by W3C consortium) and additionally it expands JSF component IDs to client-side IDs (see the VDL documentation for theselectorattribute). - If the
selectorattribute does not match theididentifier attribute of any JSF components or clients on the page, it instead uses syntax defined by the World Wide Web Consortium (W3C) for the CSS rule selector. Refer to the syntax specification at http://api.jquery.com/category/selectors/ for full details.
selector attribute can be either an id identifier attribute or CSS selector syntax, conflicting values could arise. Example 17.1, “Avoiding syntax confusion” demonstrates how to use double backslashes to escape colon characters in id identifier values.
Example 17.1. Avoiding syntax confusion
<h:form id="form"> <h:panelGrid id="menu"> <h:graphicImage value="pic1.jpg" /> <h:graphicImage value="pic2.jpg" /> </h:panelGrid> </h:form>
id identifier for the <h:panelGrid> element is form:menu, which can conflict with CSS selector syntax. Double backslashes can be used to escape the colon character such that the identifier is read correctly instead of being interpreted as CSS selector syntax.
<rich:jQuery selector="#form\\:menu img" query="..." />
17.1.3. Event handlers
selector attribute raises an event. The query is bound to the event defined using the event attribute.
attachType attribute to specify how the event-handling queries are attached to the events:
bind- This is the default for attaching queries to events. The event handler is bound to all elements currently defined by the
selectorattribute. live- The event handler is bound to all current and future elements defined by the
selectorattribute. one- The event handler is bound to all elements currently defined by the
selectorattribute. After the first invocation of the event, the event handler is unbound such that it no longer fires when the event is raised.
17.1.4. Timed queries
timing attribute to specify the point at which the timed query is triggered:
domready- This is the default behavior. The query is triggered when the document is loaded and the DOM is ready. The query is called as a
jQuery()function. immediate- The query is triggered immediately. The query is called as an in-line script.
Example 17.2. <rich:jQuery> example
<rich:dataTable id="customList" ... > ... </rich:dataTable> <rich:jQuery selector="#customList tr:odd" timing="domready" query="addClass(odd)" />
<tr> elements that are children of the element with an id="customlist" attribute. The query addClass(odd) is then performed on the selection during page loading (load) such that the odd CSS class is added to the selected elements.

17.1.5. Named queries
name attribute to name the query. The query can then be accessed as though it were a JavaScript function using the specified name attribute as the function name.
this) to the calling object as a parameter. This is treated the same as an item defined through the selector attribute.
options namespace is then used in the <rich:jQuery> query to access the passed function parameters. Example 17.3, “Calling a <rich:jQuery> component as a function” demonstrates the use of the name attribute and how to pass function parameters through the JavaScript calls.
Example 17.3. Calling a <rich:jQuery> component as a function
<h:graphicImage width="50" value="/images/price.png" onmouseover="enlargePic(this, {pwidth:'60px'})" onmouseout="releasePic(this)" /> <h:graphicImage width="50" value="/images/discount.png" onmouseover="enlargePic(this, {pwidth:'100px'})" onmouseout="releasePic(this)" /> ... <rich:jQuery name="enlargePic" query="animate({width:options.pwidth})" /> <rich:jQuery name="releasePic" query="animate({width:'50px'})"/>
enlargePic and releasePic components are called like ordinary JavaScript functions from the image elements.
17.1.6. Dynamic rendering
<rich:jQuery> component applies style and behavioral changes to DOM objects dynamically. As such, changes applied during an Ajax response are overwritten, and will need to be re-applied once the Ajax response is complete.
timing attribute set to domready may not update during an Ajax response, as the DOM document is not completely reloaded. To ensure the query is re-applied after an Ajax response, include the name attribute in the <rich:jQuery> component and invoke it using JavaScript from the complete event attribute of the component that triggered the Ajax interaction.
17.1.7. Reference data
component-type:org.richfaces.JQuerycomponent-class:org.richfaces.component.UIJQuerycomponent-family:org.richfaces.JQueryrenderer-type:org.richfaces.JQueryRenderer
Chapter 18. Functions
data attribute of components. Refer to Section 4.4.4.1, “data” for details on the data attribute.
18.1. rich:clientId
rich:clientId('id') function returns the client identifier related to the passed component identifier ('id'). If the specified component identifier is not found, null is returned instead.
18.2. rich:component
rich:component('id') function is equivalent to the RichFaces.$('clientId') code. It returns the client object instance based on the passed server-side component identifier ('id'). If the specified component identifier is not found, null is returned instead. The function can be used to get an object from a component to call a JavaScript API function without using the <rich:componentControl> component.
18.3. rich:element
rich:element('id') function is a shortcut for the equivalent document.getElementById(#{rich:clientId('id')}) code. It returns the element from the client, based on the passed server-side component identifier. If the specified component identifier is not found, null is returned instead.
18.4. rich:jQuery
rich:jQuery('id') function is a shortcut for the equivalent jQuery('##{rich:clientId('id')}) code. It returns the jQuery object for the element located by the passed server-side component identifier. If the specified component identifier is not found, null is returned instead.
18.5. rich:findComponent
rich:findComponent('id') function returns the a UIComponent instance of the passed component identifier. If the specified component identifier is not found, null is returned instead.
Example 18.1. rich:findComponent example
<h:inputText id="myInput"> <a4j:support event="keyup" render="outtext"/> </h:inputText> <h:outputText id="outtext" value="#{rich:findComponent('myInput').value}" />
18.6. rich:isUserInRole
rich:isUserInRole(Object) function checks whether the logged-in user belongs to a certain user role, such as being an administrator. User roles are defined in the web.xml settings file.
Example 18.2. rich:isUserInRole example
rich:isUserInRole(Object) function can be used in conjunction with the rendered attribute of a component to only display certain controls to authorized users.
<rich:editor value="#{bean.text}" rendered="#{rich:isUserInRole('admin')}"/>
Chapter 19. Functionality extension
19.1. <rich:componentControl>
<rich:componentControl> behavior allows JavaScript API functions to be called on target components. The functions are called after defined events are triggered on the component to with the <rich:componentControl> behavior is attached. Initialization variants and activation events can be customized, and parameters can be passed to the target component.
19.1.1. Basic usage
operation attribute is required to attach JavaScript functions to the parent component, along with either the target or selector attributes. Use the operation attribute to specify the JavaScript API function to perform. Use the target attribute to define the id identifier of the target component, or use the selector attribute to define a number of target components through the use of valid jQuery selectors.
event attribute to specify the event that triggers the JavaScript API function call if it is different from the default triggering event for the parent component.
Example 19.1. <rich:componentControl> basic usage
<h:commandButton value="Show Modal Panel"> <!--componentControl is attached to the commandButton--> <rich:componentControl target="ccModalPanelID" event="click" operation="show"/> </h:commandButton>
ccModalPanelID.
19.1.2. Passing parameters to API methods
<f:param> elements.
Example 19.2. Using parameters
<rich:componentControl event="click" target="modalPanel" operation="show"> <f:param value="width" name="500"/> </rich:componentControl>
<rich:hashParam> component to create a hash map. Refer to Section 19.4, “<rich:hashParam>” for details.
19.1.3. Reference data
client-behavior-renderer-type:org.richfaces.behavior.ComponentControlBehaviorbehavior-id:org.richfaces.behavior.ComponentControlBehaviorhandler-class:org.richfaces.taglib.ComponentControlHandlerbehavior-class:org.richfaces.component.behavior.ComponentControlBehaviorclient-behavior-renderer-class:org.richfaces.renderkit.html.ToggleControlRenderer
19.2. <rich:focus>
<rich:focus> component allows one to manipulate the focus of components on a page. It is intended to be used with any input field.
19.2.1. Placement
- in a form - defines behavior for components in the given form
- in a view (outside of forms) - defines behavior for components in all forms in the view
19.2.2. Applying Focus
ajaxRendered attribute to false.
19.2.3. Validation-Aware
<rich:focus> component reflects the results of validation of components in a view. Focus is given to the first input component in the page which is invalid.
tabindex and position in the page. You can prioritize the focusing of a specific component by increasing its tabindex.
validationAware attribute to false.
19.2.4. Preserving Focus
Example 19.3. <rich:focus> preserving focus
<h:form> <rich:focus preserve="true" /> <h:inputText id="query" value="#{query}" /> <a4j:commandButton value="Search" render="output" /> <h:outputText value="Searched query:" /> <h:outputText id="output" value="#{query}" /> </h:form>
19.2.5. Delaying Focus
delayed to true, the focus won't be applied on initial page request.
applyFocus() JavaScript API method in order to let the focus be applied.
19.2.6. Focus Manager
FocusManager.
FocusManager will take priority over any focus configuration.
Example 19.4. <rich:focus> preserving focus
FocusManager focusManager = ServiceTracker.getService(FocusManager.class); focusManager.focus("input2");
19.2.7. Reference data
component-type:org.richfaces.Focuscomponent-class:org.richfaces.component.UIFocuscomponent-family:org.richfaces.Focusrenderer-type:org.richfaces.FocusRenderer
19.3. <rich:hotKey>
<rich:hotKey> component allows one to register hot keys for the page or particular elements and to define client-side processing functions for these keys.
19.3.1. Basic usage
<rich:hotKey>:
- place it anywhere on the page. In this case the
<rich:hotKey>component is attached to the whole page. This is the default scenario. - attach it to specific elements by defining the
selectorattribute. This attribute uses the syntax of the jQuery Selectors (a superset of CSS selectors defined by W3C consortium) and additionally it expands JSF component IDs to client-side IDs (see the VDL documentation for theselectorattribute).
key attribute defines the hot key itself, which is processed by the component.
+" key separator. The key sequence modifiers needs to be defined in alphabetical order, e.g. alt+ctrl+shift.
rendered to false.
Example 19.5. <rich:hotKey> basic usage
<rich:hotKey key="ctrl+z"> <rich:componentControl target="popup" operation="show" /> </rich:hotKey> <rich:popupPanel id="popup"> ... </rich:popupPanel>
<rich:hotKey> which handles the Ctrl+Z key sequence on the whole page. When the key sequence is pressed, the <rich:popupPanel> is displayed.
19.3.2. Event processing
enabledInInput attribute enables the hot key event processing when form inputs are focused. This attribute is false by default.
preventDefault attribute specifies whether the hot key binding should prevent default browser-specific actions to be taken (e.g. Ctrl+A hot key selecting all available text, Ctrl+B opening bookmarks bar, etc.). This attribute has a default value of true.
Cross-browser support for preventing default actions
19.3.3. Event handlers
keydown(default event) is fired when the hot key sequence is initiated (the keys are down)keyupis fired when the hot key sequence is finished (the keys are up)
Example 19.6. <rich:hotKey> event handlers
<rich:hotKey key="ctrl+a" onkeyup="alert('Ctrl+A was pressed')" />
Hot Key in Editor
<rich:editor> uses <iframe> for the editable area.
<iframe> doesn't allow one to propagate events outside of the <rich:editor>, making <rich:hotKey> unusable for handling events from <rich:editor>.
19.3.4. Reference data
component-type:org.richfaces.HotKeycomponent-class:org.richfaces.component.UIHotKeycomponent-family:org.richfaces.HotKeyrenderer-type:org.richfaces.HotKeyRenderer
19.4. <rich:hashParam>
<rich:hashParam> component allows client-side parameters to be grouped into a hash map. The hash map can then be passed to the client JavaScript API functions of any RichFaces component.
19.4.1. Basic usage
<rich:hashParam> component to group them in the hash map. The hash map itself can then be passed as a function parameter.
Example 19.7. <rich:hashParam>
<h:commandButton value="Show popup"> <rich:componentControl target="popupPanel" operation="show"> <a4j:param noEscape="true" value="event" /> <rich:hashParam> <f:param name="width" value="500" /> <f:param name="height" value="300" /> <f:param name="minWidth" value="300" /> <f:param name="minHeight" value="150" /> <a4j:param noEscape="true" name="left" value="(jQuery(window).width()/2)-250" /> <a4j:param noEscape="true" name="top" value="(jQuery(window).height()/2)-150" /> </rich:hashParam> </rich:componentControl> </h:commandButton>
<rich:hashParam> component to group multiple parameters into a hash map. The parameters are passed through to the show function pop-up panel with the popupPanel identifier.
19.4.2. Reference data
component-type:org.richfaces.HashParametercomponent-class:org.richfaces.component.UIHashParametercomponent-family:org.richfaces.HashParameterhandler-class:javax.faces.view.facelets.ComponentHandler
19.5. <rich:placeholder>
<rich:placeholder> component allows one to use functionality similar to the HTML5 placeholder attribute for input components.
- per-component styling using
styleClassattribute - application to multiple components at once using
selectorattribute
Example 19.8. <rich:placeholder> with input components
<h:outputLabel value="Input text:" /> <h:inputText id="input"> <rich:placeholder value="Type text here..." /> </h:inputText> <h:outputLabel value="Textarea:" /> <h:inputTextarea id="textarea"> <rich:placeholder value="A space for long content..." /> </h:inputTextarea> <h:outputLabel value="Date:" /> <rich:calendar datePattern="dd/M/yyyy" enableManualInput="true"> <rich:placeholder value="dd/mm/yyyy" /> </rich:calendar>
19.5.1. Reference data
component-type:org.richfaces.Placeholdercomponent-class:org.richfaces.component.UIPlaceholdercomponent-family:org.richfaces.Placeholderrenderer-type:org.richfaces.PlaceholderRenderer
19.5.2. Style classes and skin parameters
Table 19.1. Style classes (selectors) and corresponding skin parameters
| Class (selector) | Skin Parameters | Mapped CSS properties |
|---|---|---|
|












































