JBoss.orgCommunity Documentation
Read this chapter for technical details on the RichFaces framework.
RichFaces has been developed with an open architecture to be compatible with a wide variety of environments.
RichFaces 4 requires either of the following server technologies:
An application server compliant with Java Platform, Enterprise Edition 5 or 6 (JEE5 or JEE6), such as JBoss Application Server 6.
A major servlet container, such as Jetty 6 or Apache Tomcat 6.
Clients accessing RichFaces applications require a web browser. Richfaces supports the following web browsers:
Developing applications with the RichFaces framework requires the Java Development Kit (JDK), an implementation of JavaServer Faces (JSF), and a development environment.
RichFaces supports the following JDK versions:
JDK 1.5 and higher
RichFaces supports the following JSF implementations and frameworks:
MyFaces 2 and higher
Seam 3 and higher
Mojara 2 and higher
RichFaces can be developed using most Java development environments. The following are recommended, and used for examples in this guide:
JBoss Tools 3.1 and higher
Maven 2.0.9 and higher (2.2.1 recommended)
The important elements of the RichFaces framework are as follows:
Ajax Action Components
Ajax Containers
Ajax Output
Skins and Theming
RichFaces Ajax Extensions
Read this section for details on each element.
The RichFaces framework includes several Ajax Action Components and Submitting Bahaviors: <a4j:commandButton>, <a4j:commandLink>, <a4j:poll>, <a4j:ajax>, and more. Use Ajax Action Components to send Ajax requests from the client side.
AjaxContainer is an interface that marks part of the JSF tree that is decoded during an Ajax request. It only marks the JSF tree if the component or behavior sending the request does not explicitly specify an alternative. AjaxRegion is an implementation of this interface.
AjaxContainer is an interface that marks part of the JSF tree that will be updated and rendered on the client for every Ajax request. It only marks the JSF tree if the component or behavior sending the request does not explicitly turn off automatic updates.
RichFaces includes extensive support for application skinning. Skinning is a high-level extension to traditional CSS (Cascading Style Sheets) which allows the color scheme and appearance of an application to be easily managed. The skins simplify look-and-feel design by allowing multiple elements of the interface to be handled as manageable features, which have associated color palettes and styling. Application skins can additionally be changed on the fly during run-time, allowing user experiences to be personalized and customized.
For full details on skinning and how to create skins for the components in your application, refer to Chapter 6, Skinning and theming.
RichFaces 4 features full JSF 2 integration and uses standard web application technologies such as JavaScript, XML (Extensible Markup Language), and XHTML (Extensible Hypertext Markup Language).
JavaServer Faces 2 evaluates Ajax options, such as execute and render, while rendering a page. This allows any parameters to be sent directly from the client side.
RichFaces evaluates the options when the current request is sent. This increases both the security of the data and the convenience for evaluating parameters.
For example, binding Ajax options to Java Bean properties in RichFaces allows you to evaluate the options dynamically for the current request, such as defining additional zones to render. Parameters changed manually on the client side will not influence the request processing. With JSF 2, the options have evaluated during the previous page rendering would need to be used.
The following restrictions apply to applications implementing the RichFaces framework:
As with most Ajax frameworks, you should not attempt to append or delete elements on a page using RichFaces Ajax, but should instead replace them. As such, elements that are rendered conditionally should not be targeted in the render attributes for Ajax controls. For successful updates, an element with the same identifier as in the response must exist on the page. If it is necessary to append code to a page, include a placeholder for it (an empty element).
JSF 2 does not allow resources such as JavaScript or Cascading Style Sheets (CSS) to be added if the element requiring the resource is not initially present in the JSF tree. As such, components added to the tree via Ajax must have any required resources already loaded. In RichFaces, any components added to the JSF tree should have components with corresponding resources included on the main page initially. To facilitate this, components can use the rendered="false" setting to not be rendered on the page.
Switching RichFaces skins via Ajax during runtime should be avoided, as this requires all the stylesheets to be reloaded.
The source code for the RichFaces framework can be compiled manually rather than using the pre-compiled binaries.
Acquiring the source code
JBoss RichFaces Downloads area
Download the RichFaces distribution as described in Section 2.3, “Setting up RichFaces”. The distribution bundles contain the full RichFaces source code.
Anonymous SVN repository
Alternatively, the source files can be checked out from the anonymous SVN repository at http://anonsvn.jboss.org/repos/richfaces/branches/4.0.X/ using the following command:
svn co http://anonsvn.jboss.org/repos/richfaces/branches/4.0.X/
Unzip archive
If using the downloaded distribution, create a new directory named RichFaces, then unzip the archive containing the source code there.
Configure Maven for RichFaces
To compile the RichFaces source code, Maven requires access to the JBoss repositories. Refer to Step 1 of the procedure in Section 2.5.2, “Using the RichFaces project archetype” to configure the required repositories.
Compile using Maven
In the root directory of the unzipped source code, enter the following command to compile and build the RichFaces framework:
mvn clean install
Add any of the following options after the command to customize the build:
-P release,docsMaven additionally builds the documentation and release artifacts.
-D skipTests=trueMaven skips the unit and functional tests, which completes the build faster.
-D checkstyle.skip=trueMaven skips the scans for checking style, which completes the build faster.
-D skip-source
Maven does not produce any source jar files from the build.
-D skip-enforce
Maven does not check for the correct JDK version, Maven version, and SNAPSHOT plug-in, and forces the build.
-D jsf-profile=implementation
Maven tests builds and tests against the specified JSF implementation. The implementation value can be any of the following:
jsf_ri: The latest release of JSF RI (Mojarra). This is the default implemenation.
jsf_ri_javax: The latest release of javax.faces.
jsf_ri_snapshot: The latest snapshot version of JSF RI (Mojarra).
myfaces: The latest release of MyFaces.
myfaces: The latest snapshot version of MyFaces.
Access compiled binaries
The compiled libraries are located in the following sub-directories of the root RichFaces directory:
/ui/dist/richfaces-components-api/target/richfaces-components-api-
version-SNAPSHOT.jar
/ui/dist/richfaces-components-ui/target/richfaces-components-ui-
version-SNAPSHOT.jar
/core/api/target/richfaces-core-api-
version-SNAPSHOT.jar
/core/impl/target/richfaces-core-impl-
version-SNAPSHOT.jar
You can now add the compiled libraries to your project as described in Step 2 of Section 2.4, “Creating a project with JBoss Tools”.