Author: atsebro
Date: 2009-07-17 08:33:40 -0400 (Fri, 17 Jul 2009)
New Revision: 14947
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/poll.xml
Log:
RF-7512:a4j:poll component description review
Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/poll.xml
===================================================================
---
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/poll.xml 2009-07-17
09:48:42 UTC (rev 14946)
+++
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/poll.xml 2009-07-17
12:33:40 UTC (rev 14947)
@@ -1,48 +1,44 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter>
- <chapterinfo>
- <keywordset>
- <keyword>a4j:poll</keyword>
- </keywordset>
- </chapterinfo>
- <table>
- <title>Component identification parameters </title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Value</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>component-type</entry>
- <entry>org.ajax4jsf.Poll</entry>
- </row>
- <row>
- <entry>component-family</entry>
- <entry>org.ajax4jsf.components.AjaxPoll</entry>
- </row>
- <row>
- <entry>component-class</entry>
- <entry>org.ajax4jsf.component.html.AjaxPoll</entry>
- </row>
- <row>
- <entry>renderer-type</entry>
- <entry>org.ajax4jsf.components.AjaxPollRenderer</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <chapterinfo>
+ <keywordset>
+ <keyword>a4j:poll</keyword>
+ </keywordset>
+ </chapterinfo>
+ <table>
+ <title>Component identification parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>component-type</entry>
+ <entry>org.ajax4jsf.Poll</entry>
+ </row>
+ <row>
+ <entry>component-family</entry>
+
<entry>org.ajax4jsf.components.AjaxPoll</entry>
+ </row>
+ <row>
+ <entry>component-class</entry>
+
<entry>org.ajax4jsf.component.html.AjaxPoll</entry>
+ </row>
+ <row>
+ <entry>renderer-type</entry>
+
<entry>org.ajax4jsf.components.AjaxPollRenderer</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <section>
- <title>Creating on a page</title>
- <para id="creating">To create the simplest variant on a page use the
following syntax:</para>
-
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[<a4j:poll
interval="500" reRender="grid"/>
+ <section>
+ <title>Creating the component with a Page Tag</title>
+ <para id="creating">To create the simplest variant on a page
use the following syntax:</para>
+ <programlisting role="XML"><![CDATA[<a4j:poll
interval="500" reRender="grid"/>
]]></programlisting>
<!--para>The <emphasis role="bold">
<property><a4j:poll></property>
@@ -50,56 +46,41 @@
performs the corresponding action and renders a components with the
<emphasis>
<property>"someDataTable"</property>
</emphasis> id after a response comes back.</para-->
- </section>
- <section>
- <title>Creating the Component Dynamically Using Java</title>
-
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="JAVA"><![CDATA[import
org.ajax4jsf.component.html.AjaxPoll;
+ </section>
+ <section>
+ <title>Creating the Component Dynamically Using Java</title>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="JAVA"><![CDATA[import
org.ajax4jsf.component.html.AjaxPoll;
...
AjaxPoll myPoll = new AjaxPoll();
...]]></programlisting>
- </section>
- <section>
- <title>Key attributes and ways of usage</title>
- <para id="attributes">The <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> componet is used for periodical polling of server data. In order
to use the component
- it's necessary to set an update interval. The <emphasis>
- <property>"interval"</property>
- </emphasis> attribute defines an interval in milliseconds between the
previous
- response and the next request. The total period beetween two requests generated by
the
- <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> component is a sum of an<emphasis>
- <property>"interval"</property>
- </emphasis> attribute value and server response time. Default value for
<emphasis>
- <property>"interval"</property>
- </emphasis> attribute is set to "1000" milliseconds (1
second). See an example of definition in
- the <link linkend="creating">"Creating on a page"
section</link>. </para>
- <para>The <emphasis>
- <property>"timeout"</property>
- </emphasis> attribute defines response waiting time in milliseconds. If a
response
- isn't received during this period a connection is aborted and the next
request is
- sent. Default value for <emphasis>
- <property>"timeout"</property>
- </emphasis> attribute isn't set.</para>
- <para>The <emphasis>
- <property>"enabled"</property>
- </emphasis> attribute defines should the <emphasis
role="bold">
- <property><a4j:poll></property>
- </emphasis> send request or not. It's necessary to render the
- <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> to apply the current value of <emphasis>
- <property>"enabled"</property>
- </emphasis> attribute. You can use an EL-expression for <emphasis>
- <property>"enabled"</property>
- </emphasis> attribute to point to a bean property. An example of usage of
<link
- linkend="attributes">mentioned above attributes</link> is
placed below:</para>
+ </section>
+
+ <section>
+ <title>Details of usage</title>
+ <para id="attributes">
+ The <emphasis
role="bold"><property><a4j:poll></property></emphasis>
componet is used for periodical polling of server data.
+ In order to use the component it's necessary to set an update
interval.
+ The
<emphasis><property>"interval"</property></emphasis>
attribute defines an interval in milliseconds between the previous response and the next
request.
+ The total period beetween two requests generated by the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
component is a sum of
an<emphasis><property>"interval"</property></emphasis>
attribute value and server response time.
+ Default value for
<emphasis><property>"interval"</property></emphasis>
attribute is set to "1000" milliseconds (1 second).
+ See an example of definition in the "<link
linkend="creating">Creating the component with a Page
Tag</link>" section.
+ </para>
+ <para>
+ The
<emphasis><property>"timeout"</property></emphasis>
attribute defines response waiting time in milliseconds.
+ If a response isn't received during this period a connection
is aborted and the next request is sent.
+ Default value for
<emphasis><property>"timeout"</property></emphasis>
attribute isn't set.
+ </para>
+
+ <para>
+ The
<emphasis><property>"enabled"</property></emphasis>
attribute defines should the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
send request or not.
+ It's necessary to render the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
to apply the current value of
<emphasis><property>"enabled"</property></emphasis>
attribute.
+ You can use an EL-expression for
<emphasis><property>"enabled"</property></emphasis>
attribute to point to a bean property.
+ An example of usage of mentioned above attributes is placed below:
+ </para>
<para>
<emphasis role="bold">Example:</emphasis>
</para>
@@ -115,11 +96,8 @@
<h:panelGrid columns="1">
<h:outputText value="Polling Inactive" rendered="#{not
userBean.pollEnabled}" />
<h:outputText value="Polling Active"
rendered="#{userBean.pollEnabled}" />
- <a4j:commandButton style="width:120px"
id="control"
-
value="#{userBean.pollEnabled?'Stop':'Start'} Polling"
- reRender="poll, grid">
- <a4j:actionparam name="polling"
value="#{!userBean.pollEnabled}"
- assignTo="#{userBean.pollEnabled}"/>
+ <a4j:commandButton style="width:120px"
id="control" value="#{userBean.pollEnabled?'Stop':'Start'}
Polling" reRender="poll, grid">
+ <a4j:actionparam name="polling"
value="#{!userBean.pollEnabled}"
assignTo="#{userBean.pollEnabled}"/>
</a4j:commandButton>
</h:panelGrid>
<h:outputText id="serverDate" style="font-size:16px"
value="Server Date: #{userBean.date}"/>
@@ -127,29 +105,32 @@
</h:form>
...]]></programlisting>
- <para>The example shows how date and time are updated on a page in compliance
with data taken
- from a server. The <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> componet sends requests to the server every second.
<emphasis>
- <property>"reRender"</property>
- </emphasis> attribute for <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> contains value of its own Id. Hence, it renders itself for
applying the current value
- of <emphasis>
- <property>"enabled"</property>
- </emphasis> attribute.</para>
+ <para>
+ The example shows how date and time are updated on a page in compliance with
data taken from a server.
+ The <emphasis
role="bold"><property><a4j:poll></property></emphasis>
componet sends requests to the server every second.
+
<emphasis><property>"reRender"</property></emphasis>
attribute of the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
contains poll's own <code>Id</code>.
+ Hence, it is self rendered for applying the current value of
<emphasis><property>"enabled"</property></emphasis>
attribute.
+ </para>
- <note><title>Note:</title><para> The form around the
<emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> component is required.</para></note>
-
+
<note>
- <title>Note:</title>
- <para>To make the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
component
- send requests periodically when it <code>limitToList</code> is set to
"true", pass the
- <emphasis
role="bold"><property><a4j:poll></property></emphasis>
ID to it <code>reRender</code> attribute.
- </para>
- </note>
+ <title>Notes:</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The form around the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
component is required.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To make the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
component send requests periodically when it <code>limitToList</code> is set
to "true",
+ pass the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
ID to it <code>reRender</code> attribute.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </note>
<!--para>The component decodes all necessary JavaScript for time count and on
the expiry of some
interval for calling of a RichFaces utility method for Ajax request sending
(A4J.AJAX.Submit
@@ -173,64 +154,43 @@
<ulink
url="index.html#support"><a4j:support></ulink>
</property>
</emphasis> component description. </para-->
- <para>
- Information about the
<emphasis><property>"process"</property></emphasis>
attribute usage you can find <link linkend="process">" Decide
what to process " </link> guide section.
- </para>
+ <para>
+ Information about the
<emphasis><property>"process"</property></emphasis>
attribute usage you can find "<link linkend="process">Decide what
to process</link>" guide section.
+ </para>
</section>
- <section>
- <title>Relevant resources links</title>
- <para>In
- <ulink
-
url="http://wiki.jboss.org/wiki/CreateABannerUsingEffectsAndPoll&quo...
- RichFaces Wiki article "Creating a Banner Using Effects and
Poll"
- </ulink>
- you can get additional information how to create an image
- banner using
- <emphasis role="bold">
- <property><rich:effect></property>
- </emphasis>
- and
- <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis>
- components and also you can figure out how to create an HTML banner in
- <ulink
-
url="http://wiki.jboss.org/auth/wiki/CreateAHTMLBannerUsingEffectsAn...
- RichFaces Wiki article "Creating an HTML Banner Using Effects and
Poll"
- </ulink>
- .
- </para>
- <para>In
- <ulink
url="http://wiki.jboss.org/auth/wiki/RichFacesCookbook/SlideShow&quo...
Cookbook article on Slide Show"</ulink>
- you can find information how to make a Slide Show with help of the
- <emphasis role="bold">
- <property><rich:effect></property></emphasis>
- and <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> components.
- </para>
- <para>On
- <ulink
-
url="http://livedemo.exadel.com/richfaces-demo/richfaces/poll.jsf?c=...
- RichFaces Live Demo page
- </ulink>
- you can see the example of
- <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis>
- usage and sources for the given example.
- </para>
- <para>
- The additional information about component usage you can find
- in
- <ulink
-
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
- RichFaces Users Forum
- </ulink>
- .
- </para>
+
+ <section>
+ <title>Relevant resources links</title>
+ <para>
+ Vizit the <ulink
url="http://livedemo.exadel.com/richfaces-demo/richfaces/poll.jsf?c=...
page</ulink> at RichFaces LiveDemo for examples of the component usage and their
sources.
+ </para>
+
+ <para>
+ Useful examples and articles:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ "<ulink
url="http://www.jboss.org/community/wiki/CreateABannerUsingEffectsAn...
a Banner Using Effects and Poll</ulink>" article at RichFaces Wiki
+ gives an example of how to create an image banner using
<emphasis
role="bold"><property><rich:effect></property></emphasis>
and <emphasis
role="bold"><property><a4j:poll></property></emphasis>components;
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ "<ulink
url="http://www.jboss.org/community/wiki/CreateAHTMLBannerUsingEffec...
an HTML Banner Using Effects and Poll</ulink>" article at RichFaces Wiki
+ brings the code of the way of creating an HTML banner
banner using <emphasis
role="bold"><property><rich:effect></property></emphasis>
and <emphasis
role="bold"><property><a4j:poll></property></emphasis>components;
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ "<ulink
url="http://www.jboss.org/index.html?module=bb&op=viewtopic&...
and Slideshow</ulink>" thread in the RichFaces users forum contains an
information and code on making a Slide Show with the help of the <emphasis
role="bold"><property><a4j:poll></property></emphasis>
component;
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Manage the <ulink
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
Users Forum</ulink> for fresh issues about the component usage.
+ </para>
+ </section>
- </section>
-
</chapter>