JBoss.orgCommunity Documentation

Developer Guide

Developing applications using RichFaces (draft)



Read this book for a comprehensive guide to getting started and working with RichFaces . It includes details of the architecture, the framework's use in different applications, and skinning implementations.

The RichFaces framework is a rich component library for JavaServer Faces (JSF). It allows integration of Ajax capabilities into enterprise web application development without needing to use JavaScript.

RichFaces leverages several parts of the JSF2 framework including lifecycle, validation, conversion facilities, and management of static and dynamic resources. The RichFaces framework includes components with built-in Ajax support and a customizable look-and-feel that can be incorporated into JSF applications.

RichFaces provides a number of advantages for enterprise web application development:

Follow the instructions in this chapter to configure the RichFaces framework and get started with application development. RichFaces applications can be developed using JBoss Tools, as described in Section 2.3, “Creating a project with JBoss Tools”; or using Maven, as described in Section 2.4, “Creating a project with Maven”.

If you have existing projects that use a previous version of RichFaces, refer to the RichFaces Migration Guide.

Follow the instructions in this section to set up the RichFaces framework and begin building applications.

  1. Download RichFaces archive

    Download RichFaces from the JBoss RichFaces Downloads area at http://www.jboss.org/richfaces/download.html. The binary files (available in .bin.zip or .bin.tar.gz archives) contain a compiled, ready-to-use version of RichFaces with a set of basic skins.

    • Compiling from source

      Instead of downloading the pre-compiled binaries, you can download the source files and compile them yourself. Refer to ??? for further instructions.

  2. Unzip archive

    Create a new directory named RichFaces, then unzip the archive containing the binaries there.

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. Version 2.2.1 is recommended.

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 Component Development Kit includes a Maven archetype named richfaces-archetype-simpleapp for generating the basic structure and requirements for a RichFaces application project. Maven can obtain the archetype from the JBoss repository at https://repository.jboss.org/nexus/content/groups/public/. The archetype is also included with the RichFaces source code. Follow the procedure in this section to generate a new Maven-based RichFaces project using the archetype.

  1. Add required repository

    The details for the JBoss repository need to be added to Maven so it can access the archetype. Add a profile in the maven_installation_folder/conf/settings.xml file under the <profiles> element:

                    <name>JBoss Public Maven Repository Group</name>
                    <name>JBoss Public Maven Repository Group</name>

    The profile then needs to be activated in the <activeProfiles> element:

  2. Generate the project from the archetype

    The project can now 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.0.0-SNAPSHOT -DgroupId=org.docs.richfaces -DartifactId=new_project

    The following parameters can be used to customize your project:


    Defines the package for the Managed Beans


    Defines the name of the project

    The command generates a new RichFaces project with the following structure:

    	├── pom.xml
    	└── src
    		└── main
    		    ├── java
    		    │   └── org
    		    │       └── docs
    		    │           └── richfaces
    		    │               └── RichBean.java
    		    └── webapp
    		        ├── index.xhtml
    		        ├── templates
    		        │   └── template.xhtml
    		        └── WEB-INF
    		            ├── faces-config.xml
    		            └── web.xml
  3. 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 full details on how to use the jsf-test project, refer to http://community.jboss.org/wiki/TestDrivenJSFDevelopment.

  4. 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 Tools.

  5. Import the project into an IDE

    Import the Maven project into your IDE. For Eclipse and JBoss Tools, you can import the project using the M2Eclipse plug-in.

    To install the plug-in, choose HelpInstall New Software from the menu. Type Maven to locate the Maven Integration for Eclipse Update Site entry, then type Maven in the filter to show the available plug-ins. Follow the prompts to install the Maven Integration for Eclipse plug-in.

    With the plug-in installed, open the importing wizard by choosing FileImport from the menu. Select MavenExisting Maven Projects as the import source and choose the pom.xml file for your project.

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/.