<?xml version='1.0' encoding='UTF-8'?>
<chapter id="GettingStarted" xreflabel="GettingStarted">
  <?dbhtml filename="GettingStarted.html"?>
  <chapterinfo>
    <keywordset>
      <keyword>MyFaces</keyword>

      <keyword>JSF</keyword>

      <keyword>RichFaces</keyword>

    </keywordset>
  </chapterinfo>
  <title>Getting Started with RichFaces</title>
  <section id="DownloadingRichFaces">
    <?dbhtml filename="DownloadingRichFaces.html" ?>
    <title>Downloading RichFaces 3.2.0</title>
    <para>The latest release of <property>RichFaces</property> is available for download at:<simplelist>
        <member>
          <ulink url="http://labs.jboss.com/jbossrichfaces/downloads"
            >http://labs.jboss.com/jbossrichfaces/downloads</ulink>
        </member>
      </simplelist> in the <property>RichFaces</property> project area under JBoss.</para>
  </section>
  <section id="Installation">
    <?dbhtml filename="Installation.html" ?>
    <title>Installation</title>
    <itemizedlist>
      <listitem> Unzip <emphasis>
          <property>&quot;richfaces-ui-3.2.0-bin.zip&quot;</property>
        </emphasis> file to the chosen folder. </listitem>
      <listitem> Copy <emphasis>
          <property>&quot;richfaces-api-3.2.0.jar&quot;</property>
        </emphasis>, <emphasis>
          <property>&quot;richfaces-impl-3.2.0.jar&quot;</property>
        </emphasis>,<emphasis>
          <property>&quot;richfaces-ui-3.2.0.jar&quot;</property>
        </emphasis>files into the <emphasis>
          <property>&quot;WEB-INF/lib&quot;</property>
        </emphasis> folder of your application. </listitem>
      <!--note>
        <title>Note:</title>
        <para>Starting from Ajax4jsf 1.1.1, the oscache library is not required to be in the
          classpath anymore. </para>
      </note-->
      <listitem> Add the following content into the <emphasis>
          <property>&quot;WEB-INF/web.xml&quot;</property>
        </emphasis> file of your application: <programlisting role="XML"><![CDATA[...
    <context-param>
        <param-name>org.richfaces.SKIN</param-name>
        <param-value>blueSky</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>]]></programlisting>
        <!--note>
          <title>Note:</title>
          <para>You can copy and paste the above text from the <emphasis>
              <property>&quot;README.txt&quot;</property>
            </emphasis> file.</para>
        </note-->
      </listitem>

      <listitem>

        <para>Add the following lines for each JSP page of your application.</para>
        <programlisting role="XML"><![CDATA[<%@ taglib uri="http://richfaces.org/a4j" prefix="a4j"%>
<%@ taglib uri="http://richfaces.org/rich" prefix="rich"%> ]]></programlisting>
        <para>For XHTML pages:</para>
        <programlisting role="XML"><![CDATA[<xmlns:a4j="http://richfaces.org/a4j">
<xmlns:rich="http://richfaces.org/rich">]]></programlisting>
      </listitem>
    </itemizedlist>
    <note>
      <title>Note:</title>
      <para>The previous namespaces URIs (https://ajax4jsf.dev.java.net/ajax and
        http://richfaces.ajax4jsf.org/rich) are also available for backward compatibility.</para>
    </note>
  </section>
  <section id="SimpleAJAXEchoProject">
    <?dbhtml filename="SimpleAJAXEchoProject.html" ?>
    <title>Simple Ajax Echo Project </title>
    <para> In our JSF project you need only one JSP page that has a form with a couple of child
      tags: <emphasis role="bold">
        <property>&lt;h:inputText&gt;</property>
      </emphasis> and <emphasis role="bold">
        <property>&lt;h:outputText&gt;</property>
      </emphasis>. </para>
    <para>This simple application let you input some text into the <emphasis role="bold">
        <property>&lt;h:inputText&gt;</property>
      </emphasis>, send data to the server, and see the server response as a value of <emphasis
        role="bold">
        <property>&lt;h:outputText&gt;</property>
      </emphasis>. </para>
    <section id="JSPPage">
      <?dbhtml filename="JSPPage.html"?>
      <title>JSP Page</title>
      <para>Here is the necessary page (echo.jsp):</para>
 	  <programlisting role="XML"><![CDATA[
    <%@ taglib uri="http://richfaces.org/a4j" prefix="a4j"%>
    <%@ taglib uri="http://richfaces.org/rich" prefix="rich"%>
    <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
    <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
    <html>
      <head>
        <title>repeater </title> 
      </head>
      <body>
        <f:view>
          <h:form>
              <rich:panel header="Simple Echo">
                <h:inputText size="50" value="#{bean.text}" > 
                  <a4j:support event="onkeyup" reRender="rep"/>
                </h:inputText>
                <h:outputText value="#{bean.text}" id="rep"/>
              </rich:panel>
          </h:form>
        </f:view>
      </body>
    </html>]]></programlisting>

      <para>Only two tags distinguish this page from a &quot;regular&quot; JSF
        one. There are <emphasis role="bold">
          <property>&lt;rich:panel&gt;</property>
        </emphasis> and <emphasis role="bold">
          <property>&lt;a4j:support&gt;</property>
        </emphasis>.</para>

      <para>The <emphasis role="bold">
          <property>&lt;rich:panel&gt;</property>
      </emphasis>allows to place the page elements in rectangle panel that can be skinned.</para>

      <para>The <emphasis role="bold">
          <property>&lt;a4j:support&gt;</property>
        </emphasis> with corresponding attributes (as it was shown in the previous example) adds an
        Ajax support to the parent <emphasis role="bold">
          <property>&lt;h:inputText&gt;</property>
        </emphasis> tag. This support is bound to &quot;onkeyup&quot; JavaScript event, so
        that each time when this event is fired on the parent tag, our application sends an Ajax
        request to the server. It means that the text field pointed to our managed bean property
        contains up-to-date value of our input. </para>
      <para> The value of <emphasis>
          <property>&quot;reRender&quot;</property>
        </emphasis> attribute of the <emphasis role="bold">
          <property>&lt;a4j:support&gt;</property>
        </emphasis> tag defines which part(s) of our page is (are) to be updated. In this case, the
        only part of the page to update is the <emphasis role="bold">
          <property>&lt;h:outputText&gt;</property>
        </emphasis> tag because its ID value matches to the value of <emphasis>
          <property>&quot;reRender&quot;</property>
        </emphasis> attribute. As you see, it&apos;s not difficult to update multiple elements
        on the page, only list their IDs as the value of <emphasis>
          <property>&quot;reRender&quot;</property>
        </emphasis>. </para>
    </section>
    <section id="DataBean">
      <?dbhtml filename="DataBean.html"?>
      <title>Data Bean</title>
      <para>In order to build this application, you should create a managed bean:</para>
      <programlisting role="JAVA">package demo;
        
        public class Bean {
        private String text;
        public Bean() {
        }
        public String getText() {
        return text;
        }
        public void setText(String text) {
        this.text = text;
        }
        }</programlisting>
    </section>
    <section id="faces-config.xml">
      <?dbhtml filename="faces-config.xml.html"?>
      <title>faces-config.xml</title>
      <para>Next, it&apos;s necessary to register your bean inside of the faces-config.xml file:</para>
      <programlisting role="XML">    <![CDATA[<?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD  JavaServer Faces Config 1.1//EN"
    "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
    <faces-config>
      <managed-bean>
        <managed-bean-name>bean</managed-bean-name>
        <managed-bean-class>demo.Bean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
        <managed-property>
          <property-name>text</property-name>
          <value/>
        </managed-property>
      </managed-bean>
    </faces-config>]]></programlisting>
      <para>
        <note>
          <title>Note:</title>
          <para>Nothing that relates directly to RichFaces is required in the configuration
          file.</para>
        </note>
      </para>
    </section>
    <section id="Web.xml">
      <?dbhtml filename="Web.xml.html"?>
      <title>Web.xml</title>
      <para>It is also necessary to add jar files (see <link linkend="Installation">installation
          chapter</link>) and modify the &quot;web.xml&quot; file: </para>
      <programlisting role="XML">    <![CDATA[<?xml version="1.0"?>
    <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee  http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
    <display-name>a4jEchoText</display-name>
    <context-param>
        <param-name>org.richfaces.SKIN</param-name>
        <param-value>blueSky</param-value>
    </context-param>
    <context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>server</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>]]></programlisting>
      <para>Now your application should work.</para>
    </section>
    <section id="Deployment">
      <?dbhtml filename="Deployment.html"?>
      <title>Deployment</title>
      <para>Finally, you should be able to place this application on your Web server.To start your
        project, point your browser at <ulink url="http://localhost:8080/a4jEchoText/echo.jsf"
          >http://localhost:8080/a4jEchoText/echo.jsf</ulink>
      </para>
    </section>
  </section>
</chapter>
