JBoss.orgCommunity Documentation

Chapter 3. RichFaces overview

3.1. Full technical requirements
3.1.1. Server requirements
3.1.2. Client requirements
3.1.3. Development requirements
3.2. Architecture
3.2.1. Ajax Action Components
3.2.2. Ajax Containers
3.2.3. Skins and theming
3.2.4. RichFaces JavaScript Engine
3.3. Technologies
3.4. Differences between JSF and RichFaces mechanisms
3.5. Restrictions
3.6. Compiling from source code

Documentation in development

Some concepts covered in this chapter may refer to the previous version of Richfaces, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date.

The RichFaces framework is a component library which enhances JSF Ajax capabilities, such that you don't need to write any extra JavaScript code or replace any existing components with new Ajax widgets. RichFaces also enables page-wide Ajax support instead of the traditional component-wide support. Events can be defined on pages that invoke Ajax requests. After an Ajax request, the areas of a page that are synchronized with the JSF Component Tree can themselves change data on the server according to events fired on the client.

Figure 3.1, “Request processing flow” illustrates how requests are processed in the RichFaces framework.

Request processing flow

[D]

Figure 3.1. Request processing flow


Using JSF tags, RichFaces allows different parts of a JSF page to be updated with an Ajax request. JSF pages using RichFaces do not change from "regular" JSF pages, and additional JavaScript code is not required.

3.1. Full technical requirements

RichFaces has been developed with an open architecture to be compatible with a wide variety of environments.

A Java application server or servlet container is required for running RichFaces applications. RichFaces supports the following servers:

Clients accessing RichFaces applications require a web browser. Richfaces supports the following web browsers:

Linux environments

  • Firefox 3.0 and higher

  • Google Chrome

  • Opera 9.5 and higher

Mac OS environments

  • Firefox 3.5 and higher

  • Google Chrome

  • Safari 3.0 and higher

Microsoft Windows environments

  • Firefox 3.0 and higher

  • Google Chrome

  • Internet Explorer 7.0 and higher

  • Opera 9.5 and higher

  • Safari 3.0 and higher

Developing applications with the RichFaces framework requires the Java Development Kit (JDK), an implementation of JavaServer Faces (JSF), and a development environment.

Java Development Kit (JDK)

RichFaces supports the following JDK versions:

JavaServer Faces (JSF)

RichFaces supports the following JSF implementations and frameworks:

Development environment

RichFaces can be developed using most Java development environments. The following are recommended, and used for examples in this guide:

3.2. Architecture

The important elements of the RichFaces framework are as follows:

Read this section for details on each element.

The RichFaces framework includes several Ajax Action Components: <a4j:commandButton>, <a4j:commandLink>, <a4j:poll>, <a4j:support>, and more. Use Ajax Action Components to send Ajax requests from the client side.

AjaxContainer (name possibly changed in release) is an interface that describes an area on a JSF page that is decoded during an Ajax request. AjaxViewRoot and AjaxRegion are implementations of this interface.

RichFaces includes extensive support for application skinning. Skinning is a high-level extension to traditional CSS (Cascading Style Sheets) which allows the color scheme and appearance of an application to be easily managed. The skins simplify look-and-feel design by allowing multiple elements of the interface to be handled as manageable features, which have associated color palettes and styling. Application skins can additionally be changed on the fly during run-time, allowing user experiences to be personalized and customized.

For full details on skinning and how to create skins for the components in your application, refer to Chapter 6, Skinning and theming.

The RichFaces JavaScript Engine runs on the client side. It can update different areas on a JSF page based on an Ajax response. It is not necessary to use the JavaScript code directly, as it is available automatically.

3.3. Technologies

RichFaces originated from the Ajax4jsf project, an open-source web application framework that added Ajax capabilities to the JavaServer Faces (JSF) framework. The RichFaces components were split into a separate commercial component library, then later both the Ajax4jsf and RichFaces libraries were re-combined under the RichFaces name.

RichFaces 4.0 features full JSF2 integration and uses standard web application technologies such as JavaScript, XML (Extensible Markup Language), and XHTML (Extensible Hypertext Markup Language).

3.4. Differences between JSF and RichFaces mechanisms

3.5. Restrictions

The following restrictions apply to applications implementing the RichFaces framework:

3.6. Compiling from source code

