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

          <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="SimpleJSFapplicationwithRichFaces">
                    <?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="AddingRichFaceslibrariesintotheproject">
                              <title>Adding RichFaces libraries into the project</title>
                              <para>Go 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 &quot;jars&quot; from
                                        <code>lib</code> folder to <code>WEB-INF/lib</code> folder
                                        of "Greeter" JSF application. </para>
                                        
                                        <important>
                                        	<title>Important:</title>
                                        	<para>
                                        		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.
                                        		
                                        	</para>
                                        </important>
                    </section>

                    <section id="RegisteringRichFacesinwebxml">
                              <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[...
<!-- 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>
...]]></programlisting>
                          <para>For more information on how to work with RichFaces skins read &quot;<link linkend="Skinnability">Skinnabilty</link>&quot; chapter.</para>
                              <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>

<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>]]></programlisting>
                    </section>

                    <section id="Managedbean">
                              <title>Managed bean</title>
                              <para>The &quot;RichFaces Greeter&quot; 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="Registeringbeaninfacescofig">
                              <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="RichFacesGreeterindex">
                              <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>
                  <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>]]></programlisting>
                              <para>The application uses three RichFaces components: 
                                    <emphasis role="bold"><property>&lt;rich:panel&gt;</property></emphasis> is used as visual container for information; 
                                    <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. Point your browser 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/GettingStarted_RFGreeterApp.png"
                                                  />
                                                  </imageobject>
                                        </mediaobject>
                              </figure>
                    </section>
          </section>
      
<!-- RELEVANT RESOURCES LINKS -->
      
      <section id="RelevantResourcesLinks">
            <title>Relevant Resources Links</title>
            <para><ulink url="https://www.redhat.com/apps/store/developers/jboss_developer_studio.html">JBoss Developer Studio</ulink> comes with a tight integration with RichFaces component framework. 
            Following links might be useful for those who already use this IDE and RichFaces for developing applications and those who wish to improve their development process:</para>
            <itemizedlist>
                  <listitem>
                     
                        <para>&quot;<ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/GettingStartedGuide/html/first_seam.html#rich_components">Rich Components</ulink>&quot; chapter 
                        in &quot;Getting Started with JBoss Developer Studio Guide&quot; describes how to add RichFaces components into a CRUD application;
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                        &quot;<ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/jsf/html/palette.html">JBoss Tools Palette</ulink>&quot; chapter in  &quot;Visual Web Tools Reference Guide&quot; 
                        describes advantages that gives Tools Pallete (comes together with JBDS) for quick and easy pages creation processs including RichFaces applications;
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                        &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 
                        demonstrates some aspects of interaction with JBoss Developer Studio while working with RichFaces.
                        </para>
                  </listitem>
            </itemizedlist>
            <para>Read also the <ulink url="http://mkblog.exadel.com/?p=110">quick overview</ulink> to "Practical RichFaces " book by Max Katz at his blog.</para>
      </section>
            
</chapter>
