<?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 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"/>
]]></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>Key attributes and ways 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 <link linkend="creating">&quot;Creating on a page&quot; section</link>. </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 <link
        linkend="attributes">mentioned above attributes</link> 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 for <emphasis role="bold">
        <property>&lt;a4j:poll&gt;</property>
      </emphasis> contains value of its own Id. Hence, it renders itself for applying the current value
      of <emphasis>
        <property>&quot;enabled&quot;</property>
      </emphasis> attribute.</para>

    <note><title>Note:</title><para> The form around the <emphasis role="bold">
      <property>&lt;a4j:poll&gt;</property>
      </emphasis> component is required.</para></note>
	  
	  <note>
	  <title>Note:</title>
	  <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>
	  </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 <link linkend="process">&quot; Decide what to process &quot; </link> guide section.
    </para>
  </section>

  <section>
  	<title>Relevant resources links</title>
  	<para>In
  		<ulink
  			url="http://wiki.jboss.org/wiki/CreateABannerUsingEffectsAndPoll">
  		  RichFaces Wiki article &quot;Creating a Banner Using Effects and Poll&quot;
  		</ulink>
  		you can get additional information 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 and also you can figure out how to create an HTML banner  in 
  		<ulink
  			url="http://wiki.jboss.org/auth/wiki/CreateAHTMLBannerUsingEffectsAndPoll">
  		  RichFaces Wiki article &quot;Creating an HTML Banner Using Effects and Poll&quot;
  		</ulink>
  		.
  	</para>
    <para>In
      <ulink url="http://wiki.jboss.org/auth/wiki/RichFacesCookbook/SlideShow">RichFaces  Cookbook article on Slide Show"</ulink>
      you can find information how to make a Slide Show with help of the
      <emphasis role="bold">
        <property>&lt;rich:effect&gt;</property></emphasis>
      and <emphasis role="bold">
        <property>&lt;a4j:poll&gt;</property>
      </emphasis> components.
    </para>
  	<para>On 
  		<ulink
  			url="http://livedemo.exadel.com/richfaces-demo/richfaces/poll.jsf?c=poll">
  			RichFaces Live Demo page
  		</ulink>
  		you can see the example of
  		<emphasis role="bold">
  			<property>&lt;a4j:poll&gt;</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&amp;op=viewtopic&amp;t=103909">
  			RichFaces Users Forum
  		</ulink>
  		.
  	</para>

  </section>

</chapter>
