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 and JSTL are also required for RC Faces.

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

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

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

      </listener>

 

      <servlet>

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

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

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

      </servlet>

     

      <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 /> <!-- !important tag  -->

      </head>

      <vh:javaScriptCollector>

            <body>

            <h:form>

 

                  <v:fieldSet text="Form">

                        <!-- container  -->

 

                  <div style="margin-top: 10px;">

               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>

 

                  <div style="margin-top: 10px;">

                      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>

 

                  <div style="margin: 10px 0;">

                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>

 

                  <div style="margin-top: 10px;">

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