JBoss.orgCommunity Documentation
Follow the instructions in this chapter to configure the RichFaces framework and get started with application development.
If you have existing projects that use a previous version of RichFaces, refer to the RichFaces Migration Guide .
The minimum technical requirements needed to get started with RichFaces are outlined below.
The RichFaces library is distributed across three jars providing all the components and services of the RichFaces framework.
RichFaces Library
richfaces-core.jar
richfaces-a4j.jar
richfaces-rich.jar
The framework depends on both mandatory and optional third-party dependencies. Some of the framework services are only enabled when the optional libraries are present.
Note that these dependencies may further depend on their own runtime dependencies.
Mandatory third-party dependencies
Java Server Faces 2.x implementation
javax.faces.jar (version 2.1.28 or higher)
myfaces-impl.jar (version 2.1.10 or higher)
Google Guava
guava.jar (version 18.0)
CSS Parser
cssparser.jar (version 0.9.14)
Simple API for CSS
sac.jar (version 1.3)
Optional third-party dependencies
Bean validation (JSR-303) integration for client-side validation (JSR-303 API and Implementation)
validation-api.jar (version 1.0.0.GA)
hibernate-validator.jar (version [code]+4.3.2.Final)
Push transport library - Atmosphere (without dependencies)
atmosphere-runtime.jar (version 2.2.3)
(selected compatibility modules atmosphere-compat-*.jar may be necessary)
Push JMS integration (JMS API and Implementation)
jms.jar (version 1.1)
hornetq-jms.jar (version 2.2.7.Final or higher)
Push CDI integration (CDI API and Implementation)
cdi-api.jar (version 1.0-SP4)
javax.inject.jar (version 1)
jsr-250-api.jar (version 1.0)
weld-servlet.jar (version 2.2.6.Final)
Extended caching (EhCache)
ehcache.jar (version 2.8.3)
Some of the dependencies are part of the Java EE 6 specification and thus it is not necessary to include them in projects running on Java EE applications servers. It is still necessary to include them when using servlet containers.
This does not apply to dependencies on the Servlet API: the JSP API and the EL API. These APIs are integral parts of both application servers and servlet containers.
RichFaces applications can be developed using a range of tools, including integrated development environments (IDEs). This chapter covers only two such environments in detail:
Other development environments such as Idea™ or NetBeans™ could also be used for RichFaces development, but such usage is not detailed in this book.
Follow the instructions in this section to set up a project with the RichFaces framework and begin building applications.
Download the RichFaces archive
Download RichFaces from the JBoss RichFaces Downloads area at http://www.jboss.org/richfaces/download.html. The binary files (available as a .zip archive) contain the following:
Unzip the archive
Create a new directory named RichFaces, then unzip the archive that contains the binaries into this new directory.
Follow the procedure in this section to create a new RichFaces application with JBoss Developer Studio™. Ensure you are using the latest version of JBoss Developer Studio™ to take advantage of the latest feautures and stability improvements.
Create a new project
Create a new project based on the JSF 2 environment using the RichFaces 4 template. In JBoss Developer Studio™, select → from the menu. Name the project, select JSF 2 from the JSF Environment drop-down box, and click the button to create the project.
If necessary, update the JSF 2 JAR files to the latest versions.
Add the RichFaces libraries to the project
Add the RichFaces libraries and their mandatory dependencies to the project. Copy them from the location where you unzipped the RichFaces archive to the WebContent/WEB-INF/lib/ directory of your project in JBoss Developer Studio.
The RichFaces tag libraries must be referenced on each XHTML page in your project:
<ui:composition xmlns:rich="http://richfaces.org/rich">
<ui:composition xmlns:a4j="http://richfaces.org/a4j">
...
</ui:composition>
You are now ready to begin developing your RichFaces application. RichFaces components can be dragged and dropped from the JBoss Developer Studio™ RichFaces palette into your application’s XHTML pages.
Apache Maven™ is a build automation and project management tool for Java projects. Follow the instructions in this section to create a Maven™ project for RichFaces™.
Maven™ can be downloaded and installed from Apache’s website at http://maven.apache.org/download.html. Due to the use of dependency importing, Maven™ version 3.0.4 or above is required.
Once Maven™ has been installed, no further configuration is required to begin building Maven projects.
A Maven archetype is a template for creating projects. Maven™ uses an archetype to generate a directory structure and files for a particular project, as well as creating pom.xml files that contain build instructions.
The RichFaces distribution includes a Maven archetype named richfaces-archetype-simpleapp for generating the basic structure and requirements of a RichFaces application project. Maven can obtain the archetype from maven central at http://search.maven.org. The archetype is also included with the RichFaces distribution in the archetypes directory. Follow the procedure in this section to generate a new Maven-based RichFaces project using the archetype.
Generate the project from the archetype
The project can be generated with the richfaces-archetype-simpleapp archetype. Create a new directory for your project, then run the following Maven command in the directory:
mvn archetype:generate -DarchetypeGroupId=org.richfaces.archetypes -DarchetypeArtifactId=richfaces-archetype-simpleapp -DarchetypeVersion=4.5.18-SNAPSHOT -DgroupId=org.docs.richfaces -DartifactId=new_project
The following parameters can be used to customize your project:
Defines the name of the project
The command generates a new RichFaces project with the following structure:
new_project
├── pom.xml
├── readme.txt
└── src
└── main
├── java
│ └── org
│ └── docs
│ └── richfaces
│ └── RichBean.java
└── webapp
├── index.xhtml
├── templates
│ └── template.xhtml
└── WEB-INF
├── faces-config.xml
└── web.xml
Add test dependencies (optional)
Your root directory of your project contains a project descriptor file: pom.xml. If you wish to include modules for test-driven JSF development, add any dependencies for the tests to the pom.xml file.
For testing the server-side part of your application, check out JBoss Arquillian project™.
If you want to test JSF from client’s perspective with ability to access state of JSF internals, use Arquillian Warp™.
For automation of client-side tests in real-browser, you may want to employ Arquillian Graphene™ and Arquillian Drone™ extensions.
Build the project
Build the project from the command line by entering the mvn install command.
The BUILD SUCCESSFUL message indicates the project has been assembled and is ready to import into an IDE (integrated development environment), such as JBoss Developer Studio™.
Import the project into an IDE
To import the project into Eclipse™ and JBoss Developer Studio™, open the importing wizard by choosing → from the menu.
Select the project
Select → as the import source and choose the directory with the pom.xml file for your project.
The ability to prepare the project for Eclipse and export it using Maven is deprecated in RichFaces 4.5.18-SNAPSHOT. The process does not support JBoss integration-specific features, such as JSF Facets.
Your project is now ready to use. Once components and functionality have been added, you can run the application on a server and access it through a web browser at the address http://localhost:8080/jsf-app/ (where jsf-app is the name of your project).
RichFaces can be added to existing JSF 2 projects by adding the new RichFaces libraries. Refer to Step 2 and Step 3 in Section 2.4, “Creating a project with JBoss Developer Studio” for details.
In RichFaces 4, it is not necessary to add any extra settings to the web.xml or config.xml settings files to use the framework.