Chapter 2. Getting started with RichFaces

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:
- compiled, ready-to-use Java Archives (JAR files) of the RichFaces library
- library source JAR files
- documentation, including Java documentation and JavaScript documentation
- archetypes
- example source code
Unzip the archive
Create a new directory named RichFaces, then unzip the archive that contains the binaries into this new directory.

2.4. Creating a project with JBoss Developer Studio™

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 5 template. In JBoss Developer Studio™, 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 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.
Reference the tag library
The RichFaces tag library must be referenced on each XHTML page in your project:
```
<ui:composition xmlns:r="http://richfaces.org">

   ...

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

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 3.0.4 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 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=5.0.0.Alpha2 -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 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™, 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 Developer Studio 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 5.0.0.Alpha2. 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 Developer Studio” for details.

Application-level settings

In RichFaces 5, it is not necessary to add any extra settings to the web.xml or config.xml settings files to use the framework.