Author: SeanRogers Date: 2011-03-23 02:25:43 -0400 (Wed, 23 Mar 2011) New Revision: 22294 Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Common_Ajax_attributes.xml modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-data-Data_reference_example.xml_sample modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-render-render_example.xml_sample Log: Revised Component Reference common Ajax attributes: RFPL-1380 Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Common_Ajax_attributes.xml =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Common_Ajax_attributes.xml 2011-03-23 01:49:02 UTC (rev 22293) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Common_Ajax_attributes.xml 2011-03-23 06:25:43 UTC (rev 22294) @@ -9,12 +9,82 @@ <para> Most attributes have default values, so they need not be explicitly set for the component to function in its default state. These attributes can be altered to customize the behavior of the component if necessary. </para> + + <section id="sect-Component_Reference-Common_Ajax_attributes-Data_processing"> + <title>Data processing</title> + <para> + The RichFaces Ajax script is built on a base of the JSF 2 Ajax script. As such, each time a request is sent, the data from the requesting component's parent <acronym>JSF</acronym> form is submitted along with the <acronym>XMLHTTPRequest</acronym> object. The form data contains values from the input element and auxiliary information such as state-saving data. + </para> + <section id="sect-Component_Reference-Data_processing-execute"> + <title><varname>execute</varname></title> + <para> + The <varname>execute</varname> attribute allows <acronym>JSF</acronym> processing to be limited to defined components. The <varname>execute</varname> attribute can point to an <varname>id</varname> identifier of a specific component to process. Components can also be identified through the use of Expression Language (<acronym>EL</acronym>). + </para> + <para> + Alternatively, the <varname>execute</varname> attribute accepts the following keywords: + </para> + <variablelist> + <varlistentry> + <term><code>@all</code></term> + <listitem> + <para> + Every component is processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@none</code></term> + <listitem> + <para> + No components are processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@this</code></term> + <listitem> + <para> + The requesting component with the <varname>execute</varname> attribute is processed. This is the default behavior for components. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@form</code></term> + <listitem> + <para> + The form that contains the requesting component is processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@region</code></term> + <listitem> + <para> + The region that contains the requesting component is processed. Use the <sgmltag>&lt;a4j:region&gt;</sgmltag> component as a wrapper element to specify regions. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Some components make use of additional keywords. These are detailed under the relevant component entry in this book. + </para> + </section> + + <section id="sect-Component_Reference-Data_processing-bypassUpdates"> + <title><varname>bypassUpdates</varname></title> + <para> + If the <varname>bypassUpdates</varname> attribute is set to <literal>true</literal>, the Update Model phase of the request processing lifecycle is bypassed. This is useful if user input needs to be validated but the model does not need to be updated. This is the opposite functionality to the <varname>execute</varname> attribute in RichFaces. + </para> + </section> + + </section> + <section id="sect-Component_Reference-Common_Ajax_attributes-Rendering"> <title>Rendering</title> <section id="sect-Component_Reference-Rendering-render"> <title><varname>render</varname></title> <para> - The <varname>render</varname> attribute provides a reference to one or more areas on the page that need updating after an Ajax interaction. It uses the <methodname>UIComponent.findComponent()</methodname> algorithm to find the components in the component tree using their <varname>id</varname> attributes as a reference. Components can be referenced by their <varname>id</varname> attribute alone, or by a hierarchy of components' <varname>id</varname> attributes to make locating components more efficient. <xref linkend="exam-Component_Reference-render-render_example" /> shows both ways of referencing components. Each command button will correctly render the referenced panel grids, but the second button locates the references more efficiently with explicit hierarchy paths. + The <varname>render</varname> attribute provides a reference to one or more components on the page that need updating after an Ajax interaction. It uses the <methodname>UIComponent.findComponent()</methodname> algorithm to find the components in the component tree using their <varname>id</varname> identifiers as a reference. Components can be referenced by their <varname>id</varname> identifier alone, or by their <varname>clientId</varname> identifier to make locating components more efficient. <xref linkend="exam-Component_Reference-render-render_example" /> shows both ways of referencing components. Each command button will correctly render the referenced panel grids, but the second button locates the references more efficiently with explicit <varname>clientId</varname> paths. </para> <example id="exam-Component_Reference-render-render_example"> <title>render example</title> @@ -23,13 +93,25 @@ <para> The value of the <varname>render</varname> attribute can also be an expression written using JavaServer Faces' Expression Language (<acronym>EL</acronym>); this can either be a <type>Set</type>, <type>Collection</type>, <type>Array</type>, or <type>String</type>. </para> + <note> + <title>Differences between <acronym>JSF</acronym> Ajax and RichFaces Ajax</title> + <para> + <acronym>JSF</acronym> evaluates all parameters during page rendering. As such, during a request from a page, all <varname>execute</varname> and <varname>render</varname> values are passed to the server from the client. In contrast, RichFaces evaluates these options at the server side during the current request. + </para> + <para> + This means that with JSF, making changes during a request to a <varname>render</varname> value defined with EL will not influence the request. RichFaces, however, will always use the newer values. + </para> + <para> + The RichFaces approach additionally increases data integrity. Parameters that are changed from the client side are re-evaluated on the server, where they cannot be changed. + </para> + </note> <important> - <title><varname>rendered</varname> attributes</title> + <title>Conditionally-rendered component updates</title> <para> - A common problem with using <varname>render</varname> occurs when the referenced component has a <varname>rendered</varname> attribute. <acronym>JSF</acronym> does not mark the place in the browser's Document Object Model (<acronym>DOM</acronym>) where the rendered component would be placed in case the <varname>rendered</varname> attribute returns <literal>false</literal>. As such, when RichFaces sends the render code to the client, the page does not update as the place for the update is not known. + A common problem with using <varname>render</varname> occurs when the referenced component is conditionally rendered via the <varname>rendered</varname> attribute. If a component is not initially rendered, it does not have any HTML representation in the Document Object Model (<acronym>DOM</acronym>). As such, when RichFaces renders the component via Ajax, the page does not update as the place for the update is not known. </para> <para> - To work around this issue, wrap the component to be rendered in an <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> with <code>layout="none"</code>. The <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> will receive the update and render the component as required. + To work around this issue, wrap the component to be rendered in an <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> component. The <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> component will receive the update and render the component as required. </para> </important> </section> @@ -40,14 +122,17 @@ A component with <code>ajaxRendered="true"</code> will be re-rendered with <emphasis>every</emphasis> Ajax request, even when not referenced by the requesting component's <varname>render</varname> attribute. This can be useful for updating a status display or error message without explicitly requesting it. </para> <para> - Rendering of components in this way can be repressed by adding <code>limitRender="true"</code> to the requesting component, as described in <xref linkend="sect-Component_Reference-Rendering-limitRender" />. + The <varname>ajaxRendered</varname> attribute's functionality is the basis for the <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> component. The <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> component is designed to mark parts of the page for automatic updating. Refer to <xref linkend="sect-Component_Reference-Containers-a4joutputPanel" /> for details. </para> + <para> + Automatic rendering of such components can be repressed by adding <code>limitRender="true"</code> to the requesting component, as described in <xref linkend="sect-Component_Reference-Rendering-limitRender" />. + </para> </section> <section id="sect-Component_Reference-Rendering-limitRender"> <title><varname>limitRender</varname></title> <para> - A component with <code>limitRender="true"</code> specified will <emphasis>not</emphasis> cause components with <code>ajaxRendered="true"</code> to re-render, and only those components listed in the <varname>render</varname> attribute will be updated. This essentially overrides the <varname>ajaxRendered</varname> attribute in other components. + RichFaces Ajax-enabled components and Ajax behaviors with <code>limitRender="true"</code> specified will <emphasis>not</emphasis> cause components with <code>ajaxRendered="true"</code> to re-render, and only those components listed in the <varname>render</varname> attribute will be updated. This essentially overrides the <varname>ajaxRendered</varname> attribute in other components. </para> <para> <xref linkend="exam-Component_Reference-data-Data_reference_example" /> describes two command buttons, a panel grid rendered by the buttons, and an output panel showing error messages. When the first button is clicked, the output panel is rendered even though it is not explicitly referenced with the <varname>render</varname> attribute. The second button, however, uses <code>limitRender="true"</code> to override the output panel's rendering and only render the panel grid. @@ -62,20 +147,22 @@ <section id="sect-Component_Reference-Common_Ajax_attributes-Queuing_and_traffic_control"> <title>Queuing and traffic control</title> + <!-- <section id="sect-Component_Reference-Queuing_and_traffic_control-queue"> <title><varname>queue</varname></title> <para> - The <varname>queue</varname> attribute defines the name of the queue that will be used to schedule upcoming Ajax requests. Typically RichFaces does not queue Ajax requests, so if events are produced simultaneously they will arrive at the server simultaneously. This can potentially lead to unpredictable results when the responses are returned. The <varname>queue</varname> attribute ensures that the requests are responded to in a set order. + The <varname>queue</varname> attribute is built on top of the JSF 2 queue functionality. It defines the name of the queue that will be used to schedule upcoming Ajax requests. Specify a queue name with the <varname>queue</varname> attribute, and each request added to the named queue is completed one at a time in the order they were sent. </para> <para> - A queue name is specified with the <varname>queue</varname> attribute, and each request added to the named queue is completed one at a time in the order they were sent. In addition, RichFaces intelligently removes similar requests produced by the same event from a queue to improve performance, protecting against unnecessary traffic flooding and + Typically RichFaces does not queue Ajax requests, so if events are produced simultaneously they will arrive at the server simultaneously. This can potentially lead to unpredictable results when the responses are returned. The <varname>queue</varname> attribute ensures that the requests are responded to in a set order. </para> </section> + --> <section id="sect-Component_Reference-Queuing_and_traffic_control-requestDelay"> <title><varname>requestDelay</varname></title> <para> - The <varname>requestDelay</varname> attribute specifies an amount of time in milliseconds for the request to wait in the queue before being sent to the server. If a similar request is added to the queue before the delay is over, the original request is removed from the queue and not sent. + The <varname>requestDelay</varname> attribute specifies an amount of time in milliseconds for the request to wait in the queue before being sent to the server. If a similar request is added to the queue before the delay is over, the original request is replaced with the new one. </para> </section> @@ -87,37 +174,10 @@ </section> </section> - - <section id="sect-Component_Reference-Common_Ajax_attributes-Data_processing"> - <title>Data processing</title> - <para> - RichFaces uses a form-based approach for sending Ajax requests. As such, each time a request is sent the data from the requesting component's parent <acronym>JSF</acronym> form is submitted along with the <acronym>XMLHTTPRequest</acronym> object. The form data contains values from the input element and auxiliary information such as state-saving data. - </para> - <section id="sect-Component_Reference-Data_processing-execute"> - <title><varname>execute</varname></title> - <para> - The <varname>execute</varname> attribute allows <acronym>JSF</acronym> processing to be limited to defined components. To only process the requesting component, <code>execute="@this"</code> can be used. - </para> - </section> - - <section id="sect-Component_Reference-Data_processing-immediate"> - <title><varname>immediate</varname></title> - <para> - If the <varname>immediate</varname> attribute is set to <literal>true</literal>, the default ActionListener is executed immediately during the Apply Request Values phase of the request processing lifecycle, rather than waiting for the Invoke Application phase. This allows some data model values to be updated regardless of whether the Validation phase is successful or not. - </para> - </section> - - <section id="sect-Component_Reference-Data_processing-bypassUpdates"> - <title><varname>bypassUpdates</varname></title> - <para> - If the <varname>bypassUpdates</varname> attribute is set to <literal>true</literal>, the Update Model phase of the request processing lifecycle is bypassed. This is useful if user input needs to be validated but the model does not need to be updated. - </para> - </section> - </section> - - <section id="sect-Component_Reference-Common_Ajax_attributes-Action_and_navigation"> - <title>Action and navigation</title> + <!-- + <section id="sect-Component_Reference-Common_Ajax_attributes-Server-side_event_handling"> + <title>Server-side event handling</title> <para> The <varname>action</varname> and <varname>actionListener</varname> attributes can be used to invoke action methods and define action events. </para> @@ -139,69 +199,66 @@ </section> </section> + --> <section id="sect-Component_Reference-Common_Ajax_attributes-Events_and_JavaScript_interactions"> <title>Events and JavaScript interactions</title> <para> - RichFaces allows for Ajax-enabled <acronym>JSF</acronym> applications to be developed without using any additional JavaScript code. However it is still possible to invoke custom JavaScript code through Ajax events using event listeners. + JSF provides global <varname>jsf.ajax.onError</varname> and <varname>jsf.ajax.onEvent</varname> events to define handlers (the <varname>jsf.ajax.onEvent</varname> event is used for all <varname>begin</varname>, <varname>success</varname>, and <varname>complete</varname> events). RichFaces adds event-specific attributes at the component level. </para> - <section id="sect-Component_Reference-Events_and_JavaScript_interactions-submit"> - <title><varname>submit</varname></title> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onsubmit"> + <title><varname>onsubmit</varname></title> <para> - The <varname>submit</varname> event attribute invokes the event listener <emphasis>before</emphasis> the Ajax request is sent. The request is canceled if the event listener defined for <varname>submit</varname> event returns <literal>false</literal>. + The <varname>onsubmit</varname> event attribute invokes the event listener <emphasis>before</emphasis> the Ajax request is sent. The request is canceled if the event listener defined for the <varname>onsubmit</varname> event returns <literal>false</literal>. </para> </section> - <section id="sect-Component_Reference-Events_and_JavaScript_interactions-begin"> - <title><varname>begin</varname></title> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onbegin"> + <title><varname>onbegin</varname></title> <para> - The <varname>begin</varname> event attribute invokes the event listener <emphasis>after</emphasis> the Ajax request is sent. + The <varname>onbegin</varname> event attribute invokes the event listener <emphasis>after</emphasis> the Ajax request is sent. </para> </section> - <section id="sect-Component_Reference-Events_and_JavaScript_interactions-click"> - <title><varname>click</varname></title> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onbeforedomupdate"> + <title><varname>onbeforedomupdate</varname></title> <para> - The <varname>click</varname> event attribute functions similarly to the <varname>submit</varname> event attribute for those components that can be clicked, such as <sgmltag>&lt;a4j:commandButton&gt;</sgmltag> and <sgmltag>&lt;a4j:commandLink&gt;</sgmltag>. It invokes the defined JavaScript before the Ajax request, and the request will be canceled if the defined code returns <literal>false</literal>. + The <varname>onbeforedomupdate</varname> event attribute invokes the event listener after the Ajax response has been returned but <emphasis>before</emphasis> the <acronym>DOM</acronym> tree of the browser has been updated. </para> </section> - <section id="sect-Component_Reference-Events_and_JavaScript_interactions-success"> - <title><varname>success</varname></title> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-oncomplete"> + <title><varname>oncomplete</varname></title> <para> - The <varname>success</varname> event attribute invokes the event listener after the Ajax response has been returned but <emphasis>before</emphasis> the <acronym>DOM</acronym> tree of the browser has been updated. + The <varname>oncomplete</varname> event attribute invokes the event listener after the Ajax response has been returned <emphasis>and</emphasis> the <acronym>DOM</acronym> tree of the browser has been updated. </para> - </section> - - <section id="sect-Component_Reference-Events_and_JavaScript_interactions-complete"> - <title><varname>complete</varname></title> - <para> - The <varname>complete</varname> event attribute invokes the event listener after the Ajax response has been returned <emphasis>and</emphasis> the <acronym>DOM</acronym> tree of the browser has been updated. - </para> + <!-- <note> <title>Reference consistency</title> <para> The code is registered for further invocation of the <acronym>XMLHTTP</acronym> request object before an Ajax request is sent. As such, using <acronym>JSF</acronym> Expression Language (<acronym>EL</acronym>) value binding means the code will not be changed during processing of the request on the server. Additionally the <varname>complete</varname> event attribute cannot use the <literal>this</literal> keyword as it will not point to the component from which the Ajax request was initiated. </para> </note> - </section> + --> - <section id="sect-Component_Reference-Events_and_JavaScript_interactions-error"> - <title><varname>error</varname></title> - <para> - The <varname>error</varname> event attribute invokes the event listener when an error has occurred during Ajax communications. - </para> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-data"> + <title><varname>data</varname></title> + <para> + The <varname>data</varname> attribute allows additional data to be handled with the <varname>oncomplete</varname> event. Use <acronym>JSF</acronym> Expression Language (<acronym>EL</acronym>) to reference the property of the managed bean, and its value will be serialized in JavaScript Object Notation (<acronym>JSON</acronym>) and returned to the client side. The property can then be referenced through the <parameter>event.data</parameter> variable in the event attribute definitions. Both primitive types and complex types such as arrays and collections can be serialized and used with <varname>data</varname>. + </para> + <example id="exam-Component_Reference-data-Data_reference_example"> + <title>Data reference example</title> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-data-Data_reference_example.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </example> + </section> + </section> - <section id="sect-Component_Reference-Events_and_JavaScript_interactions-data"> - <title><varname>data</varname></title> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onerror"> + <title><varname>onerror</varname></title> <para> - The <varname>data</varname> event attribute allows the use of additional data during an Ajax call. <acronym>JSF</acronym> Expression Language (<acronym>EL</acronym>) can be used to reference the property of the managed bean, and its value will be serialized in JavaScript Object Notation (<acronym>JSON</acronym>) and returned to the client side. The property can then be referenced through the <varname>data</varname> variable in the event attribute definitions. Both primitive types and complex types such as arrays and collections can be serialized and used with <varname>data</varname>. + The <varname>onerror</varname> event attribute invokes the event listener when an error has occurred during Ajax communications. </para> - <example id="exam-Component_Reference-data-Data_reference_example"> - <title>Data reference example</title> - <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-data-Data_reference_example.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </example> </section> </section> Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-data-Data_reference_example.xml_sample =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-data-Data_reference_example.xml_sample 2011-03-23 01:49:02 UTC (rev 22293) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-data-Data_reference_example.xml_sample 2011-03-23 06:25:43 UTC (rev 22294) @@ -1 +1 @@ -<a4j:commandButton value="Update" data="#{userBean.name}" complete="showTheName(data.name)" /> +<a4j:commandButton value="Update" oncomplete="showTheName(event.data.name)" data="#{userBean.name}" /> Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-render-render_example.xml_sample =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-render-render_example.xml_sample 2011-03-23 01:49:02 UTC (rev 22293) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-render-render_example.xml_sample 2011-03-23 06:25:43 UTC (rev 22294) @@ -7,8 +7,8 @@ ... </h:panelGrid> -<f:subview id="sv"> +<h:form id="sv"> <h:panelGrid id="infoBlock2"> ... </h:panelGrid> -</f:subview> +</h:form>