Author: SeanRogers Date: 2010-02-01 01:44:17 -0500 (Mon, 01 Feb 2010) New Revision: 16384 Added: root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Request_processing_flow.png root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Request_processing_sequences.png root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Resource_request_sequence.png Modified: root/docs/trunk/Developer_Guide/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml root/docs/trunk/Developer_Guide/en-US/chap-Developer_Guide-RichFaces_overview.xml Log: Worked on RichFaces Overview and Getting Started Modified: root/docs/trunk/Developer_Guide/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml =================================================================== --- root/docs/trunk/Developer_Guide/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml 2010-01-31 23:27:26 UTC (rev 16383) +++ root/docs/trunk/Developer_Guide/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml 2010-02-01 06:44:17 UTC (rev 16384) @@ -7,34 +7,289 @@ <chapter id="chap-Developer_Guide-Getting_started_with_RichFaces"> <title>Getting started with RichFaces</title> <para> - Incomplete + Follow the instructions in this chapter to install and configure RichFaces for development. If you have existing projects that use an previous version of RichFaces, refer to the <citetitle>RichFaces 4.0 Migration Guide</citetitle>. </para> <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Technical_Requirements"> <title>Technical Requirements</title> <para> - Incomplete + RichFaces has been developed with an open architecture to be compatible with a wide variety of environments. In addition to the RichFaces framework, you need the following frameworks, environments, and applications installed on your computer to start developing with RichFaces: + <variablelist> + <varlistentry> + <term>Java Development Kit (<acronym>JDK</acronym>)</term> + <listitem> + <para> + RichFaces supports the following JDK versions: + <itemizedlist> + <listitem> + <para> + JDK 1.5 and higher + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>JavaServer Faces (<acronym>JSF</acronym>)</term> + <listitem> + <para> + RichFaces supports the following JSF implementations and frameworks: + <itemizedlist> + <listitem> + <para> + Facelets 1.1.1 &ndash; 1.2 + </para> + </listitem> + <listitem> + <para> + MyFaces 1.2.5 + </para> + </listitem> + <listitem> + <para> + Seam 1.2 &ndash; 2.1 + </para> + </listitem> + <listitem> + <para> + Sun JSF-RI 1.2_12 + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A Java application server or servlet container</term> + <listitem> + <para> + RichFaces supports the following servers: + <itemizedlist> + <listitem> + <para> + Apache Tomcat 5.5 &ndash; 6.0 + </para> + </listitem> + <listitem> + <para> + BEA WebLogic 9.1 &ndash; 10.0 + </para> + </listitem> + <listitem> + <para> + JBoss 4.2 &ndash; 5.0 + </para> + </listitem> + <listitem> + <para> + Jetty 6.1 + </para> + </listitem> + <listitem> + <para> + Geronimo 2.0 and higher + </para> + </listitem> + <listitem> + <para> + Glassfish (J2EE 5) + </para> + </listitem> + <listitem> + <para> + Resin 3.1 + </para> + </listitem> + <listitem> + <para> + Sun Application Server 9 (J2EE 1.5) + </para> + </listitem> + <listitem> + <para> + Websphere 7.0 and higher + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A web browser</term> + <listitem> + <para> + RichFaces supports the following web browsers: + <itemizedlist> + <title>Linux environments</title> + <listitem> + <para> + Firefox 3.0 and higher + </para> + </listitem> + <listitem> + <para> + Google Chrome + </para> + </listitem> + <listitem> + <para> + Opera 8.5 and higher + </para> + </listitem> + </itemizedlist> + <itemizedlist> + <title>Mac OS environments</title> + <listitem> + <para> + Firefox 3.5 and higher + </para> + </listitem> + <listitem> + <para> + Google Chrome + </para> + </listitem> + <listitem> + <para> + Safari 3.0 and higher + </para> + </listitem> + </itemizedlist> + <itemizedlist> + <title>Microsoft Windows environments</title> + <listitem> + <para> + Firefox 3.0 and higher + </para> + </listitem> + <listitem> + <para> + Google Chrome + </para> + </listitem> + <listitem> + <para> + Internet Explorer 6.0 and higher + </para> + </listitem> + <listitem> + <para> + Opera 8.5 and higher + </para> + </listitem> + <listitem> + <para> + Safari 3.0 and higher + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> </para> </section> <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Installing_RichFaces"> <title>Installing RichFaces</title> <para> - Incomplete + Follow the instructions in this section to install the RichFaces framework on your computer. </para> + <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Downloading_RichFaces"> + <title>Downloading RichFaces</title> + <para> + Download RichFaces from the JBoss RichFaces Downloads area at <ulink url="http://www.jboss.org/richfaces/download.html">http://ww...;. The binary files (available in <filename class="extension">.bin.zip</filename> or <filename class="extension">.bin.tar.gz</filename> archives) contain a compiled, ready-to-use version of RichFaces with a set of basic skins. + </para> + <para> + Create a new directory named <filename>RichFaces</filename>, then unzip the archive containing the binaries there. + </para> + <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Compiling_the_source"> + <title>Compiling the source</title> + <para> + Instead of downloading the pre-compiled binaries, you can download the source files and compile them yourself. Download the source files (also available in <filename class="extension">.bin.zip</filename> or <filename class="extension">.bin.tar.gz</filename> archives) from the JBoss RichFaces Downloads area at <ulink url="http://www.jboss.org/richfaces/download.html">http://ww...;. + </para> + </section> + </section> + </section> - <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Configuration"> - <title>Configuration</title> - <para> - Incomplete - </para> - </section> - <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Creating_a_project"> <title>Creating a project</title> <para> - Incomplete + Follow the procedure in this section to create a new RichFaces application with <application>JBoss Tools</application>. </para> + <procedure> + <step> + <title>Create a new project</title> + <para>In <application>JBoss Tools</application>, select <menuchoice><guimenu>File</guimenu><guimenu>New</guimenu><guimenuitem>JSF Project</guimenuitem></menuchoice></para> from the menu. Name the project, select <guilabel>JSF 2</guilabel> from the <guilabel>JSF Environment</guilabel> drop-down box, and click the <guibutton>Finish</guibutton> button to create the project. + </step> + <step> + <title>Add the RichFaces libraries to the project</title> + <para>Add <filename>core-ui.jar</filename>, <filename>richfaces-api.jar</filename>, and <filename>richfaces-impl.jar</filename> into your project by dragging them from the location where you unzipped the RichFaces archive to the <filename>WebContent/WEB-INF/lib/</filename> directory of your project in <application>JBoss Tools</application>.</para> + <note> + <title>Other required libraries</title> + <para> + RichFaces also requires the following libraries to be referenced in your project. Typically they are already included when creating a JSF project in <application>JBoss Tools</application>. + <itemizedlist> + <listitem> + <para> + <filename>commons-beanutils.jar</filename> + </para> + </listitem> + <listitem> + <para> + <filename>commons-collections.jar</filename> + </para> + </listitem> + <listitem> + <para> + <filename>commons-digester.jar</filename> + </para> + </listitem> + <listitem> + <para> + <filename>commons-logging.jar</filename> + </para> + </listitem> + <listitem> + <para> + <filename>jhighlight.jar</filename> + </para> + </listitem> + </itemizedlist> + </para> + </note> + </step> + <step> + <title>Reference the tag libraries</title> + <para>The RichFaces tag libraries need to be referenced on each JSP and XHTML page in your project.</para> + <variablelist> + <varlistentry> + <term>Referencing in JSP pages</term> + <listitem> +<programlisting language="XML" role="XML">&lt;%@ taglib uri="http://richfaces.org/a4j" prefix="a4j"%&gt; +&lt;%@ taglib uri="http://richfaces.org/rich" prefix="rich"%&gt; +</programlisting> + </listitem> + </varlistentry> + <varlistentry> + <term>Referencing in XHTML pages</term> + <listitem> +<programlisting language="XML" role="XML">&lt;ui:composition xmlns="http://www.w3.org/1999/xhtml" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:a4j="http://richfaces.org/a4j" + xmlns:rich="http://richfaces.org/rich"&gt; + ... +&lt;/ui:composition&gt; +</programlisting> + </listitem> + </varlistentry> + </variablelist> + </step> + </procedure> + <para> + You are now ready to begin building your RichFaces applications. + </para> </section> </chapter> Modified: root/docs/trunk/Developer_Guide/en-US/chap-Developer_Guide-RichFaces_overview.xml =================================================================== --- root/docs/trunk/Developer_Guide/en-US/chap-Developer_Guide-RichFaces_overview.xml 2010-01-31 23:27:26 UTC (rev 16383) +++ root/docs/trunk/Developer_Guide/en-US/chap-Developer_Guide-RichFaces_overview.xml 2010-02-01 06:44:17 UTC (rev 16384) @@ -7,13 +7,125 @@ <chapter id="chap-Developer_Guide-RichFaces_overview"> <title>RichFaces overview</title> <para> - Incomplete + The RichFaces framework is a component library which adds Ajax capability into existing pages, such that you don't need to write any extra JavaScript code or replace any existing components with new Ajax widgets. RichFaces also enables page-wide Ajax support instead of the traditional component-wide support. Events can be defined on pages that invoke Ajax requests. After an Ajax request, the areas of a page that are synchronized with the JSF Component Tree can themselves change data on the server according to events fired on the client. </para> + <para> + <xref linkend="figu-Developer_Guide-RichFaces_overview-Request_processing_flow" /> illustrates how requests are processed in the RichFaces framework. + </para> + <figure id="figu-Developer_Guide-RichFaces_overview-Request_processing_flow"> + <title>Request processing flow</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/figu-Developer_Guide-RichFaces_overview-Request_processing_flow.png" format="PNG" /> + </imageobject> + <textobject> + <para> + The RichFaces request processing flow. + </para> + </textobject> + </mediaobject> + </figure> + <para> + Using JSF tags, RichFaces allows different parts of a JSF page to be updated with an Ajax request. JSF pages using RichFaces do not change from "regular" JSF pages, and additional JavaScript or XMLHTTPRequest objects do not need to be written. + </para> <section id="sect-Developer_Guide-RichFaces_overview-Architecture"> <title>Architecture</title> <para> - Incomplete + The important elements of the RichFaces framework are as follows: + <itemizedlist> + <listitem> + <para> + Ajax Filter + </para> + </listitem> + <listitem> + <para> + Ajax Action Components + </para> + </listitem> + <listitem> + <para> + Ajax Containers + </para> + </listitem> + <listitem> + <para> + Skins and Theming + </para> + </listitem> + <listitem> + <para> + RichFaces JavaScript Engine + </para> + </listitem> + </itemizedlist> + Read this section for details on each element. </para> + <section id="sect-Developer_Guide-RichFaces_overview-Ajax_Filter"> + <title>Ajax Filter</title> + <para> + To get all benefits of RichFaces, a filter should be registered in the <filename>web.xml</filename> file of your application. The filter recognizes multiple request types. Filter configuration is covered in detail in <xref linkend="sect-Developer_Guide-Advanced_features-Filters" />. <xref linkend="figu-Developer_Guide-RichFaces_overview-Request_processing_sequences" /> shows the difference between processing a regular JSF request and an Ajax request with a filter. + </para> + <figure id="figu-Developer_Guide-RichFaces_overview-Request_processing_sequences"> + <title>Request processing sequences</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/figu-Developer_Guide-RichFaces_overview-Request_processing_sequences.png" format="PNG" /> + </imageobject> + <textobject> + <para> + The difference between processing a regular JSF request and an Ajax request with a filter. + </para> + </textobject> + </mediaobject> + <para> + With the regular JSF request, the whole JSF tree is encoded. With the Ajax request, the filter parses the content of an Ajax response before sending it to the client side, and encoding depends on the size of the Ajax region. + </para> + </figure> + <para> + Both with and without a filter, the required static or dynamic resources that your application requests are registered in the <classname>ResourseBuilder</classname> class. <xref linkend="figu-Developer_Guide-RichFaces_overview-Resource_request_sequence" /> shows the differences in resource requests for a regular JSF request and an Ajax request with a filter. + </para> + <figure id="figu-Developer_Guide-RichFaces_overview-Resource_request_sequence"> + <title>Resource request sequence</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/figu-Developer_Guide-RichFaces_overview-Resource_request_sequence.png" format="PNG" /> + </imageobject> + <textobject> + <para> + The difference between resource requests for a regular JSF request and an Ajax request with a filter. + </para> + </textobject> + </mediaobject> + <para> + When a request for a resource occurs, the RichFaces filter checks the <classname>ResourceCache</classname> for the resource. If the resource is in the cache, it is sent to the client. Otherwise, the filter searches for the resource among those that are registered by the <classname>ResourceBuilder</classname>. If the resource is registered, the RichFaces filter will send a request to the <classname>ResourceBuilder</classname> to deliver the resource. + </para> + </figure> + </section> + <section id="sect-Developer_Guide-RichFaces_overview-Ajax_Action_Components"> + <title>Ajax Action Components</title> + <para> + The RichFaces framework includes several Ajax Action Components: <sgmltag>&lt;a4j:commandButton&gt;</sgmltag>, <sgmltag>&lt;a4j:commandLink&gt;</sgmltag>, <sgmltag>&lt;a4j:poll&gt;</sgmltag>, <sgmltag>&lt;a4j:ajax&gt;</sgmltag>, and more. Use Ajax Action Components to send Ajax requests from the client side. + </para> + </section> + <section id="sect-Developer_Guide-RichFaces_overview-Ajax_Containers"> + <title>Ajax Containers</title> + <para> + <classname>AjaxContainer</classname> is an interface that describes an area on a JSF page that is decoded during an Ajax request. <classname>AjaxViewRoot</classname> and <classname>AjaxRegion</classname> are implementations of this interface. + </para> + </section> + <section id="sect-Developer_Guide-RichFaces_overview-Skins_and_Theming"> + <title>Skins and Theming</title> + <para> + + </para> + </section> + <section id="sect-Developer_Guide-RichFaces_overview-RichFaces_JavaScript_Engine"> + <title>RichFaces JavaScript Engine</title> + <para> + The RichFaces JavaScript Engine runs on the client side. It can update different areas on a JSF page based on an Ajax response. It is not necessary to use the JavaScript code directly, as it is available automatically. + </para> + </section> </section> <section id="sect-Developer_Guide-RichFaces_overview-Technologies"> @@ -33,7 +145,34 @@ <section id="sect-Developer_Guide-RichFaces_overview-Restrictions"> <title>Restrictions</title> <para> - Incomplete + The following restrictions apply to applications implementing the RichFaces framework: + <itemizedlist> + <listitem> + <para> + Any Ajax framework should not append or delete elements on a page, but should instead replace them. For successful updates, an element with the same identifier as in the response must exist on the page. If it is necessary to append code to a page, include a placeholder for it (an empty element). For the same reason, it is recommended that messages be placed in the <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> component. + </para> + </listitem> + <listitem> + <para> + <sgmltag>&lt;f:verbatim&gt;</sgmltag> should not be used for self-rendered containers, since it is transient and not saved in the tree. + </para> + </listitem> + <listitem> + <para> + Ajax requests are made by XMLHTTPRequest functions in XML format, but this XML bypasses most validations and the corrections that might be made in a browser. As such, a strict standards-compliant code for HTML and XHTML should be used, without skipping any required elements or attributes. Any necessary XML corrections are automatically made by the XML filter on the server, but unexpected effects can be produced through incorrect HTML code. + </para> + </listitem> + <listitem> + <para> + The RichFaces <classname>ViewHandler</classname> puts itself in front of the Facelets <classname>ViewHandlers</classname> chain. + </para> + </listitem> + <listitem> + <para> + RichFaces components uses their own renderers. In the <emphasis>Render Response Phase</emphasis>, the RichFaces framework makes a traversal of the component tree, calls its own renderer, and passes the result to the Faces Response. + </para> + </listitem> + </itemizedlist> </para> </section> Added: root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Request_processing_flow.png =================================================================== (Binary files differ) Property changes on: root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Request_processing_flow.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Request_processing_sequences.png =================================================================== (Binary files differ) Property changes on: root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Request_processing_sequences.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Resource_request_sequence.png =================================================================== (Binary files differ) Property changes on: root/docs/trunk/Developer_Guide/en-US/images/figu-Developer_Guide-RichFaces_overview-Resource_request_sequence.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream