Author: atsebro Date: 2009-06-04 13:27:01 -0400 (Thu, 04 Jun 2009) New Revision: 14510 Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ajaxListener.desc.xml branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ajaxListener.xml Log: RF-7080: Editing a note about ajaxPortlet Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ajaxListener.desc.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ajaxListener.desc.xml 2009-06-04 17:26:12 UTC (rev 14509) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ajaxListener.desc.xml 2009-06-04 17:27:01 UTC (rev 14510) @@ -1,14 +1,24 @@ -<?xml version='1.0' encoding='UTF-8'?> -<chapter> +<?xml version="1.0" encoding="UTF-8"?> <section> - <sectioninfo> - <keywordset> - <keyword>a4j:ajaxListener</keyword> - </keywordset> - </sectioninfo> - <title>Description</title> - <para>The <emphasis role="bold"><property>&lt;a4j:ajaxListener&gt;</property></emphasis> - component is the same one as <emphasis role="bold"><property>&lt;f:actionListener&gt;</property></emphasis> - or <emphasis role="bold"><property>&lt;f:valueChangeListener&gt;</property></emphasis>, but for an Ajax container.</para> + <sectioninfo> + <keywordset> + <keyword>a4j:ajaxListener</keyword> + </keywordset> + </sectioninfo> + + <section> + <title>Description</title> + <para>The component adds an action listener to a parent component to provide possibility of Ajax update. + It 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>Key Features</title> + <itemizedlist> + <listitem><para>The listener is invoked for Ajax requests only</para></listitem> + <listitem><para>The listener is always guaranteed to be invoked</para></listitem> + </itemizedlist> + </section> </section> -</chapter> \ No newline at end of file Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ajaxListener.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ajaxListener.xml 2009-06-04 17:26:12 UTC (rev 14509) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ajaxListener.xml 2009-06-04 17:27:01 UTC (rev 14510) @@ -1,10 +1,10 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter> - <chapterinfo> +<section> + <sectioninfo> <keywordset> <keyword>a4j:ajaxListener</keyword> </keywordset> - </chapterinfo> + </sectioninfo> <table> <title>Component identification parameters </title> <tgroup cols="2"> @@ -35,27 +35,27 @@ <section> - <title>Creating on a page</title> - <para>To create the simplest variant on a page use the following syntax:</para> + <title>Creating the Component with a Page Tag</title> + <para>To create the simplest variant of the <emphasis role="bold"><property>a4j:ajaxListener</property></emphasis> component on a page use the following syntax:</para> <para> <emphasis role="bold">Example:</emphasis> </para> <programlisting role="XML"><![CDATA[... - <a4j:ajaxListener type="demo.Bean"/> -... -]]></programlisting> +<a4j:ajaxListener type="demo.Bean"/> +...]]></programlisting> </section> - <section> - <title>Creating the Component Dynamically Using Java</title> - <para> - <emphasis role="bold">Example:</emphasis></para> - <programlisting role="JAVA"><![CDATA[package demo; +<section> + <title>Creating the Component Dynamically Using Java</title> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="JAVA"><![CDATA[package demo; public class ImplBean implements import org.ajax4jsf.event.AjaxListener{ - ... +... } ]]></programlisting> @@ -66,20 +66,32 @@ </section> - <section> - <title>Key attributes and ways of usage</title> - <para> -Additional to the listeners provided by JSF specification, RichFaces add one more: ajax Listener ( - <emphasis role="bold"><property>&lt;a4j:ajaxListener&gt;</property> - </emphasis>). - Ajax Listener is invoked before the Render Response phase. Instead of <emphasis role="bold"><property>&lt;f:actionListener&gt;</property></emphasis> of <emphasis role="bold"><property>&lt;f:valueChangeListener&gt;</property></emphasis> which are not -invoked when Validation of Update Model phases failed, ajax Listener is guarantied to be invoked for each Ajax response. Thus, it is -a good place for update the list of re-rendered components, for example. -Ajax Listener is not invoked for non-Ajax request and when RichFaces works in "Ajax Request generates -Non-Ajax Response" mode. Therefore, ajax Listener invocation is a good indicator that Ajax response is going to be processed. -Attribute <emphasis><property>&quot;type&quot;</property></emphasis> described in the following <link linkend="ajaxListener"> chapter</link>. It defines the fully qualified Java class name for listener. This class implements - <ulink url="http://www.jboss.org/file-access/default/members/jbossrichfaces.... You can access to the source of the event (Ajax component) using <code>java.util.EventObject.getSource() </code> call. - </para> + <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, which needs to be provided with Ajax support. + That listener is invoked on each Ajax request during the &quot;Render Response&quot; JSF phase. + In comparison with JSF <emphasis role="bold"><property>&lt;f:actionListener&gt;</property></emphasis> and <emphasis role="bold"><property>&lt;f:valueChangeListener&gt;</property></emphasis> + the invocation of the <emphasis role="bold"><property>&lt;a4j:ajaxListener&gt;</property></emphasis> is not skipped in case when validation of Update Model fails. + The <emphasis role="bold"><property>&lt;a4j:ajaxListener&gt;</property></emphasis> is guarantied to be invoked for each Ajax response. + </para> + + <note> + <para> + Ajax listener is not invoked for non-Ajax requests and when RichFaces works in the &quot;Ajax Request generates Non-Ajax Response&quot; mode. + </para> + </note> + +<para> + As example of the <emphasis role="bold"><property>&lt;a4j:ajaxListener&gt;</property></emphasis> component usage one can cite an updating the list of re-rendered components. +</para> + +<para> + The <emphasis><property>&quot;type&quot;</property></emphasis> attribute defines the fully qualified Java class name for the listener. + This Java class implements <code><ulink url="http://www.jboss.org/file-access/default/members/jbossrichfaces..., which is base interface for all listeners, capable for receiving Ajax events. + The source of the event could be accessed using the <code><ulink url="http://java.sun.com/j2se/1.4.2/docs/api/java/util/EventObject.h... call. +</para> + + <para> <emphasis role="bold">Example:</emphasis> @@ -87,7 +99,7 @@ <programlisting role="XML"><![CDATA[... <a4j:commandLink id="cLink" value="Click it To Send Ajax Request"> - <a4j:ajaxListener type="demo.Bean"/> + <a4j:ajaxListener type="demo.Bean"/> </a4j:commandLink> ...]]></programlisting> @@ -110,12 +122,11 @@ <section> <title>Relevant resources links</title> - <para> - Some additional information about usage of component can be found on - <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/ajaxListene... Live Demo page</ulink>.</para> - <para> - More information about <emphasis role="bold"><property>&lt;f:valueChangeListener&gt;</property></emphasis> can be found <ulink url=" http://java.sun.com/javaee/javaserverfaces/1.1_01/docs/tlddocs/f/valueCha... Sun JSF TLD documentation </ulink>. - </para> + <para> + Vizit <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/ajaxListene... 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/... tag</ulink>. + </para> </section> - -</chapter> \ No newline at end of file +</section> \ No newline at end of file