The source code for the RichFaces framework can be downloaded and compiled manually rather than using the pre-compiled binaries.

  1. Download source code

  2. Unzip archive

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

  3. Configure Maven with JBoss developer settings

    To compile the RichFaces source code, Maven requires access to JBoss development repositories. Edit the maven_installation_folder/conf/settings.xml file and add the following settings:

    Server definitions
    
<servers>
    
    <server>
    
        <id>jboss-developer-repository-group</id>
    
        <username>username</username>
    
        <password>password</password>
    
    </server>
    
    <server>
    
        <id>jboss-screenshots-repository</id>
    
        <username>username</username>
    
        <password>password</password>
    
    </server>
    
    <server>
    
        <id>jboss-releases-repository</id>
    
        <username>username</username>
    
        <password>password</password>
    
    </server>
    
    ...
    
</servers>

    Change the username and password in your server definitions to your JBoss.org username and password.

    Mirror definitions
    
<mirrors>
    
    <mirror>
    
        <id>jboss-developer-repository-group</id>
    
        <mirrorOf>*,!jboss-deprecated</mirrorOf>
    
        <name>JBoss.org Developer Repository Group</name>
    
        <url>https://repository.jboss.org/nexus/content/groups/developer/</url>
    
    </mirror>
    
    ...
    
</mirrors>
    Profile definitions
    
<profiles>
    
    <!-- Redefine the Maven central repository to enable snapshots.  The url will be replaced by the mirror -->
    
    <profile>
    
        <id>jboss-nexus</id>
    
        <repositories>
    
            <repository>
    
                <id>central</id>
    
                <name>Central repository proxy</name>
    
                <url>replaced by mirror settings</url>
    
                <layout>default</layout>
    
                <releases>
    
                    <enabled>true</enabled>
    
                </releases>
    
                <snapshots>
    
                    <enabled>true</enabled>
    
                    <updatePolicy>never</updatePolicy>
    
                </snapshots>
    
            </repository>
    
        </repositories>
    
        <pluginRepositories>
    
            <pluginRepository>
    
                <id>central</id>
    
                <url>replaced by mirror settings</url>
    
                <releases>
    
                    <enabled>true</enabled>
    
                </releases>
    
                <snapshots>
    
                    <enabled>true</enabled>
    
                </snapshots>
    
            </pluginRepository>
    
        </pluginRepositories>
    
    </profile>
    
    ...
    
</profiles>
    Activate profile
    
<activeProfiles>
    
    <activeProfile>jboss-nexus</activeProfile>
    
    ...
    
</activeProfiles>

  4. Compile using Maven

    In the root directory of the unzipped source code, enter the following command to compile and build the RichFaces framework: 

    mvn clean install

    Add any of the following options after the command to customize the build:

    -P release,docs

    Maven additionally builds the documentation and release artifacts.

    -D skipTests=true

    Maven skips the unit and functional tests, which completes the build faster.

    -D checkstyle.skip=true

    Maven skips the scans for checking style, which completes the build faster.

    -D skip-source

    Maven does not produce any source jar files from the build.

    -D skip-enforce

    Maven does not check for the correct JDK version, Maven version, and SNAPSHOT plug-in, and forces the build.

    -D jsf-profile=implementation

    Maven tests builds and tests against the specified JSF implementation. The implementation value can be any of the following:

    • jsf_ri: The latest release of JSF RI (Mojarra). This is the default implemenation.

    • jsf_ri_javax: The latest release of javax.faces.

    • jsf_ri_snapshot: The latest snapshot version of JSF RI (Mojarra).

    • myfaces: The latest release of MyFaces.

    • myfaces: The latest snapshot version of MyFaces.

  5. Access compiled binaries

    The compiled libraries are located in the following sub-directories of the root RichFaces directory:

    • ui/assembly/target/dist/richfaces-ui-version-SNAPSHOT.jar

    • framework/api/target/richfaces-api-version-SNAPSHOT.jar

    • framework/impl/target/richfaces-impl-version-SNAPSHOT.jar

    If Maven built the framework using the -P release option, the distribution package containing all three compiled libraries and reference documentation is located at ui/assembly/target/dist/richfaces-ui-version-SNAPSHOT-bin.zip.

You can now add the compiled libraries to your project as described in Step 2 of Section 2.3, “Creating a project with JBoss Tools”.