Chapter 2. Getting started with RichFaces

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.

2.1. Technical Requirements

The minimum technical requirements needed to get started with RichFaces are outlined below.

Java Development Kit (JDK) 1.5 or higher
An application server compliant with Java Platform, Enterprise Edition 5 (JEE5), such as JBoss Application Server 6 or Apache Tomcat 6.
A compliant web browser, such as Firefox 3.5 or Internet Explorer 7

2.2. Development environments

RichFaces applications can be developed using a range of tools, including integrated development environments (IDEs). This chapter covers only two such environments in detail:

JBoss Tools, as described in Section 2.4, “Creating a project with JBoss Tools”.
Maven, as described in Section 2.5, “Creating a project with Maven”.

Other environments, such as Idea or NetBeans, could also be used for RichFaces development, but are not detailed in this book.

2.3. Setting up RichFaces

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

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 the following:
- compiled, ready-to-use Java Archives (JAR files) of the RichFaces libraries
- library source JAR files
- documentation, including Java documentation and JavaScript documentation
- archetypes
- example source code
- Compiling from source
  Instead of using the pre-compiled binaries, you can compile the source files yourself. Refer to Section 3.6, “Compiling from source code” for further instructions.
Unzip archive
Create a new directory named RichFaces, then unzip the archive containing the binaries there.

2.4. Creating a project with JBoss Tools

Follow the procedure in this section to create a new RichFaces application with JBoss Tools Ensure you are using the latest version of JBoss Tools.

Create a new project
Create a new project based on the JSF 2 environment using the RichFaces 4 template. In JBoss Tools, select File → New → JSF Project from the menu. Name the project, select JSF 2 from the JSF Environment drop-down box, and click the Finish 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 richfaces-core-api.jar, richfaces-core-impl.jar, richfaces-components-api.jar, and richfaces-components-ui.jar into your project. Copy them from the location where you unzipped the RichFaces archive to the WebContent/WEB-INF/lib/ directory of your project in JBoss Tools.

Reference the tag libraries

The RichFaces tag libraries need to be referenced on each XHTML page in your project:


<ui:composition xmlns:a4j="http://richfaces.org/a4j"

                xmlns:rich="http://richfaces.org/rich">

   ...

</ui:composition>

You are now ready to begin constructing your RichFaces applications. RichFaces components can be dragged and dropped into your application's XHTML pages from the RichFaces palette in JBoss Tools.

2.5. Creating a project with Maven

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.

2.5.1. Setting up Maven

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 2.0.9 or above is required.

Once Maven has been installed, no further configuration is required to begin building Maven projects.

2.5.2. Using the RichFaces project archetype

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 in the archetypes directory. Follow the procedure in this section to generate a new Maven-based RichFaces project using the archetype.

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:


<profiles>

    ...

    <profile>

        <id>jboss-public-repository</id>

        <repositories>

            <repository>

                <id>jboss-public-repository-group</id>

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

                <url>https://repository.jboss.org/nexus/content/groups/public/</url>

                <layout>default</layout>

                <releases>

                    <enabled>true</enabled>

                    <updatePolicy>never</updatePolicy>

                </releases>

                <snapshots>

                    <enabled>true</enabled>

                    <updatePolicy>never</updatePolicy>

                </snapshots>

            </repository>

        </repositories>

        <pluginRepositories>

            <pluginRepository>

                <id>jboss-public-repository-group</id>

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

                <url>https://repository.jboss.org/nexus/content/groups/public/</url>

                <layout>default</layout>

                <releases>

                    <enabled>true</enabled>

                    <updatePolicy>never</updatePolicy>

                </releases>

                <snapshots>

                    <enabled>true</enabled>

                    <updatePolicy>never</updatePolicy>

                </snapshots>

            </pluginRepository>

        </pluginRepositories>

    </profile>

</profiles>

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


<activeProfiles>

   <activeProfile>jboss-public-repository</activeProfile>

</activeProfiles>

For further details, refer to the JBoss RichFaces Wiki.

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:

-DgroupId: Defines the package for the Managed Beans
-DartifactId: 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 full details on how to use the jsf-test project, refer to http://community.jboss.org/wiki/TestDrivenJSFDevelopment.
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.
Import the project into an IDE
To import the project into Eclipse and JBoss Tools, use the JBoss Maven Integration plug-ins. These plug-ins work with plug-ins from the M2Eclipse project to import Maven projects.
1. Install the plug-ins
  1. Choose Help → Install New Software from the Eclipse menu.
  2. Select the JBoss Tools update site to use, then open the Maven Support group and select the JBoss Maven Integration and JBoss Maven JSF Configurator plug-ins.
  3. Follow the prompts to install the integration plug-ins. The installation will automatically include the transitive dependencies Maven Integration for Eclipse and Maven Integration for WTP. Both of these dependencies are from the M2Eclipse project.
  4. Restart Eclipse to finish the installation.
2. Open the importing wizard
  With the plug-ins installed, open the importing wizard by choosing File → Import from the menu.
3. Select the project
  Select Maven → Existing Maven Projects as the import source and choose the directory with the pom.xml file for your project.
Exporting from Maven
The ability to prepare the project for Eclipse and export it using Maven is deprecated in RichFaces 4.0. 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/.

2.6. Using RichFaces in existing JSF 2 projects

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 Tools” for details.

Application-level settings

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.

Exporting from Maven

Application-level settings