Chapter 2. Getting Started with RichFaces
This chapter tells you how to plug RichFaces components into a JSF application. The instructions are based on a simple JSF with RichFaces creation process, from downloading the required libraries to running the application in a browser. These instructions do not depend on the integrated development environment that is in use.
2.1. Simple JSF application with RichFaces
RichFaces Greeter — the simple application — is similar to a typical hello world application, with one exception: the world of RichFaces will say "Hello!" to the user first.
Create a standard JSF 1.2 project named
Greeter
. Include all required libraries, and continue with the instructions that follow.
2.1.1. Adding RichFaces libraries into the project
From the
RichFaces
folder where you unzipped the RichFaces binary files, open the lib
. This folder contains three *.jar
files with API, UI, and implementation libraries. Copy these JARs from lib
to the WEB-INF/lib
directory of your Greeter JSF application.
Important
A JSF application with RichFaces assumes that the following JARs are available in the project:
commons-beanutils-1.7.0.jar
commons-collections-3.2.jar
commons-digester-1.8.jar
commons-logging-1.0.4.jar
jhighlight-1.0.jar
2.1.2. Registering RichFaces in web.xml
After you add the RichFaces libraries to the project, you must register them in the project
web.xml
file. Add the following to web.xml
:
... <!-- Plugging the "Blue Sky" skin into the project --> <context-param> <param-name>org.richfaces.SKIN</param-name> <param-value>blueSky</param-value> </context-param> <!-- Making the RichFaces skin spread to standard HTML controls --> <context-param> <param-name>org.richfaces.CONTROL_SKINNING</param-name> <param-value>enable</param-value> </context-param> <!-- Defining and mapping the RichFaces filter --> <filter> <display-name>RichFaces Filter</display-name> <filter-name>richfaces</filter-name> <filter-class>org.ajax4jsf.Filter</filter-class> </filter> <filter-mapping> <filter-name>richfaces</filter-name> <servlet-name>Faces Servlet</servlet-name> <dispatcher>REQUEST</dispatcher> <dispatcher>FORWARD</dispatcher> <dispatcher>INCLUDE</dispatcher> </filter-mapping> ...
For more information about RichFaces skins, read Section 4.4, “Skinnability”.
Finally, your
web.xml
should look like this:
<?xml version="1.0"?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <display-name>Greeter</display-name> <context-param> <param-name>javax.faces.STATE_SAVING_METHOD</param-name> <param-value>server</param-value> </context-param> <context-param> <param-name>org.richfaces.SKIN</param-name> <param-value>blueSky</param-value> </context-param> <context-param> <param-name>org.richfaces.CONTROL_SKINNING</param-name> <param-value>enable</param-value> </context-param> <filter> <display-name>RichFaces Filter</display-name> <filter-name>richfaces</filter-name> <filter-class>org.ajax4jsf.Filter</filter-class> </filter> <filter-mapping> <filter-name>richfaces</filter-name> <servlet-name>Faces Servlet</servlet-name> <dispatcher>REQUEST</dispatcher> <dispatcher>FORWARD</dispatcher> <dispatcher>INCLUDE</dispatcher> </filter-mapping> <listener> <listener-class>com.sun.faces.config.ConfigureListener</listener-class> </listener> <!-- Faces Servlet --> <servlet> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <!-- Faces Servlet Mapping --> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.jsf</url-pattern> </servlet-mapping> <login-config> <auth-method>BASIC</auth-method> </login-config> </web-app>
2.1.3. Managed bean
The RichFaces Greeter application needs a managed bean. In the project's
JavaSource
directory, create a new managed bean named user
in the demo
package. Place the following code in user
:
package demo; public class user { private String name=""; public String getName() { return name; } public void setName(String name) { this.name = name; } }
2.1.4. Registering the bean in faces-config.xml
To register the
user
bean, add the following to the faces-config.xml
file:
<?xml version="1.0" encoding="UTF-8"?> <faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"> <managed-bean> <description>UsernName Bean</description> <managed-bean-name>user</managed-bean-name> <managed-bean-class>demo.user</managed-bean-class> <managed-bean-scope>request</managed-bean-scope> <managed-property> <property-name>name</property-name> <property-class>java.lang.String</property-class> <value/> </managed-property> </managed-bean> </faces-config>
2.1.5. RichFaces Greeter index.jsp
RichFaces Greeter has only one JSP page. Create
index.jsp
in the root of WEB CONTENT
folder and add the following to the JSP file:
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <!-- RichFaces tag library declaration --> <%@ taglib uri="http://richfaces.org/a4j" prefix="a4j"%> <%@ taglib uri="http://richfaces.org/rich" prefix="rich"%> <html> <head> <title>RichFaces Greeter</title> </head> <body> <f:view> <a4j:form> <rich:panel header="RichFaces Greeter" style="width: 315px"> <h:outputText value="Your name: " /> <h:inputText value="#{user.name}" > <f:validateLength minimum="1" maximum="30" /> </h:inputText> <a4j:commandButton value="Get greeting" reRender="greeting" /> <h:panelGroup id="greeting" > <h:outputText value="Hello, " rendered="#{not empty user.name}" /> <h:outputText value="#{user.name}" /> <h:outputText value="!" rendered="#{not empty user.name}" /> </h:panelGroup> </rich:panel> </a4j:form> </f:view> </body> </html>
The application uses three RichFaces components: <rich:panel> is used as visual container for information; <a4j:commandButton> with built-in AJAX support lets a greeting be rendered dynamically after a response returns; and <a4j:form> helps the button to perform the action.
Note
The RichFaces tag library should be declared on each JSP page. For XHTML pages, add the following lines to declare your tag libraries:
<xmlns:a4j="http://richfaces.org/a4j"> <xmlns:rich="http://richfaces.org/rich">
Now, run the application on the server by pointing your browser to the
index.jsp
page: http://localhost:8080/Greeter/index.jsf
Figure 2.1. "RichFaces Greeter" application