JBoss.orgCommunity Documentation
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 JSF 2, which features several improvements to the framework.
RichFaces allows standard handlers to be defined for processing different application exceptions. Custom JavaScript can be executed when these exceptions occur.
JSF provides a global onError
handler on the client. The handler provides the relevant error code and other associated data. The RichFaces Ajax components provide the error
attribute if extra functionality needs to be defined.
Additional processing is available through a number of components, such as the following:
<a4j:status>
component has an additional error state.
<a4j:queue>
component can be used to process errors.
RichFaces provides a number of advanced functions, such as managing user roles and identifying elements. Refer to the Functions chapter in the RichFaces Component Reference for further details.
The RichFaces improves a standard JSF resource handling in order to achieve following features:
For leveraging RichFaces resource loading improvements, the ResourceServlet
needs to be registered.
ResourceServlet
is automatically registered in the Servlet 3.0 and higher environments.
In the Servlet 2.5 and lower environments, it is necessary to register the ResourceServlet
manually in the WEB-INF/web.xml
configuration file:
<servlet>
<servlet-name>Resource Servlet</servlet-name>
<servlet-class>org.richfaces.webapp.ResourceServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Resource Servlet</servlet-name>
<url-pattern>/org.richfaces.resources/*</url-pattern>
</servlet-mapping>
The resource optimization feature provides optimized component dependencies - JavaScript, CSS - which are compressed and aggregated to resource packages.
The loading of compressed resource packages may lead into significant client performance boost, since many small files are aggregated into one big file - the number of HTTP connections necessary to download application resources is significantly decreased.
Example 5.1. Enabling resource optimization
To enable the resource optimization, add a following configuration to web.xml
:
<context-param>
<param-name>org.richfaces.resourceOptimization.enabled</param-name>
<param-value>true</param-value>
</context-param>
Example 5.2. Resource optimization in development JSF project stage
Resource optimization is influenced by the project stage:
Switch to the development project stage during a development:
<context-param>
<param-name>javax.faces.PROJECT_STAGE</param-name>
<param-value>Development</param-value>
</context-param>
The resource mapping feature maps an existing JSF resource (determined by library and name) to a another resource.
This feature can help to solve the following cases:
Configuring the resource mapping means adding new records to the class-path file META-INF/richfaces/static-resource-mappings.properties
.
Each line in the configuration file represents one relocation.
A following sample shows a JSF resource with the name resourceLibrary:resourceName
relocated to a resource anotherResourceLibrary:anotherResourceName
:
resourceLibrary\:resourceName=anotherResourceLibrary/anotherResourceName
The definition above contains a JSF resource name on the left side of the expression and a relative path on the right side.
The expression on the right side represents a path relative to a JSF resource root, thus resource path anotherResourceLibrary/anotherResourceName
actually maps to a JSF resource with name anotherResourceLibrary:anotherResourceName
.
It is possible to define additional resource mapping configuration files by using a contextual parameter identifying the class-path locations where the files reside: org.richfaces.resourceMapping.mappingFile
(a comma-separated list of the class-path files).
Example 5.3. Providing alternative file
All requests for jquery.js
are served as requests for jquery-alternative-version.js
:
jquery.js=jquery-alternative-version.js
Example 5.4. Mapping several resources to one
Both some:jquery.js
and another:jquery.js
are mapped to final:jquery.js
:
some\:jquery.js=final/jquery.js another\:jquery.js=final/jquery.js
Example 5.5. Using external resources
Mappings with a resource path starting with http://
or https://
are served as absolute resource locations:
A following sample instructs to load jquery.js
from CDN:
jquery.js=http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js