[richfaces-svn-commits] JBoss Rich Faces SVN: r14734 - branches/community/3.3.X/docs/userguide/en/src/main/docbook/included.
richfaces-svn-commits at lists.jboss.org
richfaces-svn-commits at lists.jboss.org
Fri Jun 26 11:43:13 EDT 2009
Author: atsebro
Date: 2009-06-26 11:43:13 -0400 (Fri, 26 Jun 2009)
New Revision: 14734
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.desc.xml
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.xml
Log:
RF-7423: a4j:queue component description review
Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.desc.xml
===================================================================
--- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.desc.xml 2009-06-26 14:27:53 UTC (rev 14733)
+++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.desc.xml 2009-06-26 15:43:13 UTC (rev 14734)
@@ -7,7 +7,10 @@
</keywordset>
</sectioninfo>
<title>Description</title>
- <para>The <emphasis role="bold"><property><a4j:queue></property></emphasis> component creates a queue of the Ajax requests. The Ajax4JSF or RichFaces components with built-in Ajax can reference the queue to optimize Ajax requests.</para>
- <para>You can find more information about the <emphasis role="bold"><property><a4j:queue></property></emphasis> in the "<link linkend="QueuePrinciples">Queue Principles</link>" section.</para>
+ <para>
+ The <emphasis role="bold"><property><a4j:queue></property></emphasis> component enqueues set of Ajax requests sent from client.
+ The <emphasis role="bold"><property><a4j></property></emphasis> or <emphasis role="bold"><property><rich></property></emphasis> components with built-in Ajax can reference the queue to optimize Ajax requests.
+ </para>
+
</section>
</chapter>
\ No newline at end of file
Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.xml
===================================================================
--- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.xml 2009-06-26 14:27:53 UTC (rev 14733)
+++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/queue.xml 2009-06-26 15:43:13 UTC (rev 14734)
@@ -35,24 +35,23 @@
</tgroup>
</table>
<section>
- <title>Creating on a page</title>
-
-
- <para>
- This is how you can create a form based queue. All other types of the queue are described in the "<link linkend="QueuePrinciples">Queue Principles</link>" section.
- </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[<h:form>
- <a4j:queue />
- <h:inputText value="#{bean.a}">
- <a4j:support event="onkeyup" />
- </h:inputText>
-</h:form>
-]]></programlisting>
+ <title>Creating the Component with a Page Tag</title>
+ <para>
+ To create the simplest variant of the Form Based queue use the following syntax.
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[<h:form id="form">
+ <a4j:queue />
+ <h:inputText value="#{bean.a}">
+ <a4j:support event="onkeyup" />
+ </h:inputText>
+</h:form>]]></programlisting>
+
</section>
- <section>
+
+ <section>
<title>Creating the Component Dynamically Using Java</title>
<para>
<emphasis role="bold"> Example: </emphasis>
@@ -62,46 +61,49 @@
HtmlQueue myQueue = new HtmlQueue();
]]></programlisting>
</section>
- <section>
- <title>Key attributes and ways of usage</title>
- <para>As it was said earlier the queue implemented in Richfaces has 4 types.
- In this section we will take a closer look at the form based queue. All other types of queue are similar is usage(except for the "global queue") but different is their scope.</para>
-
+
+ <section>
+ <title>Details of usage</title>
+
+ <para>
+ The RichFaces Queue has four different types: global default, view scoped default, view scoped named and form-based default queue (general Queue principles are good documented in the "<link linkend="QueuePrinciples">Queue Principles</link>" section).
+ The current section will take closer to the form based queue. The usage of other types is similar.
+ </para>
- <para>In order to disable or enable the <emphasis role="bold"><property
- ><a4j:queue></property></emphasis> component on the page you can use the
- <emphasis><property>"disabled"</property></emphasis> attribute.</para>
-
- <para> The <emphasis><property>"requestDelay"</property></emphasis> attribute
- defines delay time for all the requests fired by the action components. </para>
<para>
+ In order to disable or enable the <emphasis role="bold"><property><a4j:queue></property></emphasis> component on the page you can use the <emphasis><property>"disabled"</property></emphasis> attribute.
+ </para>
- The <emphasis><property>"size"</property></emphasis> attribute specifies the number of request that can be stored in the queue at a time.
- The attribute can help you prevent overloading of a sever with requests. You can also determine the type of behaviour when the size of the queue is exceeded.
- </para>
- <para>You should use the <emphasis><property>"sizeExceededBehavior"</property></emphasis> for the purpose.</para>
- <para> The <emphasis><property>"sizeExceededBehavior"</property></emphasis>
- attribute can set 4 the strategies of the queue's behavior if the number of the
- requests waiting in the queue is exceeded: </para>
- <itemizedlist>
- <listitem>
- <para>"dropNext" drops next request that should be fired</para>
- </listitem>
- <listitem>
- <para>"dropNew" drops the incoming request</para>
- </listitem>
- <listitem>
- <para>"fireNext" immediately fires the next request in line to be fired</para>
- </listitem>
- <listitem>
- <para>"fireNew" immediately fires the incoming request.</para>
- </listitem>
- </itemizedlist>
+ <para>
+ The <emphasis><property>"requestDelay"</property></emphasis> attribute defines delay time for all the requests fired by the action components.
+ </para>
+
+ <para>
+ The <emphasis><property>"size"</property></emphasis> attribute specifies the number of requests that can be stored in the queue at a time.
+ The attribute helps to prevent server overloading.
+ It is also possible to determine queue's behaviour when it's size is exceeded.
+ Use the <emphasis><property>"sizeExceededBehavior"</property></emphasis> for this purpose.
+ There are four possible strategies of exceeded queue's behavior:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>"dropNext" drops next request that should be fired</para>
+ </listitem>
+ <listitem>
+ <para>"dropNew" drops the incoming request</para>
+ </listitem>
+ <listitem>
+ <para>"fireNext" immediately fires the next request in line to be fired</para>
+ </listitem>
+ <listitem>
+ <para>"fireNew" immediately fires the incoming request.</para>
+ </listitem>
+ </itemizedlist>
+
<para>
<emphasis role="bold"> Example: </emphasis>
</para>
- <programlisting role="XML"><![CDATA[...
-<h:form>
+ <programlisting role="XML"><![CDATA[<h:form>
<a4j:queue size="2" requestDelay="500" sizeExceededBehavior="dropNext" onsizeexceeded="alert('The size of the queue is exceeded')" />
<h:inputText value="#{bean.a}">
<a4j:support event="onkeyup" />
@@ -112,10 +114,9 @@
<h:selectBooleanCheckbox value="#{bean.check}" id="checkboxID">
<a4j:support id="checkboxSupport" event="onchange" />
</h:selectBooleanCheckbox>
-</h:form>
-...]]></programlisting>
+</h:form>]]></programlisting>
<para>
- In this example if the queue has more than 2 requests waiting to be processed the next event will be dropped and a message (the <emphasis><property>"onsizeexceeded"</property></emphasis> attribute fires a JavaScript function ) saying that the queues is exceeded will be displayed.
+ In this example if the queue has more than 2 requests waiting to be processed the next event will be dropped and a message (the <emphasis><property>"onsizeexceeded"</property></emphasis> attribute fires a JavaScript function) saying that the queues is exceeded will be displayed.
</para>
<para>
@@ -127,35 +128,32 @@
<para>
<emphasis role="bold"> Example: </emphasis>
</para>
- <programlisting role="XML"><![CDATA[...
-<h:form>
- <a4j:queue requestDelay="500" ignoreDupResponses="true" />
- <h:inputText value="#{bean.a}">
- <a4j:support event="onkeyup" />
- </h:inputText>
-</h:form>
-...]]></programlisting>
+ <programlisting role="XML"><![CDATA[<h:form>
+ <a4j:queue requestDelay="500" ignoreDupResponses="true" />
+ <h:inputText value="#{bean.a}">
+ <a4j:support event="onkeyup" />
+ </h:inputText>
+</h:form>]]></programlisting>
<para>In this example, the requests are glued together and only the last one is submitted.</para>
- <para>Another key attribute that easies server load is <emphasis><property
- >"timeout"</property></emphasis>.
- The attribute specifies the amount of time an item can be in the queue before the sent event is be aborted and dropped from the queue.
- </para>
- <para>If the request is sent and response is not returned within the
- time frame defined in this attribute - the request is aborted, and the next one is sent.
+ <para>
+ Another key attribute that easies server load is <emphasis><property>"timeout"</property></emphasis>.
+ The attribute specifies the amount of time an item can be in the queue before the sent event is be aborted and dropped from the queue.
</para>
+
+ <para>
+ If the request is sent and response is not returned within the time frame defined in this attribute - the request is aborted, and the next one is sent.
+ </para>
<para>
<emphasis role="bold"> Example: </emphasis>
</para>
- <programlisting role="XML"><![CDATA[...
-<h:form>
- <a4j:queue timeout="1000" />
- <h:inputText value="#{bean.a}" >
- <a4j:support event="onkeyup" />
- </h:inputText>
-</h:form>
-...]]></programlisting>
+ <programlisting role="XML"><![CDATA[<h:form>
+ <a4j:queue timeout="1000" />
+ <h:inputText value="#{bean.a}">
+ <a4j:support event="onkeyup" />
+ </h:inputText>
+</h:form>]]></programlisting>
<para>
In this case if the sever doesn't respond within a second the request will be aborted.
@@ -164,28 +162,24 @@
<para>
As you can see the implementation of the queue provides some custom event handlers that you may use to call JavaScript functions.</para>
<para>
- The <emphasis><property>"oncomplete"</property></emphasis>is fired after request completed.
+ The <emphasis><property>"oncomplete"</property></emphasis>is fired after request completed.
+ In this event handler request object is be passed as a parameter.
+ Thus queue is be accessible using <code>request.queue</code>.
+ And the element which was a source of the request is available using <code>this</code>.
</para>
+
<para>
- In this event handler request object is be passed as a parameter.
- Thus queue is be accessible using <code>request.queue</code>.
- And the element which was a source of the request is available using <code>this</code>.
-
- </para>
- <para>
<emphasis role="bold"> Example: </emphasis>
</para>
- <programlisting role="XML"><![CDATA[...
-<h:form>
- <a4j:queue oncomplete="alert(request.queue.getSize())" requestDelay="1000" />
- <h:inputText value="#{bean.a}">
- <a4j:support event="onkeyup" />
- </h:inputText>
- <h:selectBooleanCheckbox value="#{bean.check}">
- <a4j:support event="onchange"/>
- </h:selectBooleanCheckbox>
-</h:form>
-...]]></programlisting>
+ <programlisting role="XML"><![CDATA[<h:form>
+ <a4j:queue oncomplete="alert(request.queue.getSize())" requestDelay="1000" />
+ <h:inputText value="#{bean.a}">
+ <a4j:support event="onkeyup" />
+ </h:inputText>
+ <h:selectBooleanCheckbox value="#{bean.check}">
+ <a4j:support event="onchange"/>
+ </h:selectBooleanCheckbox>
+</h:form>]]></programlisting>
<para>In this example you can see how the number of requests waiting in the queue change. You will get a message with the number of the requests in the queue.</para>
@@ -229,10 +223,12 @@
<section>
<title>Relevant resources links</title>
<para>
- <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/queue.jsf?c=queue"
- >On the component LiveDemo page</ulink> you can see the example of <emphasis role="bold">
- <property><a4j:queue></property>
- </emphasis> usage and sources for the given example. </para>
- <para>General queue principals are documented in the "<link linkend="QueuePrinciples">Queue Principles</link>" section.</para>
+ Vizit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/queue.jsf?c=queue">Queue Page</ulink> at the RichFaces LiveDemo for examples of component usage and their sources.
+ </para>
+
+ <para>
+ Useful articles:
+ </para>
+ <para>"<link linkend="QueuePrinciples">Queue Principles</link>" section of the RichFaces developer guide describes general Queue principles.</para>
</section>
</chapter>
More information about the richfaces-svn-commits
mailing list