Rich Client Faces - Getting Started

Getting Started

Download

The latest release is available at http://sourceforge.net/projects/rcfaces/files/.

The rcfaces-1.2.0.RELEASE archive file contains the following directories:

docs :
- apidocs : javadoc of rcfaces.core
- jsdocs : javascript doc of rcfaces.html
- tlddocs : tag lib definition doc of rcfaces.core
- userguide : user guide for developers

lib : The RCfaces libs (for development and runtime)

lib_optimized : The RCfaces libs(for javascript runtime perfomances optimizing)

lib_required : The required apache-commons libraries.

NB:

JSF RI 1.2

JSTL

projects : contains projects examples
- AdressBook : A complete project using many components. Preview here
- Form sample : A little project introducing RC Faces. Preview here
These Projects can be imported into eclipse as WTP projects. Right click/import/WEB>WAR File.

src: The RCfaces source libraries

For integration build:

You must download one of the core JAR file (e.g. rcfaces-core-jsf1_2-I2554.jar ) and the corresponding html jar (e.g. rcfaces-html-jsf1_2-I2554.jar). Both jars are required.

You will also find the source code for each implementation (e.g. rcfaces-core-src-jsf1_2-I2554.jar and rcfaces-html-src-JSF1_2-I2554.jar), and documentation for java source code, Javascript and TLD (rcfaces-javadoc-JSF1_2-I2554.jar., rcfaces-jsdoc-JSF1_2-I2554.jar and rcfaces-tlddoc-JSF1_2-I2554.jar).

The rcfaces-imageIO-*.jar is used by RCFaces to generate on the fly multiple versions of an image (hover, disabled, scaled, ...).

Your first RCFaces application

The goal of this tutorial is to create a simple form and add results in a grid. This way you will have a quick overview of RC Faces.
This project was built with Eclipse Galileo and Apache Tomcat 6. The Eclipse workspace is available for download at http://linktothefile/.

Create project and add libraries

First create JSF 1.2 (Sun RI) project named "RCFacesFormSample". Add all necessary libraries in folder WEB-INF/lib :

commons-beanutils.jar
commons-digester.jar
commons-logging.jar
jstl.jar

And in same folder, the RC Faces libraries :

rcfaces-core-jsf1_2.jar
rcfaces-html-jsf1_2.jar

Add RC Faces resources Servlet in web.xml file

Declare the RC Faces resources Servlet. This servlet load resources used by each RC faces component: JavaScript, css and images.

Add the following lines in web.xml :

<servlet-name>Rcfaces resources Servlet</servlet-name>

<servlet-class>org.rcfaces.renderkit.html.internal.resource.ResourcesServlet</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>Rcfaces resources Servlet</servlet-name>

