<section role="NotInToc" id="a4j_ajaxListener">
    <title>
        &lt;
        a4j:ajaxListener
        &gt;
        <emphasis role="since">
            <superscript>available since
                <emphasis role="version">3.0.0</emphasis>
            </superscript>
        </emphasis>
    </title>
    <section>
        <title>Description</title>
        <para>The
            <emphasis role="bold">
                <property>&lt;a4j:ajaxListener&gt;</property>
            </emphasis>
            component adds an action listener to a parent component and works like the
            <emphasis role="bold">
                <property>&lt;f:actionListener&gt;</property>
            </emphasis>
            or
            <emphasis role="bold">
                <property>&lt;f:valueChangeListener&gt;</property>
            </emphasis>
            JSF components
            but for the whole Ajax container.
        </para>
    </section>
    <section>
        <title>Details of Usage</title>
        <para>The
            <emphasis role="bold">
                <property>&lt;a4j:ajaxListener&gt;</property>
            </emphasis>
            component adds an action listener to a parent component.
            That listener is invoked on each Ajax request during the &quot;Render Response&quot; JSF phase.
            In comparison with standard JSF
            <emphasis role="bold">
                <property>&lt;f:actionListener&gt;</property>
            </emphasis>
            and
            <emphasis role="bold">
                <property>&lt;f:valueChangeListener&gt;</property>
            </emphasis>
            components the invocation of the
            <emphasis role="bold">
                <property>&lt;a4j:ajaxListener&gt;</property>
            </emphasis>
            is not skipped in case when validation of &quot;Update Model&quot; fails.
            The
            <emphasis role="bold">
                <property>&lt;a4j:ajaxListener&gt;</property>
            </emphasis>
            is guarantied to be invoked for each Ajax response.
        </para>
        <para>
            The
            <emphasis>
                <property>&quot;type&quot;</property>
            </emphasis>
            attribute defines the fully qualified Java class name for the listener.
            This Java class should implement
            <code>
                <ulink url="&apidoc_framework;org/ajax4jsf/event/AjaxListener.html">
                    <property>org.ajax4jsf.event.AjaxListener</property>
                </ulink>
            </code>
            interface which is base interface for all listeners, capable for receiving Ajax events.
            The object on which the Event initially occurred could be accessed using the
            <code>
                <ulink url="http://java.sun.com/j2se/1.4.2/docs/api/java/util/EventObject.html">
                    <property>java.util.EventObject.getSource()</property></ulink></code>
            method.
        </para>
        <para>
            The
            <emphasis role="bold">
                <property>&lt;a4j:ajaxListener&gt;</property>
            </emphasis>
            is not invoked for non-Ajax requests and when RichFaces works in the "Ajax Request
            generates Non-Ajax Response" mode, so
            <emphasis role="bold">
                <property>&lt;a4j:ajaxListener&gt;</property>
            </emphasis>
            invocation is a good indicator that Ajax
            Response is going to be processed. Let&apos;s check it in the following example.
        </para>

        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>

        <programlisting role="XML"><![CDATA[...
<rich:messages/>
<h:form id="form">
    <a4j:commandLink value="Click to send Ajax request">
        <a4j:ajaxListener type="org.docs.richfaces.actionListenerBean"/>
    </a4j:commandLink>
</h:form>
...]]></programlisting>

        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>

        <programlisting role="JAVA"><![CDATA[...
public class ActionListenerBean implements org.ajax4jsf.event.AjaxListener {
    public void processAjax(AjaxEvent event) {
        FacesContext.getCurrentInstance().addMessage("form", new FacesMessage("Ajax request is sent"));
    }
}        
...]]></programlisting>
        <para>
            There is a result:
        </para>
        <figure>
            <title>
                Usage of the
                <emphasis role="bold">
                    <property>&lt;a4j:ajaxListener&gt;</property>
                </emphasis>
            </title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/ajaxListener.png"/>
                </imageobject>
            </mediaobject>
        </figure>


    </section>
    <section>
        <title>Reference Data</title>
        <para>
            <ulink url="&tlddoc;a4j/ajaxListener.html">Table of
                &lt;a4j:ajaxListener&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>listener-class</entry>
                        <entry>org.ajax4jsf.event.AjaxListener</entry>
                    </row>
                    <row>
                        <entry>event-class</entry>
                        <entry>org.ajax4jsf.event.AjaxEvent</entry>
                    </row>

                    <row>
                        <entry>tag-class</entry>
                        <entry>org.ajax4jsf.taglib.html.jsp.AjaxListenerTag</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </section>
    <section>
        <title>Relevant Resources Links</title>
        <para>
            Visit
            <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/ajaxListener.jsf?c=ajaxListener">
                AjaxListener</ulink>
            page at RichFaces Livedemo for examples of component usage and their sources.
        </para>
        <para>
            Check Sun JSF TLD documentation for more information on
            <ulink
                url="http://java.sun.com/javaee/javaserverfaces/1.1_01/docs/tlddocs/f/valueChangeListener.html">&lt;f:valueChangeListener&gt;
            tag</ulink>.
        </para>
    </section>
</section>
