<section role="NotInToc" id="a4j_poll">
   <title>
				&lt;
				a4j:poll
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.0.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section id="poll_d">
        <sectioninfo>
            <keywordset>
                <keyword>a4j:poll</keyword>
                <keyword>component</keyword>
            </keywordset>
        </sectioninfo>
        
        <title>Description</title>
        <para>The <emphasis role="bold">
                <property>&lt;a4j:poll&gt;</property>
            </emphasis> component allows periodical sending of Ajax requests to a server and is
            used for a page updating according to a specified time interval.</para>
    </section>
   <section>
            <title>Details of Usage</title>
            <para id="attributes">
                  The <emphasis role="bold">
            <property>&lt;a4j:poll&gt;</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>&lt;a4j:poll&gt;</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>&lt;a4j:poll&gt;</property>
         </emphasis> send request or not. 
                  It's necessary to render the <emphasis role="bold">
            <property>&lt;a4j:poll&gt;</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>

      <programlisting role="XML"><![CDATA[...
<a4j:region>
      <h:form>
            <a4j:poll id="poll" interval="1000" enabled="#{userBean.pollEnabled}" reRender="poll,grid"/>
      </h:form>
</a4j:region>
<h:form>
      <h:panelGrid columns="2" width="80%" id="grid">
           <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>
          </h:panelGrid>
          <h:outputText id="serverDate" style="font-size:16px" value="Server Date: #{userBean.date}"/>
    </h:panelGrid>
</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>&lt;a4j:poll&gt;</property>
         </emphasis> componet sends requests to the server every second. 
          <emphasis>
            <property>"reRender"</property>
         </emphasis> attribute of the <emphasis role="bold">
            <property>&lt;a4j:poll&gt;</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>Notes:</title>
	        <itemizedlist>
	           <listitem>
	              <para>
	                    The form around the <emphasis role="bold">
                     <property>&lt;a4j:poll&gt;</property>
                  </emphasis> component is required.
	              </para>
	           </listitem>
	        
	           <listitem>
	              <para>
	                    To make the <emphasis role="bold">
                     <property>&lt;a4j:poll&gt;</property>
                  </emphasis> component send requests periodically when it <code>limitToList</code> is set to "true", 
	                    pass the <emphasis role="bold">
                     <property>&lt;a4j:poll&gt;</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
      (Some request parameters)). </para>
    <para> The timer could be stopped or started in any time. The current state is controlled on the
      component with the <emphasis>
        <property>"enabled"</property>
      </emphasis> attribute: </para>
    <programlisting role="XML"><![CDATA[<![CDATA[<a4j:poll interval="1000" enabled="#{bean.boolProperty}"/>
]]>]]></programlisting>
    <para>As any RichFaces Action component, <emphasis role="bold">
        <property>&lt;a4j:poll&gt;</property>
      </emphasis> has all described in the <emphasis role="bold">
        <property>
          <ulink url="index.html#support">&lt;a4j:support&gt;</ulink>
        </property>
      </emphasis> chapter attributes to provide the necessary behavior of request sending (delay,
      limitation of a submit and render area, requests frequency, and etc.). For detailed
      information on these attributes see again the <emphasis role="bold">
        <property>
          <ulink url="index.html#support">&lt;a4j:support&gt;</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>
  </section>
   <section>
      <title>Reference Data</title>
      <para>
         <ulink url="&tlddoc;a4j/poll.html">Table of 
							&lt;a4j:poll&gt; 
							 attributes</ulink>.
						</para>
      <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>
   <section>
            <title>Relevant Resources Links</title>
            <para>
                  Visit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/poll.jsf?c=poll">Poll 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/CreateABannerUsingEffectsAndPoll">Create 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>&lt;rich:effect&gt;</property>
               </emphasis> and <emphasis role="bold">
                  <property>&lt;a4j:poll&gt;</property>
               </emphasis>components;   
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              "<ulink url="http://www.jboss.org/community/wiki/CreateAHTMLBannerUsingEffectsAndPoll">Create 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>&lt;rich:effect&gt;</property>
               </emphasis> and <emphasis role="bold">
                  <property>&lt;a4j:poll&gt;</property>
               </emphasis>components;   
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              "<ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewtopic&amp;t=125621">RichFaces 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>&lt;a4j:poll&gt;</property>
               </emphasis> component;
                         </para>
                  </listitem>
            </itemizedlist> 
            <para>
                  Manage the <ulink url="http://jboss.com/index.html?module=bb&amp;op=viewtopic&amp;t=103909">RichFaces Users Forum</ulink> for fresh issues about the component usage.
            </para>
      </section>
</section>
