<?xml version='1.0' encoding='UTF-8'?>
<chapter>

  <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>Dynamical creation of a component from Java code</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>
                <h:outputText value="Polling Active" rendered="#{userBean.pollEnabled}"></h:outputText>
                <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> The form around the <emphasis role="bold">
      <property>&lt;a4j:poll&gt;</property>
      </emphasis> component is required.</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-->

  </section>

  <section>
    <title>Relevant resources links</title>

    <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/poll.jsf?c=poll"
      >Here</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 aditional information about component usage you can find here : <ulink
        url="http://jboss.com/index.html?module=bb&amp;op=viewtopic&amp;t=103909">RichFaces
        Users Forum</ulink>.</para>

  </section>

</chapter>
