<?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>
          <para>This chapter describes all necessary actions and configurations that should be done
                    for plugging the RichFaces components into a JSF appplication. The description
                    relies on a simple JSF with RichFaces application creation process from
                    downloading the libraries to running the application in a browser. The process
                    of application creation described here is common and does not depend on used
                    IDE. </para>
          <para>See &quot;<ulink
                              url="http://docs.jboss.org/tools/movies/demos/rich_faces_demo/rich_faces_demo.htm"
                              > RichFaces Toolkit for developing Web application</ulink>&quot;
                    video tutorial for benefits that gives the JBoss Developer Studio for developing
                    applications using RichFaces. </para>
          

          <section id="DownloadingRichFaces">
                    <?dbhtml filename="DownloadingRichFaces.html" ?>
                    <title>Downloading the RichFaces</title>
                    <para>The latest release of RichFaces components is available for download at
                                        <ulink url="http://labs.jboss.com/jbossrichfaces/downloads"
                                        >JBoss RichFaces Downloads area</ulink> at JBoss community.
                              Binary files (uploaded there in <code>*.bin.zip</code> or
                                        <code>*.bin.tar.gz</code> archives) contains compiled,
                              ready-to-use version of RichFaces with set of basic skins. 
							  </para>
							  <para>To start with RichFaces in computer file system create new folder with
                              name "RichFaces", download and unzip the archive with binaries there.
							  </para>
							  <para>For those who want to download and compile the RichFaces by themselfs there is an article 
					at JBoss community that describes the 
					<ulink url="http://www.jboss.org/community/docs/DOC-11864">RichFaces repository's structure overview</ulink> and 
					some aspects of working with it.
					</para>
          </section>

          <section id="Simple JSF application with RichFaces">
                    <?dbhtml filename="Installation.html" ?>
                    <title>Simple JSF application with RichFaces</title>
                    <para> "RichFaces Greeter"—the simple application—is hello-world like
                              application but with one difference: the world of RichFaces will say
                              "Hello!" to user first. 
                    </para>
                    <para> Create standard JSF 1.2 project with all necessary libraries; name the project
                    "Greeter" and follow the decription. </para>
                    
                    <section id="Adding RichFaces libraries into the project">
                              <title>Adding RichFaces libraries into the project</title>
                              <para>Pass to the folder with unzipped earlier RichFaces binary files
                                        and open <code>lib</code> folder. This folder contains three
                                                  <code>*.jar</code> files with API, UI and
                                        implementation libraries. Copy that "jars" from
                                        <code>lib</code> folder to <code>WEB-INF/lib</code> folder
                                        of "Greeter" JSF application. </para>
                    </section>

                    <section id="Registering RichFaces in web.xml">
                              <title>Registering RichFaces in web.xml</title>
                              <para> After RichFaces libraries where added into the project it is
                                        necessary to register them in project <code>web.xml</code>
                                        file. Add following lines in <code>web.xml</code>: </para>
                              <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>
                              <para>Finally the <code>web.xml</code> should look like this: </para>
                              <programlisting role="XML"><![CDATA[<?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>
 
<!-- RichFaces Filter -->
<filter> 
   <display-name>RichFaces Filter</display-name> 
   <filter-name>richfaces</filter-name> 
   <filter-class>org.ajax4jsf.Filter</filter-class> 
</filter> 

<!-- RichFaces Filter mapping-->
<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>
                    </section>

                    <section id="Managed bean">
                              <title>Managed bean</title>
                              <para>The "RichFaces Greeter" application needs a managed bean. In
                                        project <code>JavaSource</code> folder create a new managed
                                        bean with name <code>user</code> in <code>demo</code>
                                        package and paste there the following simple code: </para>
                              <programlisting role="JAVA">package demo;

public class user {
   private String name="";
   public String getName() {
      return name;
   }
   public void setName(String name) {
      this.name = name;
   }
}</programlisting>
                    </section>

                    <section id="Registering bean in faces-cofig.xml">
                              <title>Registering bean in faces-cofig.xml</title>
                              <para>With the next step the <code>user</code> bean should be
                                        registered in <code>faces-config.xml</code> file: </para>
                              <programlisting role="XML"><![CDATA[<?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>
]]></programlisting>
                    </section>

                    <section id="RichFaces Greeter index.jsp">
                              <title>RichFaces Greeter index.jsp</title>
                              <para> The "RichFaces Greeter" application has only one JSP page.
                                        Create <code>index.jsp</code> page in root of <code>WEB
                                                  CONTENT</code> folder and add there following
                                        code: </para>
                              <programlisting role="XML"><![CDATA[<!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>
         <h1>RichFaces Greeter</h1>
         <a4j:form>
            <h:panelGroup style="margin-left: 10" >
               <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>
         </a4j:form>
         <h:panelGroup id="greeting" >
            <h:outputText value="Hello, " rendered="#{not empty user.name}" style="margin-left: 10" />
            <h:outputText value="#{user.name}" />
            <h:outputText value="!" rendered="#{not empty user.name}" />
         </h:panelGroup>
      </f:view>
   </body>
</html>]]></programlisting>
                              <para>The application uses two RichFaces components: <emphasis
                                                  role="bold">
                                                  <property>&lt;a4j:commandButton&gt;</property>
                                        </emphasis> with built-in Ajax support allows rendering a
                                        greeting dynamically after a response comes back and
                                                  <emphasis role="bold">
                                                  <property>&lt;a4j:form&gt;</property>
                                        </emphasis> helps the button to perform the action. </para>
                              <para>Note, that the RichFaces tag library should be declared on each
                                        JSP page. For XHTML pages add following lines for tag
                                        library declaration: </para>
                              <programlisting role="XML"><![CDATA[<xmlns:a4j="http://richfaces.org/a4j">
<xmlns:rich="http://richfaces.org/rich">]]></programlisting>
                              <para>That’s it. Run the application on server. Write the full pass to
                                                  <code>index.jsp</code> page in browser:
                                                  <code>http://localhost:8080/Greeter/index.jsf</code>
                              </para>
                              <figure>
                                        <title>"RichFaces Greeter" application</title>
                                        <mediaobject>
                                                  <imageobject>
                                                  <imagedata
                                                  fileref="images/RichFaces Greeter.png"
                                                  />
                                                  </imageobject>
                                        </mediaobject>
                              </figure>
                    </section>
          </section>
</chapter>
