JBoss.orgCommunity Documentation
Some concepts covered in this chapter may refer to the previous version of Richfaces, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date.
Read this chapter for details on some of the advanced features and configuration possibilities for the RichFaces framework.
JavaServer Faces (JSF) is the Java-based web application framework upon which the RichFaces framework has been built. RichFaces is now integrated with JSF2, which features several improvements to the framework.
The standard display technology used by JSF1 was JavaServer Pages (JSP). With JSP2, the standard display technology has been changed to Facelets, which is a more powerful and more efficient View Declaration Language (VLD) than JSP.
The RichFaces framework includes several components designed to improve application performance. Script and style management can be optimized with resource-loading components such as <a4j:loadBundle>, <a4j:loadScript>, and <a4j:loadStyle>.
For further details on optimizing the performance of RichFaces applications, refer to the Resources and Processing management chapters in the Component Reference Guide.
The RichFaces framework allows for queues to manage traffic from Ajax requests, events, and page updates. Controlling the message processing with a queue can make applications more efficient and avoid problems with data corruption. Basic queuing is available with all RichFaces components, and the <a4j:queue> component adds advanced queuing to standard JSF components.
For further details on RichFaces queue management, refer to the queuing details in the Common Ajax attributes chapter and the Processing management chapter in the Component Reference Guide.
The RichFaces framework features several validation components. These components can validate Ajax actions, or validate data against model-based constraints defined using Hibernate Validator.
For further details on RichFaces validation components, refer to the Validation chapter of the Component Reference Guide.
Scripts and styles are normally loaded into a RichFaces application on demand. The default loading strategy can be altered to suit certain applications by specifying the strategy in the web.xml file.
The script-loading strategy is specified as follows:
<context-param>
<param-name>org.richfaces.LoadScriptStrategy</param-name>
<param-value>ALL</param-value>
</context-param>
The <param-value> element can be set to one of three values:
ALLAll scripts are loaded when the application starts.
When org.richfaces.LoadScriptStrategy is set to ALL, JavaScript file compression is turned off.
DEFAULTScripts are loaded as required. If not otherwise specified, this is the normal script-loading behavior.
NONENo scripts are loaded. This can be useful for including scripts manually.
The style-loading strategy is specified as follows:
<context-param>
<param-name>org.richfaces.LoadStyleStrategy</param-name>
<param-value>ALL</param-value>
</context-param>
The <param-value> element can be set to one of three values:
ALLAll styles from a single integrated style sheet are loaded when the application starts.
DEFAULTStyles are loaded as required. If not otherwise specified, this is the normal style-loading behavior.
NONE
No styles are loaded. The default plain skin resets all color and font parameters to null. Any pre-defined styles for RichFaces are not used.
RichFaces allows standard handlers to be defined for processing different application exceptions. Custom JavaScript can be executed when these exceptions occur.
To define handlers for application exceptions, add the following code to your web.xml file:
<context-param>
<param-name>org.ajax4jsf.handleViewExpiredOnClient</param-name>
<param-value>true</param-value>
</context-param>
Custom error handlers for the onError and onExpire events do not work under MyFaces. MyFaces handles exceptions through its internal debug page. Use the following code in the web.xml file to prevent this behavior in MyFaces:
<context-param>
<param-name>org.apache.myfaces.ERROR_HANDLING</param-name>
<param-value>false</param-value>
</context-param>
To execute custom JavaScript code on the client when an error occurs during an Ajax request, redefine the standard A4J.AJAX.onError method, as shown in Example 5.1, “Example request error”.
Example 5.1. Example request error
A4J.AJAX.onError = function(req, status, message){
window.alert("Custom onError handler "+message);
}
The function accepts three parameters:
reqA string of parameters from the request that caused the error.
statusThe error number returned by the server.
messageA default message for the error.
Redefine the A4J.AJAX.onExpired method to handle the expiration of a user's session, as shown in Example 5.2, “Example session expiration error”.
Example 5.2. Example session expiration error
A4J.AJAX.onExpired = function(loc, expiredMsg){
if(window.confirm("Custom onExpired handler "+expiredMsg+" for a location: "+loc)){
return loc;
} else {
return false;
}
}
The function accepts two parameters:
locThe URL of the current page, which can be updated on demand.
expiredMsgA default message for the session expiration error.
JavaServer Faces (JSF) has an advanced navigation mechanism that allows you to define navigation from one view to another. Navigation typically happens in a web application when a user moves from one page to another, but there is no switch mechanism between certain logical states in the same view. The RichFaces State API allows sets of states to be defined for the views, as well as any properties associated with these states.
Actually States is a map where the entry key is a name of the State and the value is a State map. Particular State map has entries with some names as keys and any objects as values that are used after the state activation. Thus, in the State map you could define any values, method bindings, or just some simple state variables (constants) which have different values for every State.
To check whether the logged-in user belongs to a certain user role, use the rich:isUserInRole(Object) function in RichFaces. The example demonstrates the function's use to render controls only for users with administrator privileges.
Example 5.3. User role example
Certain controls only need to be rendered for administrators.
Create admin role
Create the admin role in the web.xml file:
<security-role>
<role-name>admin</role-name>
</security-role>
Implement authorization for users
Assign the admin role to users when they log in to the application as administrators.
Use the rich:isUserInRole(Object) function
The rich:isUserInRole(Object) function can be used with the rendered attribute of any component:
<rich:editor value="#{bean.text}" rendered="#{rich:isUserInRole('admin')}" />