JBoss.orgCommunity Documentation

Chapter 2. Getting started with RichFaces

2.1. Technical Requirements
2.2. Development environments
2.3. Setting up RichFaces
2.4. Creating a project with JBoss Tools
2.5. Creating a project with Maven
2.5.1. Setting up Maven
2.5.2. Using the RichFaces project archetype
2.6. Using RichFaces in existing JSF 2 projects

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.

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 environments, such as Idea or NetBeans, could also be used for RichFaces development, but are not detailed in this book.

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

  2. Unzip archive

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

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.

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.

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

  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:

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

  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:

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

    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 HelpInstall 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 FileImport from the menu.

    3. Select the project

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

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.