[richfaces-svn-commits] JBoss Rich Faces SVN: r15803 - root/docs/trunk/Component_Reference/en-US.

Author: SeanRogers Date: 2009-11-02 02:28:47 -0500 (Mon, 02 Nov 2009) New Revision: 15803 Modified: root/docs/trunk/Component_Reference/en-US/Ajax_basics.xml root/docs/trunk/Component_Reference/en-US/Common_Ajax_attributes.xml root/docs/trunk/Component_Reference/en-US/Rich_inputs.xml Log: Worked on Component Reference chapters Modified: root/docs/trunk/Component_Reference/en-US/Ajax_basics.xml =================================================================== --- root/docs/trunk/Component_Reference/en-US/Ajax_basics.xml 2009-11-01 23:12:53 UTC (rev 15802) +++ root/docs/trunk/Component_Reference/en-US/Ajax_basics.xml 2009-11-02 07:28:47 UTC (rev 15803) @@ -5,24 +5,102 @@ <chapter id="chap-Component_Reference-Ajax_basics"> <title>Ajax basics</title> <para> - Incomplete + This chapter details the basic components that respond to a user action and submit an Ajax request. </para> <section id="sect-Component_Reference-Ajax_basics-a4jcommandButton"> - <title><classname>&lt;a4j:commandButton&gt;</classname></title> + <title>&lt;a4j:commandButton&gt;</title> + <itemizedlist> + <listitem> + <para> + component-type: <classname>org.ajax4jsf.CommandButton</classname> + </para> + </listitem> + <listitem> + <para> + component-family: <classname>javax.faces.Command</classname> + </para> + </listitem> + <listitem> + <para> + component-class: <classname>org.ajax4jsf.component.html.HtmlAjaxCommandButton</classname> + </para> + </listitem> + <listitem> + <para> + renderer-type: <classname>org.ajax4jsf.components.AjaxCommandButtonRenderer</classname> + </para> + </listitem> + </itemizedlist> <para> The <classname>&lt;a4j:commandButton&gt;</classname> is similar to the JavaServer Faces (<acronym>JSF</acronym>) component <classname>&lt;h:commandButton&gt;</classname>, but additionally includes Ajax support. When the command button is clicked it generates an Ajax form submit, and when a response is received the command button can be dynamically rendered. </para> + <para> + The <classname>&lt;a4j:commandButton&gt;</classname> requires only the <code>value</code> and <code>render</code> attributes to function. The <code>value</code> attribute specifies the text of the button and the <code>render</code> attribute specifies which areas are to be updated. The <classname>&lt;a4j:commandButton&gt;</classname> uses the <code>onclick</code> event instead of the <code>onsubmit</code> event, but otherwise uses all common Ajax attributes as listed in <xref linkend="chap-Component_Reference-Common_Ajax_attributes" />. + </para> + <note> + <title>Note</title> + <para> + When attaching a JavaScript function to a <classname>&lt;a4j:commandButton&gt;</classname> with the help of a <classname>&lt;rich:componentControl&gt;</classname>, do not use the <code>attachTo</code> attribute of <classname>&lt;rich:componentControl&gt;</classname>. The attribute adds event handlers using <classname>Event.observe</classname> but <classname>&lt;a4j:commandButton&gt;</classname> does not include this event. + </para> + </note> </section> <section id="sect-Component_Reference-Ajax_basics-a4jcommandLink"> - <title>a4j:commandLink</title> + <title>&lt;a4j:commandLink&gt;</title> + <itemizedlist> + <listitem> + <para> + component-type: <classname>org.ajax4jsf.CommandLink</classname> + </para> + </listitem> + <listitem> + <para> + component-family: <classname>javax.faces.Command</classname> + </para> + </listitem> + <listitem> + <para> + component-class: <classname>org.ajax4jsf.component.html.HtmlAjaxCommandLink</classname> + </para> + </listitem> + <listitem> + <para> + renderer-type: <classname>org.ajax4jsf.components.AjaxCommandLinkRenderer</classname> + </para> + </listitem> + </itemizedlist> <para> - Incomplete + The <classname>&lt;a4j:commandLink&gt;</classname> is similar to the JavaServer Faces (<acronym>JSF</acronym>) component <classname>&lt;h:commandLink&gt;</classname>, but additionally includes Ajax support. When the command link is clicked it generates an Ajax form submit, and when a response is received the command link can be dynamically rendered. </para> + <para> + The <classname>&lt;a4j:commandLink&gt;</classname> requires only the <code>value</code> and <code>render</code> attributes to function. The <code>value</code> attribute specifies the text of the link and the <code>render</code> attribute specifies which areas are to be updated. The <classname>&lt;a4j:commandLink&gt;</classname> uses the <code>onclick</code> event instead of the <code>onsubmit</code> event, but otherwise uses all common Ajax attributes as listed in <xref linkend="chap-Component_Reference-Common_Ajax_attributes" />. + </para> </section> <section id="sect-Component_Reference-Ajax_basics-a4jhtmlCommandLink"> - <title>a4j:htmlCommandLink</title> + <title>&lt;a4j:htmlCommandLink&gt;</title> + <itemizedlist> + <listitem> + <para> + component-type: <classname>org.ajax4jsf.HtmlCommandLink</classname> + </para> + </listitem> + <listitem> + <para> + component-family: <classname>javax.faces.Command</classname> + </para> + </listitem> + <listitem> + <para> + component-class: <classname>org.ajax4jsf.component.html.HtmlCommandLink</classname> + </para> + </listitem> + <listitem> + <para> + renderer-type: <classname>org.ajax4jsf.HtmlCommandLinkRenderer</classname> + </para> + </listitem> + </itemizedlist> <para> Incomplete </para> Modified: root/docs/trunk/Component_Reference/en-US/Common_Ajax_attributes.xml =================================================================== --- root/docs/trunk/Component_Reference/en-US/Common_Ajax_attributes.xml 2009-11-01 23:12:53 UTC (rev 15802) +++ root/docs/trunk/Component_Reference/en-US/Common_Ajax_attributes.xml 2009-11-02 07:28:47 UTC (rev 15803) @@ -72,7 +72,7 @@ <example id="exam-Component_Reference-limitRender-Rendering_example"> <title>Rendering example</title> -<programlisting role="XML"> +<programlisting language="XML"> &lt;h:form id="form1"&gt; &lt;a4j:commandButton value="Normal rendering" render="infoBlock" /&gt; &lt;a4j:commandButton value="Limited rendering" render="infoBlock" limitRender="true" /&gt; @@ -96,39 +96,49 @@ <section id="sect-Component_Reference-Queuing_and_traffic_control-queue"> <title>queue</title> <para> - The <code>queue</code> 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 <code>queue</code> attribute ensures that the + The <code>queue</code> 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 <code>queue</code> attribute ensures that the requests are responded to in a set order. </para> + <para> + A queue name is specified with the <code>queue</code> 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 + </para> </section> - + <section> + <title>requestDelay</title> + <para> + The <code>requestDelay</code> 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. + </para> + </section> + <section> + <title>ignoreDupResponses</title> + <para> + When set to <literal>true</literal>, the <code>ignoreDupResponses</code> attribute causes responses from the server for the request to be ignored if there is another similar request in the queue. This avoids unnecessary updates on the client when another update is expected. The request is still processed on the server, but if another similar request has been queued then no updates are made on the client. + </para> + </section> </section> <section id="sect-Component_Reference-Common_Ajax_attributes-Data_processing"> <title>Data processing</title> - <section id="sect-Component_Reference-Data_processing-execute"> - <title>execute</title> - <para> - Incomplete - </para> - </section> - + <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-process"> <title>process</title> <para> - Incomplete + The <code>process</code> attribute allows <acronym>JSF</acronym> processing to be limited to defined components. To only process the requesting component, <code>process="@this"</code> can be used. </para> </section> <section id="sect-Component_Reference-Data_processing-immediate"> <title>immediate</title> <para> - Incomplete + If the <code>immediate</code> 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 waitingfor 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>bypassUpdates</title> <para> - Incomplete + If the <code>bypassUpdates</code> 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> @@ -136,71 +146,88 @@ <section id="sect-Component_Reference-Common_Ajax_attributes-Action_and_navigation"> <title>Action and navigation</title> + <para> + The <code>action</code> and <code>actionListener</code> attributes can be used to invoke action methods and define action events. + </para> <section id="sect-Component_Reference-Action_and_navigation-action"> <title>action</title> <para> - Incomplete + The <code>action</code> attribute is a method binding that points to the application action to be invoked. The method can be activated during the Apply Request Values phase or the Invoke Application phase of the request processing lifecycle. </para> + <para> + The method specified in the <code>action</code> attribute must return <literal>null</literal> for an Ajax response with a partial page update. + </para> </section> <section id="sect-Component_Reference-Action_and_navigation-actionListener"> <title>actionListener</title> <para> - Incomplete + The <code>actionListener</code> attribute is a method binding for <classname>ActionEvent</classname> methods with a return type of <literal>void</literal>. </para> </section> </section> - <section id="sect-Component_Reference-Common_Ajax_attributes-Events_and_Javascript_interactions"> - <title>Events and Javascript interactions</title> - <section id="sect-Component_Reference-Events_and_Javascript_interactions-onsubmit"> + <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. + </para> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onsubmit"> <title>onsubmit</title> <para> - Incomplete + The <code>onsubmit</code> attribute will invoke the JavaScript code before the Ajax request is sent. The request is canceled if the JavaScript code defined for <code>onsubmit</code> returns <literal>false</literal>. </para> </section> - <section id="sect-Component_Reference-Events_and_Javascript_interactions-onclick"> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onclick"> <title>onclick</title> <para> - Incomplete + The <code>onclick</click> attribute functions similarly to the <code>onsubmit</code> attribute for those components that can be clicked, such as <classname>&lt;a4j:commandButton&gt;</classname> and <classname>&lt;a4j:commandLink&gt;</classname>. It invokes the defined JavaScript before the Ajax request, and the request will be canceled if the defined code returns <literal>false</literal>. </para> </section> - <section id="sect-Component_Reference-Events_and_Javascript_interactions-oncomplete"> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-oncomplete"> <title>oncomplete</title> <para> - Incomplete + The <code>oncomplete</code> attribute invokes the JavaScript code after the Ajax response has been returned and the <acronym>DOM</acronym> tree of the browser has been updated. 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 <code>oncomplete</code> attribute cannot use the <literal>this</literal> keyword as it will not point to the component from which the Ajax request was initiated. </para> </section> - <section id="sect-Component_Reference-Events_and_Javascript_interactions-onbegin"> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onbegin"> <title>onbegin</title> <para> Incomplete </para> </section> - <section id="sect-Component_Reference-Events_and_Javascript_interactions-onsuccess"> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onsuccess"> <title>onsuccess</title> <para> Incomplete </para> </section> - <section id="sect-Component_Reference-Events_and_Javascript_interactions-onerror"> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-onerror"> <title>onerror</title> <para> Incomplete </para> </section> - <section id="sect-Component_Reference-Events_and_Javascript_interactions-data"> + <section id="sect-Component_Reference-Events_and_JavaScript_interactions-data"> <title>data</title> <para> - Incomplete + The <code>data</code> 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 <code>data</code> variable in the event attribute definitions. Both primitive types and complex types such as arrays and collections can be serialized and used with <code>data</code>. </para> + <example id="exam-Component_Reference-limitRender-Rendering_example"> + <title>Data reference example</title> + +<programlisting language="XML"> +&lt;a4j:commandButton value="Update" data="#{userBean.name}" oncomplete="showTheName(data.name)" /&gt; +</programlisting> + </example> + </section> </section> Modified: root/docs/trunk/Component_Reference/en-US/Rich_inputs.xml =================================================================== --- root/docs/trunk/Component_Reference/en-US/Rich_inputs.xml 2009-11-01 23:12:53 UTC (rev 15802) +++ root/docs/trunk/Component_Reference/en-US/Rich_inputs.xml 2009-11-02 07:28:47 UTC (rev 15803) @@ -5,73 +5,83 @@ <chapter id="chap-Component_Reference-Rich_inputs"> <title>Rich inputs</title> <para> - Incomplete + This chapter details rich components for user input and interaction. </para> <section id="sect-Component_Reference-Rich_inputs-richCalendar"> - <title>rich:Calendar</title> + <title>&lt;rich:Calendar&gt;</title> <para> - Incomplete + The <classname>&lt;rich:calendar&gt;</classname> component allows the user to enter a date and time through an in-line or pop-up calendar. The pop-up calendar can navigate through months and years, and its look and feel can be highly customized. </para> + <para> + The <classname>&lt;rich:calendar&gt;</classname> component supports two different ways of loading data through defining the <code>mode</code> attribute. When not specified, the component uses <literal>client</literal> mode, which loads an initial portion of data within a set date range. The range can be defined by using the <code>preloadDateRangeBegin</code> and <code>preloadDateRangeEnd</code> attributes. Additional data requests are not sent. Alternatively, with <code>mode="ajax"</code> the <classname>&lt;rich:calendar&gt;</classname> requests portions of data for rendering from a special data model. The data model can be defined through the <code>dataModel</code> attribute, which points to an object that implements the <classname>CalendarDataModel</classname> interface. If the <code>dataModel</code> attribute is not defined or has a value of <literal>null</literal>, the <literal>ajax</literal> mode functions the same as the <literal>client</literal> mode. + </para> + <para> + The <classname>&lt;rich:calendar&gt;</classname> component is presented as a pop-up by default, appearing as a text input with a button to expand the full pop-up calendar. Specifying <code>popup="false</code> will render the calendar in-line on the page instead, which displays the full calendar without the text input or display button. The appearance of the display button can be altered from the standard calendar icon by defining the <code>buttonIcon</code> and <code>buttonIconDisabled</code> attributes to replace the icon with a specified file, or by defining the <code>buttonLabel</code> attribute to display text on the button without an icon. If <code>buttonLabel</code> is specified then both <code>buttonIcon</code> and <code>buttonIconDisabled</code> attributes are ignored. + </para> + <para> + + </para> + </section> <section id="sect-Component_Reference-Rich_inputs-richcolorPicker"> - <title>rich:colorPicker</title> + <title>&lt;rich:colorPicker&gt;</title> <para> Incomplete </para> </section> <section id="sect-Component_Reference-Rich_inputs-richcomboBox"> - <title>rich:comboBox</title> + <title>&lt;rich:comboBox&gt;</title> <para> Incomplete </para> </section> <section id="sect-Component_Reference-Rich_inputs-richeditor"> - <title>rich:editor</title> + <title>&lt;rich:editor&gt;</title> <para> Incomplete </para> </section> <section id="sect-Component_Reference-Rich_inputs-richfileUpload"> - <title>rich:fileUpload</title> + <title>&lt;rich:fileUpload&gt;</title> <para> Incomplete </para> </section> <section id="sect-Component_Reference-Rich_inputs-richinplaceInput"> - <title>rich:inplaceInput</title> + <title>&lt;rich:inplaceInput&gt;</title> <para> Incomplete </para> </section> <section id="sect-Component_Reference-Rich_inputs-richinplaceSelect"> - <title>rich:inplaceSelect</title> + <title>&lt;rich:inplaceSelect&gt;</title> <para> Incomplete </para> </section> <section id="sect-Component_Reference-Rich_inputs-richinputNumberSlider"> - <title>rich:inputNumberSlider</title> + <title>&lt;rich:inputNumberSlider&gt;</title> <para> Incomplete </para> </section> <section id="sect-Component_Reference-Rich_inputs-richinputNumberSpinner"> - <title>rich:inputNumberSpinner</title> + <title>&lt;rich:inputNumberSpinner&gt;</title> <para> Incomplete </para> </section> <section id="sect-Component_Reference-Rich_inputs-richsuggestionBox"> - <title>rich:suggestionBox</title> + <title>&lt;rich:suggestionBox&gt;</title> <para> Incomplete </para>