<url-pattern>/rc-fwk/*</url-pattern>

</servlet-mapping>

That is the minimum required in the web.xml file. RC Faces has many other parameters to improve its performance. For further configuration, read part 6: Settings.

Final version of web.xml :

<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

id="WebApp_ID" version="2.5">

<display-name>RCFacesFormSample</display-name>

<welcome-file-list>

<welcome-file>index.jsp</welcome-file>

</welcome-file-list>

<context-param>

<param-name>javax.faces.STATE_SAVING_METHOD</param-name>

<param-value>server</param-value>

</context-param>

<context-param>

<param-name>javax.servlet.jsp.jstl.fmt.localizationContext</param-name>

<param-value>resources.application</param-value>

</context-param>

<listener-class>com.sun.faces.config.ConfigureListener</listener-class>

</listener>

<servlet-name>Faces Servlet</servlet-name>

<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-name>Rcfaces resources Servlet</servlet-name>

<servlet-class>org.rcfaces.renderkit.html.internal.resource.ResourcesServlet</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>Faces Servlet</servlet-name>

<url-pattern>*.jsf</url-pattern>

</servlet-mapping>

<servlet-mapping>

<servlet-name>Rcfaces resources Servlet</servlet-name>

<url-pattern>/rc-fwk/*</url-pattern>

</servlet-mapping>

</web-app>

Create a managed bean

We want to add data from a form into a data grid, so we need to build a JSF managed bean to get fields value and put them in the table's model. The best solution would be to do two managed beans; however for this simple demo only one is necessary.

Create a java object named GridBean in the org.rcfaces.rcfacesformsample.managed package :

package org.rcfaces.rcfacesformsample.managed;

import java.text.DateFormat;

import java.text.ParseException;

import java.text.SimpleDateFormat;

import java.util.ArrayList;

import java.util.Date;

import java.util.List;

import org.rcfaces.core.event.SelectionEvent;

public class GridBean {

private static final DateFormat dateFormat = new SimpleDateFormat(

"dd/MM/yyyy");

private List<Row> rows; // Data model of dataGrid

private Row newRow; // Use by the form field

public GridBean() {

rows = new ArrayList<Row>();

rows.add(new Row("Didier", "La Rochelle", "1/1/1882"));

rows.add(new Row("Fred", "La Rochelle", "02/02/1901"));

rows.add(new Row("Olivier", "La Rochelle", "11/4/1975"));

rows.add(new Row("Christine", "La Rochelle", "4/12/1980"));

rows.add(new Row("Jean-Marc", "La Rochelle", "4/12/1980"));

rows.add(new Row("JB", "La Rochelle", "1/8/2000"));

}

// called by the actionListner of submit button

public void addRow(SelectionEvent event) {

rows.add(new Row(newRow.getName(), newRow.getCity(), newRow

.getBirthDate()));

newRow = null;

}

public List<Row> getRows() {

return rows;

}

public void setRows(List<Row> rows) {

this.rows = rows;

}

public Row getNewRow() {

if (newRow == null) {

newRow = new Row();

}

return newRow;

}

public void setNewRow(Row newRow) {

this.newRow = newRow;

}

public class Row {

private String name;

private String city;

private Date birthDate;

public Row() {

}

public Row(String name, String city, String birthDate) {

this.name = name;

this.city = city;

try {

this.birthDate = dateFormat.parse(birthDate);

} catch (ParseException ex) {

throw new IllegalArgumentException(ex);

}

public Row(String name, String city, Date birthDate) {

this.name = name;

this.city = city;

this.birthDate = birthDate;

}

public String getName() {

return name;

}

public void setName(String name) {

this.name = name;

}

public String getCity() {

return city;

}

public void setCity(String city) {

this.city = city;

}

public Date getBirthDate() {

return birthDate;

}

public void setBirthDate(Date birthDate) {

this.birthDate = birthDate;

}

A JSF managed bean must be registered in the faces-config.xml file :

<managed-bean>

<managed-bean-name>gridBean</managed-bean-name>

<managed-bean-class>org.rcfaces.rcfacesformsample.managed.GridBean</managed-bean-class>

<managed-bean-scope>session</managed-bean-scope>

</managed-bean>

Create a JSP

In web.xml file, we mapped the Faces Servlet with the url pattern like "*.jsf", therefore the welcome file index.jsp must do a forward to a *.jsf page to enter in the JSF context :

<?xml version="1.0" encoding="UTF-8"?>

<jsp:root version="2.0" xmlns="http://www.w3.org/1999/xhtml"

xmlns:jsp="http://java.sun.com/JSP/Page">

<jsp:forward page="form.jsf"/>

</jsp:root>

form.jsp source code :

<?xml version="1.0" encoding="UTF-8"?>

<jsp:root version="2.0" xmlns="http://www.w3.org/1999/xhtml"

xmlns:jsp="http://java.sun.com/JSP/Page"

xmlns:f="http://java.sun.com/jsf/core"

xmlns:h="http://java.sun.com/jsf/html"

xmlns:v="http://rcfaces.org/core" xmlns:vh="http://rcfaces.org/html">

<jsp:directive.page contentType="text/html" pageEncoding="UTF-8" />

<jsp:output omit-xml-declaration="true" doctype-root-element="html"

doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"

doctype-system="http://www.w3.org/TR/html4/loose.dtd" />

<f:view>

<html>

<head>

<vh:init />

</head>

<vh:javaScriptCollector>

<body>

<h:form>

<v:fieldSet text="Form">

What is your name :

<v:message for="field1" showDetail="false" showSummary="true"

showIfMessage="true" />

<v:textEntry id="field1" columnNumber="30"

value="#{gridBean.newRow.name}" required="true" />

</div>

Where do you come from :

<v:message for="field2" showDetail="false" showSummary="true"

showIfMessage="true" />

<v:textEntry id="field2" columnNumber="30"

value="#{gridBean.newRow.city}" required="true"

emptyMessage="your city" />

</div>

When were you born :

<v:message for="fieldDate" showDetail="false" showSummary="true"

showIfMessage="true" />

<v:dateEntry id="fieldDate" value="#{gridBean.newRow.birthDate}"

required="true" />

<v:dateChooser id="date" for="fieldDate" />

</div>

<v:submitButton text="submit" actionListener="#{gridBean.addRow}" />

</v:fieldSet>

<v:dataGrid id="tableId"

width="450" value="#{gridBean.rows}" var="row" rows="3">

<v:dataColumn text="Name" sortListener="alpha" value="#{row.name}" />

<v:dataColumn text="city" sortListener="alpha" value="#{row.city}" />

<v:dataColumn text="BirthDate" value="#{row.birthDate}"

alignment="center" />

</v:dataGrid>

<v:pager for="tableId"></v:pager>

</div>

</h:form>

</body>

</vh:javaScriptCollector>

</html>

</f:view>

</jsp:root>

In the header element of this page there is a tag <vh: init /> without this tag RC-Faces won't work so don't forget it. If your application uses template like Tiles or Facelet this tag can be placed in the header of the main page.

Note this sample is done without additional css styles. All components will have the default RC Faces look and feel. To customize the look and feel see part Override renderer, javaScript or css.

Run the RCFacesFormSample web project as server application and point your browser to this URL : http://localhost:8080/RCFacesFormSample/

You should see :

RCFaces

RCFaces Demo

Components

Project Documentation

Project API Documentation

Getting Started

Download

Your first RCFaces application

Create project and add libraries

Add RC Faces resources Servlet in web.xml file

Create a managed bean

Create a JSP