<?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>

      <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>&lt;a4j:poll&gt;</property>
      </emphasis> component defined this way every second submits Ajax form onto the server,
      performs the corresponding action and renders a components with the <emphasis>
        <property>&quot;someDataTable&quot;</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;
...
AjaxPoll myPoll = new AjaxPoll();
...]]></programlisting>

      </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&apos;s necessary to set an update interval. 
                  The <emphasis><property>&quot;interval&quot;</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>&quot;interval&quot;</property></emphasis> attribute value and server response time. 
                  Default value for <emphasis><property>&quot;interval&quot;</property></emphasis> attribute is set to &quot;1000&quot; milliseconds (1 second). 
                  See an example of definition in the &quot;<link linkend="creating">Creating the component with a Page Tag</link>&quot; section. 
            </para>
            <para>
                  The <emphasis><property>&quot;timeout&quot;</property></emphasis> attribute defines response waiting time in milliseconds. 
                  If a response isn&apos;t received during this period a connection is aborted and the next request is sent. 
                  Default value for <emphasis><property>&quot;timeout&quot;</property></emphasis> attribute isn&apos;t set.
            </para>
            
            <para>
                  The <emphasis><property>&quot;enabled&quot;</property></emphasis> attribute defines should the <emphasis role="bold"><property>&lt;a4j:poll&gt;</property></emphasis> send request or not. 
                  It&apos;s necessary to render the <emphasis role="bold"><property>&lt;a4j:poll&gt;</property></emphasis> to apply the current value of <emphasis><property>&quot;enabled&quot;</property></emphasis> attribute. 
                  You can use an EL-expression for <emphasis><property>&quot;enabled&quot;</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>&quot;reRender&quot;</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>&quot;enabled&quot;</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[<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>&quot;process&quot;</property></emphasis> attribute usage you can find &quot;<link linkend="process">Decide what to process</link>&quot; guide section.
            </para>
  </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>
                              &quot;<ulink url="http://www.jboss.org/community/wiki/CreateABannerUsingEffectsAndPoll">Create a Banner Using Effects and Poll</ulink>&quot; 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>
                              &quot;<ulink url="http://www.jboss.org/community/wiki/CreateAHTMLBannerUsingEffectsAndPoll">Create an HTML Banner Using Effects and Poll</ulink>&quot; 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>
                              &quot;<ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewtopic&amp;t=125621">RichFaces and Slideshow</ulink>&quot; 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>

</chapter>
