image::https://raw.github.com/richfaces/docs/4.3.1.20130305-Final/Component_Reference/src/main/docbook/en-US/images/rf_logo.png[[RichFaces Project Logo]

RichFaces 4.5 image:https://travis-ci.org/richfaces/richfaces.png?branch=master[alt="Build Status", link="https://travis-ci.org/richfaces/richfaces"]

'''

= The next-generation JSF component framework by JBoss, Red Hat

> The RichFaces project is an advanced UI component framework for easily integrating Ajax capabilities into business applications using JSF.


== Project Info

--
[horizontal]
License:: LGPL v2.1
Build System::  Maven
--

* http://richfaces.org[Project Site]
* http://docs.jboss.org/richfaces/[Documentation]
* https://issues.jboss.org/browse/RF[Issue Tracker]
* http://planet.jboss.org/feed/richfacesall[News / RSS] (includes release announcements)
* https://community.jboss.org/thread/213160[Roadmap]
* https://developer.jboss.org/en/richfaces/content[User Forums]
* https://developer.jboss.org/en/richfaces/dev/content[Developer Forums]
* IRC: `#richfaces` at `irc.freenode.net`
* https://developer.jboss.org/en/richfaces/dev/teammtgs[Team Meetings]
* https://travis-ci.org/richfaces/richfaces/builds[Continuous Integration] image:https://travis-ci.org/richfaces/richfaces.png?branch=master[alt="Build Status", link="https://travis-ci.org/richfaces/richfaces"]

== Getting Started

To use the RichFaces framework in your JSF maven application, simply add the following dependency to your `pom.xml` file (Replacing the version `4.5.0-SNAPSHOT` with the version of the library you wish to include):

[source, xml]
----
<dependency>
    <groupId>org.richfaces</groupId>
    <artifactId>richfaces</artifactId>
    <version>4.5.0-SNAPSHOT</version>
</dependency>
----

NOTE: Prior releases of RichFaces required using a BOM to manage the project dependencies.  With RichFaces 4.5 all required dependencies are managed transitively, simplifying your project setup.

Alternatively, if you are not using maven, you can download the project ZIP distribution from the http://www.jboss.org/richfaces/download.html[Download Page] and manually include the dependencies in your classpath.

Once you have included the RichFaces dependency in your application, you can start developing by adding a JSF page which includes the RichFaces taglib references:

[source, xml]
----
<!DOCTYPE html>
<html lang="en"
    xmlns="http://www.w3.org/1999/xhtml"
    ...
    xmlns:rich="http://richfaces.org/rich"
    xmlns:a4j="http://richfaces.org/a4j">

</html>
----

For more information on how to get started with the project, see the http://docs.jboss.org/richfaces/[project documentation].

== Building the Project

=== Clone the Project

    $ git clone git@github.com:richfaces/richfaces.git

=== Prerequsities:

* JDK 1.6 +
* Maven 3.0.4 +
* https://community.jboss.org/wiki/MavenGettingStarted-Developers[JBoss Maven Repository]

=== Build the project

Build the project on the command line:

    $ mvn clean install

Maven will build the project and execute the unit tests, but it won't build the distribution archive nor execute the integration tests.

The freshly built RichFaces artifacts will now be available in your local maven repo, and can be included in your application (using a `-SNAPSHOT` dependency version).

=== Building Project Distribution Archive

If you are not using maven in your application, you can build the complete distribution archive using the command:

    $ mvn clean install -Prelease

The generated ZIP distribution file will be placed in the `dist/target/` folder.  This zip file contains both the required and optional libraries to be included in your RichFaces-based application.

== Contributing to the project

Details on contributing to the project are available in the link:CONTRIBUTING.md[Contributing guide].

=== How to Explore the Sources

All the sources related to RichFaces framework and component library are located in the `core` and `components` folders:

* `src/main/java`
** framework sources
** JSF components under `org.richfaces.components` package
* `src/main/resources/META-INF/resources`
** JavaScript and CSS resources

Examples such as *RichFaces Showcase* and *Components Demo* are stored in the `examples` folder.

=== Developing the Project in an IDE

Once you have <<building-the-project, built the project>> you can import `core`, `components` and one of the `examples` to the IDE.

If you are using Eclipse, you should use `Import Existing Maven Project` option.

=== How to Test the Project

RichFaces has extensive framework test suite which validates compatibility with various browsers and application servers.

For more information on how to run and develop this test suite, see https://github.com/richfaces/richfaces5/blob/master/TESTS.md[Framework Tests] document.

=== Running Smoke Tests

In order to effectively test the project with each code modification, you need to run at least framework's smoke tests:

    $ mvn clean install -Dintegration=wildfly81 -Dsmoke

This will download WildFly and run the project tests against a managed instance of WildFly 8.1 using a headless PhantomJS browser.
For a detailed explanation of additional testing configurations and options, refer to the link:TESTS.md[Testing guide].

These smoke tests are also executed in the https://travis-ci.org/richfaces/richfaces/builds[continuous integration job].

