[richfaces-svn-commits] JBoss Rich Faces SVN: r2073 - in trunk/docs/userguide/en/src/main/docbook: included and 1 other directories.

Author: smukhina Date: 2007-08-06 09:07:23 -0400 (Mon, 06 Aug 2007) New Revision: 2073 Added: trunk/docs/userguide/en/src/main/docbook/included/actionparam.desc.xml trunk/docs/userguide/en/src/main/docbook/included/actionparam.xml trunk/docs/userguide/en/src/main/docbook/included/ajaxListener.desc.xml trunk/docs/userguide/en/src/main/docbook/included/ajaxListener.xml trunk/docs/userguide/en/src/main/docbook/included/commandButton.desc.xml trunk/docs/userguide/en/src/main/docbook/included/commandButton.xml trunk/docs/userguide/en/src/main/docbook/included/commandLink.desc.xml trunk/docs/userguide/en/src/main/docbook/included/commandLink.xml trunk/docs/userguide/en/src/main/docbook/included/form.desc.xml trunk/docs/userguide/en/src/main/docbook/included/form.xml trunk/docs/userguide/en/src/main/docbook/included/htmlCommandLink.desc.xml trunk/docs/userguide/en/src/main/docbook/included/htmlCommandLink.xml trunk/docs/userguide/en/src/main/docbook/included/include.desc.xml trunk/docs/userguide/en/src/main/docbook/included/include.xml trunk/docs/userguide/en/src/main/docbook/included/jsFunction.desc.xml trunk/docs/userguide/en/src/main/docbook/included/jsFunction.xml trunk/docs/userguide/en/src/main/docbook/included/keepAlive.desc.xml trunk/docs/userguide/en/src/main/docbook/included/keepAlive.xml trunk/docs/userguide/en/src/main/docbook/included/listener.desc.xml trunk/docs/userguide/en/src/main/docbook/included/loadBundle.desc.xml trunk/docs/userguide/en/src/main/docbook/included/loadBundle.xml trunk/docs/userguide/en/src/main/docbook/included/loadScript.desc.xml trunk/docs/userguide/en/src/main/docbook/included/loadScript.xml trunk/docs/userguide/en/src/main/docbook/included/loadStyle.desc.xml trunk/docs/userguide/en/src/main/docbook/included/loadStyle.xml trunk/docs/userguide/en/src/main/docbook/included/log.desc.xml trunk/docs/userguide/en/src/main/docbook/included/log.xml trunk/docs/userguide/en/src/main/docbook/included/mediaOutput.desc.xml trunk/docs/userguide/en/src/main/docbook/included/mediaOutput.xml trunk/docs/userguide/en/src/main/docbook/included/outputPanel.desc.xml trunk/docs/userguide/en/src/main/docbook/included/outputPanel.xml trunk/docs/userguide/en/src/main/docbook/included/page.desc.xml trunk/docs/userguide/en/src/main/docbook/included/page.xml trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml trunk/docs/userguide/en/src/main/docbook/included/poll.xml trunk/docs/userguide/en/src/main/docbook/included/portlet.desc.xml trunk/docs/userguide/en/src/main/docbook/included/portlet.xml trunk/docs/userguide/en/src/main/docbook/included/push.desc.xml trunk/docs/userguide/en/src/main/docbook/included/push.xml trunk/docs/userguide/en/src/main/docbook/included/region.desc.xml trunk/docs/userguide/en/src/main/docbook/included/region.xml trunk/docs/userguide/en/src/main/docbook/included/repeat.desc.xml trunk/docs/userguide/en/src/main/docbook/included/repeat.xml trunk/docs/userguide/en/src/main/docbook/included/status.desc.xml trunk/docs/userguide/en/src/main/docbook/included/status.xml trunk/docs/userguide/en/src/main/docbook/included/support.desc.xml trunk/docs/userguide/en/src/main/docbook/included/support.xml Modified: trunk/docs/userguide/en/src/main/docbook/master.xml trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml Log: http://jira.jboss.com/jira/browse/RF-522 Guides chapters merging Added: trunk/docs/userguide/en/src/main/docbook/included/actionparam.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/actionparam.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/actionparam.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,17 @@ +<?xml version='1.0' encoding='UTF-8'?> +<section> + <para>The <emphasis role="bold"> + <property>&lt;a4j:actionparam&gt;</property> + </emphasis> component combines the functionality of both JSF components: <emphasis role="bold"> + <property>&lt;f:param&gt;</property> + </emphasis> and <emphasis role="bold"> + <property>&lt;f:actionListener&gt;</property> + </emphasis>.</para> + <para>More information about <emphasis role="bold"> + <property>&lt;f:param&gt;</property> + </emphasis> and <emphasis role="bold"> + <property>&lt;f:actionListener&gt;</property> + </emphasis> can be found <ulink + url="http://java.sun.com/javaee/javaserverfaces/1.2/docs/tlddocs/ind... + >here</ulink>.</para> +</section> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/actionparam.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/actionparam.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/actionparam.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,95 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + <para> + <table frame="all"> + <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.ajax.ActionParameter</entry> + </row> + <row> + <entry>component-family</entry> + <entry> </entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlActionParameter</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry> </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <section> + <title>Creating on a page</title> + <para>Simple component definition example:</para> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<a4j:actionParam noEscape="true" name="param1" value="getMyValue()" assignTo="#{bean.prop1}" />]]></programlisting> + </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.ajax.html.HtmlActionParameter; +... +HtmlActionParameter myActionParameter = new HtmlActionParameter(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The component <emphasis role="bold"> + <property>&lt;a4j:actionparam&gt;</property> + </emphasis> is a combination of the functionality of two JSF tags: <emphasis role="bold"> + <property>&lt;f:param&gt;</property> + </emphasis> and <emphasis role="bold"> + <property>&lt;f:actionListener&gt;</property> + </emphasis>.</para> + <para>At the render phase, it's decoded by parent component (<emphasis role="bold"> + <property>&lt;h:commandLink&gt;</property> + </emphasis> or like) as usual. At the process request phase, if the parent component + performs an action event, update the value specified in the &quot;assignTo&quot; + attribute as its value. If a converter attribute is specified, use it to encode and + decode the value to a string stored in the html parameter.</para> + <para><emphasis role="bold"> + <property>&lt;a4j:actionparam&gt;</property> + </emphasis>has a &quot;noEscape&quot; attribute. If it is set to + &quot;true&quot;, the value will be evaluated as a JavaScript code. </para> + <emphasis role="bold">Example:</emphasis> + <programlisting role="XML"><![CDATA[... + <script> + ... + var foo = "bar"; + ... + </script> + ... + <a4j:actionParam noEscape="true" name="param1" value="foo" assignTo="#{bean.prop1}" /> +...]]></programlisting> + <para> + The <emphasis role="bold"><property>&lt;a4j:param&gt;</property></emphasis> extends + <emphasis role="bold"><property>&lt;f:param&gt;</property></emphasis>, so the "name" attribute is mandatory. + Otherwise, the value will be missing due missing the request parameter name for it. + </para> + </section> + + <section> + <title>Relevant resources links</title> + <para>More information can be found on the <ulink + url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&... + >Ajax4JSF Users Forum</ulink>.</para> + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/ajaxListener.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/ajaxListener.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/ajaxListener.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,5 @@ +<?xml version='1.0' encoding='UTF-8'?> +<section> + <para>The <emphasis role="bold"><property>&lt;a4j:ajaxListener&gt;</property></emphasis> +component is the same one as &quot;ActionListener&quot; or &quot;ValueChangeListener&quot;, but for an AJAX container.</para> +</section> Added: trunk/docs/userguide/en/src/main/docbook/included/ajaxListener.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/ajaxListener.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/ajaxListener.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,74 @@ +<?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.Listener</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.Listener</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.component.html.AjaxListener</entry> + </row> + + </tbody> + </tgroup> + </table> + + <!-- + <section> + <title>Creating on a page</title> + <para>Simple Component definition on a page:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + + <programlisting role="XML"><![CDATA[<a4j:ajaxListenet type=""/> +]]></programlisting> + </section> + --> + + <section> + <title>Dynamical creation of a component from Java code</title> + + <para> + <emphasis role="bold">Example:</emphasis> + <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.AjaxListener; +... +AjaxListener myListener = new AjaxListener(); +... + ]]></programlisting> + </para> + </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 Action Listener of Value Change Listener which are not +invoked when Validation of Update Model phases failed, Ajax Listener is guarantied to be invoked for each Ajax response. So, 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 'type' defines the fully qualified Java class name for listener. This class should implement org.ajax4jsf.events.AjaxListener interface. +You can access to the source of the event (Ajax component) using event.getSource() call. + </para> + + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/commandButton.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/commandButton.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/commandButton.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:commandButton&gt;</property> + </emphasis>component is very similar to the<emphasis role="bold"> + <property>&lt;h:commandButton&gt;</property> + </emphasis>component, the only difference is that an AJAX form submit is generated on a click and it allows dynamic rerendering after a response comes back. It&apos;s not necessary to plug any support into the component, as AJAX support is already built in.</para> +</section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/commandButton.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/commandButton.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/commandButton.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,63 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + <para><table frame="all"> + <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.ajax.CommandButton</entry> + </row> + <row> + <entry>component-family</entry> + <entry>javax.faces.Command </entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlCommandButton</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxCommandButtonRenderer </entry> + </row> + </tbody> + </tgroup> + </table></para> + <section> + <title>Creating on a page</title> + <para><emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> is used in the same way as <emphasis role="bold"><property>&lt;h:commandButton&gt;</property></emphasis>, but with definition of the area that is updated after the response comes back from the server.</para> + <programlisting role="XML"><![CDATA[<a4j:commandButton reRender="someData" action="#{bean.action1}" value="Link"/>]]></programlisting> + <para>This definition of the component provides a link, a click on the link causes an AJAX form submit on the server, &quot;action1&quot; method performance, and rendering of the component with &quot;someData&quot; id after the response comes back from the server.</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.ajax.html.HtmlAjaxCommandButton; +... +HtmlAjaxCommandButton myButton = new HtmlAjaxCommandButton(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The component <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> placed on a page generates the following HTML code:</para> + <programlisting role="XHTML"><![CDATA[<input type="submit" onclick="A4J.AJAX.Submit(...request parameters);return false;" value="sort"/> +]]></programlisting> + <para>Hence, the utility method &quot;A4J.AJAX.Submit&quot; is called on a click, the method performs AJAX request as the <emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> component</para> + <note> + <title>Note:</title> + <para>AJAX support is built in and it&apos;s not necessary to add nested <emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> to the component.</para> + </note> + <para>Common JSF navigation could be performed after an AJAX submit and partial rendering, but Navigation Case must be defined as <emphasis role="bold"><property>&lt;redirect/&gt;</property></emphasis> in order to avoid problems with some browsers.</para> + <para>As any Ajax4jsf component sending AJAX requests and processing server responses <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis> has all attributes described above (see <emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> chapter) that provide the required behavior of requests sending (delay, limitation of submit area and rendering, and etc.)</para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/commandLink.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/commandLink.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/commandLink.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> +<section> +<title>Description</title> + <para> The <emphasis role="bold"> + <property>&lt;a4j:commandLink&gt;</property> + </emphasis>component is very similar to the <emphasis role="bold"> + <property>&lt;h:commandLink&gt;</property> + </emphasis> component, the only difference is that an AJAX form submit is generated on a click and it allows dynamic rerendering after a response comes back. It&apos;s not necessary to plug any support into the component, as AJAX support is already built in.</para> +</section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/commandLink.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/commandLink.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/commandLink.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,72 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + + <para><table frame="all"> + <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.ajax.CommandLink</entry> + </row> + <row> + <entry>component-family</entry> + <entry>javax.faces.Command </entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlCommandLink</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxCommandLinkRenderer </entry> + </row> + </tbody> + </tgroup> + </table></para> + + <section> + <title>Creating on a page</title> + <para><emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis> is used in the same way as <emphasis role="bold"><property>&lt;h:commandLink&gt;</property></emphasis>, but with definition of the area that is updated after the response comes back from the server.</para> + <programlisting role="XML"><![CDATA[<a4j:commandLink reRender="someData" action="#{bean.action1}" value="Link"/>]]></programlisting> + <para>This definition of the component provides a link, and a click on the link causes an AJAX form + submit on the server, &quot;action1&quot; method performance, and rendering of the component + with &quot;someData&quot; id after the response comes back from the server.</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.ajax.html.HtmlAjaxCommandLink; +... +HtmlAjaxCommandLink myLink = new HtmlAjaxCommandLink(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The component <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis> placed on a page generates the following HTML code:</para> + <programlisting role="JSP"><![CDATA[<a href="#" onclick="A4J.AJAX.Submit(?"request parameters"); + return + <a href="#" onclick="A4J.AJAX.Submit(?"request parameters"); + return false;"> + <span style="color: black;">Link Value</span> + </a> +]]></programlisting> + <para>Hence, the utility method &quot;A4J.AJAX.Submit&quot; is called on a click, the method performs AJAX request as the <emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> component</para> + <note> + <title>Note:</title> + <para>AJAX support is built in and it&apos;s not necessary to add nested <emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> to the component.</para> + </note> + <para>Common JSF navigation could be performed after AJAX submit and partial rendering, but Navigation Case must be defined as <emphasis role="bold"><property>&lt;redirect/&gt;</property></emphasis> in order to avoid problems with some browsers.</para> + <para>As any Ajax4jsf component sending AJAX requests and processing server responses <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis> has all attributes described above (see <emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> chapter) that provide the required behavior of requests sending (delay, limitation of submit area and rendering, etc.)</para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/form.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/form.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/form.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + <section> + <title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:form&gt;</property> + </emphasis> component is very similar to the same component from the JSF HTML library, the only slight difference is in generation of links inside and possibility of AJAX by-default submission.</para> + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/form.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/form.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/form.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,87 @@ +<?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.ajax.Form</entry> + </row> + <row> + <entry>component-family</entry> + <entry>javax.faces.Form</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.AjaxForm</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.FormRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>Component definition on a page is similar to definition of the original component from JSF HTML library. </para> + <programlisting role="XML"><![CDATA[<a4j:form> + <!--...Some content to be submitted.--> +</a4j:form> +]]></programlisting> + </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.ajax.html.AjaxForm; +... +AjaxForm myForm = new AjaxForm(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The difference with the original component is that all hidden fields required for command links are always rendered and it doesn't depend on links rendering on the initial page. It solves the problem with invalid links that weren't rendered on a page immediately, but after some AJAX request.</para> + <para>Beginning with release 1.0.5 additional attributes that make this form variant universal have appeared. With a new attribute definition as ajax=<emphasis > + <property>&quot;true&quot;</property> + </emphasis>, it becomes possible to set AJAX submission way for any components inside, i.e. not a page URL is used as an <emphasis > + <property>&quot;action&quot;</property> + </emphasis> attribute, but the javascript:A4J.AJAX.Submit(...) call. In this case, rendering is defined as reRender=list of Ids for the form element itself.</para> + <para>Example</para> + <programlisting role="XML"><![CDATA[<a4j:form id="helloForm" ajaxSubmit="true" reRender="table"> + ... + <t:dataTable id="table"... > + ... + </t:dataTable> + ... + <t:dataScroller for="table"... > + ... + </t:dataScroller> + ... +</a4j:form +]]></programlisting> +<para>This example shows that in order to make <emphasis role="bold"> + <property>&lt;t:dataScroller&gt;</property> + </emphasis> submissions to be AJAX ones it's required only to place this <emphasis role="bold"> + <property>&lt;t:dataScroller&gt;</property> + </emphasis> into <emphasis role="bold"> + <property>&lt;a4j:form&gt;</property> + </emphasis>. In the other case it is necessary to redefine renders for its child links elements that are defined as <emphasis role="bold"> + <property>&lt;h:commandLink&gt;</property> + </emphasis> and can't be made AJAX ones with using e.g. <emphasis role="bold"> + <property>&lt;a4j:support&gt;</property> + </emphasis>.</para> + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/htmlCommandLink.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/htmlCommandLink.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/htmlCommandLink.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:htmlCommandLink&gt;</property> + </emphasis> component is very similar to the same component from the JSF HTML library, the only slight difference is in links generation and problem solving that occurs when an original component is used.</para> +</section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/htmlCommandLink.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/htmlCommandLink.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/htmlCommandLink.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,79 @@ +<?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>javax.faces.HtmlCommandLink</entry> + </row> + <row> + <entry>component-family</entry> + <entry>javax.faces.Command</entry> + </row> + <row> + <entry>component-class</entry> + <entry>javax.faces.component.html.HtmlCommandLink</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.HtmlCommandLinkRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>Component definition on a page is the same as for the original component from the JSF HTML library.</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<a4j:htmlCommandLink value="value" action="action"/> +]]></programlisting> +</section> + <section> + <title>Dynamical creation of a component from Java code</title> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="JAVA"><![CDATA[import javax.faces.component.html.HtmlCommandLink; +... +HtmlCommandLink myForm = new HtmlCommandLink(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The difference with the original component is that all hidden fields required for command links with the child <emphasis role="bold"> + <property>&lt;f:param&gt;</property> + </emphasis> elements are always rendered and it doesn't depend on links rendering on the initial page. It solves the problem with invalid links that weren&apos;t rendered on a page immediately, but after some AJAX request.</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<a4j:form> + ... + <a4j:htmlComandLink action="action" value="link" rendered="#{bean.rendered}"> + <f:param ...> + <a4j:htmlComandLink> + ... +</a4j:form> +]]></programlisting> +<para>In this example <emphasis role="bold"> + <property>&lt;a4j:htmlCommandLink&gt;</property> + </emphasis>works as standard <emphasis role="bold"> + <property>&lt;h:commandLink&gt;</property> + </emphasis>, but here hidden fields required for correct functionality are rendered before the first downloading of a page, though it doesn't happen if its attribute isn't set to &quot;false&quot;.</para> + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/include.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/include.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/include.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + <section> + <title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:include&gt;</property> + </emphasis> component is used for page areas update after an AJAX request according to the faces-config Navigation Rules and for implementation of wizard-like parts work in AJAX mode.</para> + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/include.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/include.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/include.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,102 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + + <para><table frame="all"> + <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.ajax.Include</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.ajax.Output</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.Include</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.AjaxIncludeRenderer</entry> + </row> + </tbody> + </tgroup> + </table></para> + + <section> + <title>Creating on a page</title> + <para>To use the component, it&apos;s necessary to place the following strings on a page:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<h:panelGroup id="wizard"> + <a4j:include viewId="/pages/include/first.xhtml" /> +</h:panelGroup> +]]></programlisting> +<para>For navigation inside a page defined in viewId any components responsible for AJAX requests to the server generation are used.</para> +<para>For example, the following component on the page &quot;/pages/include/first.xhtml&quot;</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> +<programlisting role="XML"><![CDATA[... +<a4j:commandButton action="next" reRender="wizard"/> +... +]]></programlisting> +<para>And in faces-config it's defined:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> +<programlisting role="XML"><![CDATA[<navigation-rule> + <from-view-id>/pages/include/first.xhtml</from-view-id> + <navigation-case> + <from-outcome>next</from-outcome> + <to-view-id>/pages/include/second.xhtml</to-view-id> + </navigation-case> + </navigation-rule> +]]></programlisting> +<para>In this case after a click on a button defined inside &quot;first.xhtml&quot; view, navigation is performed after an AJAX request (the same as standard JSF one) only inside this view.</para> + </section> + <section> + <title>Dynamical creation of a component from Java code</title> + <programlisting role="XML"><![CDATA[<a4j:outputPanel ajaxRendered="true"> + <a4j:include viewId="/pages/include/first.xhtml"/> +</a4j:outputPanel> +]]></programlisting> +<para>If <emphasis role="bold"> + <property>&lt;a4j:include&gt;</property> + </emphasis> is defined this way, any AJAX request returning outcome inside generates navigation with this <emphasis role="bold"> + <property>&lt;a4j:include&gt;</property> + </emphasis>.</para> +<para>Ajax Action for navigation implementation inside view must be placed inside <emphasis role="bold"> + <property>&lt;a4j:include&gt;</property> + </emphasis> pages. Navigation defined by these pages is applied to the <emphasis role="bold"> + <property>&lt;a4j:include&gt;</property> + </emphasis> element current for them.</para> +<para>As in the general case for Ajax Action component, if the <emphasis role="bold"> + <property>&lt;a4j:action&gt;</property> + </emphasis>component inside <emphasis role="bold"> + <property>&lt;a4j:include&gt;</property> + </emphasis>returns outcome defined as <emphasis role="bold"> + <property>&lt;redirect/&gt;</property>, + </emphasis> AJAX submit is performed with navigation of the whole page and not only of the current view. +</para> +</section> + + <section> + <title>Relevant resources links</title> + <para> + Some additional information can be found on the <ulink url="http://jboss.com/index.html?module=bb&amp;op=viewtopic&... Users Forum.</ulink> + </para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/jsFunction.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/jsFunction.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/jsFunction.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<root> + <section> + <title>Description</title> + <para> + The <emphasis role="bold"> + <property>&lt;a4j:jsFunction&gt;</property> + </emphasis> component allows to invoke the server side data and return it in a JSON format to use in a client JavaScript calls. + </para> + </section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/jsFunction.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/jsFunction.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/jsFunction.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,121 @@ +<?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.ajax.Function</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.components.AjaxFunction</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlAjaxFunction</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxFunctionRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>Simple component definition example:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[... +<head> + <script> + <!--There is some script named "myScript" that uses parameters which will be taken from server--> + </script> +</head> +<body> +... +<a4j:jsFunction data="#{bean.someProperty}" name="callScript" oncomplete="myScript(data.subProperty1, data.subProperty2)"/> +...]]> + </programlisting> + <para> The script &quot;myScript&quot; will be called after + <property>bean.someProperty</property> data will be returned from server(e.g. It&apos;ll + be object with two subproperties). </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.ajax.html.HtmlAjaxFunction; +... +HtmlAjaxFunction myFunction = new HtmlAjaxFunction(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para> As the component uses Ajax request to get data from server - it has all common Ajax + Action attributes. So, action and actionListener can be invoked, and reRendering some parts of + the page fired after calling function. </para> + <para> When using the <emphasis role="bold"> + <property>&lt;a4j:jsFunction&gt;</property> + </emphasis> it&apos;s possible to initiate the AJAX request from the JavaScript and + perform partial update of a page and/or invoke the JavaScript function with data returned by + AJAX response. </para> + <programlisting role="XML"><![CDATA[... +<body onload="callScript()"> + ... + <h:form> + ... + <a4j:jsFunction name="callScript" data="#{bean.someProperty1 } + "reRender="someComponent" oncomplete="myScript(data.subProperty1, data.subProperty2)"> + <a4j:actionparam name="param_name" assignTo="#{bean.someProperty2}"> + </a4j:actionparam> + </a4j:jsFunction> + ... + </h:form> + ... +</body> +...]]></programlisting> + <para> The <emphasis role="bold"> + <property>&lt;a4j:jsFunction&gt;</property> + </emphasis> allows to use <emphasis role="bold"> + <property>&lt;a4j:actionparam&gt;</property> + </emphasis> or pure <emphasis role="bold"> + <property>&lt;f:param&gt;</property> + </emphasis> for passing any number of parameters of the JavaScript function into AJAX request. + <emphasis role="bold"> + <property>&lt;a4j:jsFunction&gt;</property> + </emphasis> is similar to <emphasis role="bold"> + <property>&lt;a4j:commandButton&gt;</property> + </emphasis>, but it could be activated from the JavaScript code. It allows to invoke some + server side functionality and use the returned data in the JavaScript function invoked from + &quot;oncomplete&quot; attribute. So it&apos;s possible to use <emphasis + role="bold"> + <property>&lt;a4j:jsFunction&gt;</property> + </emphasis> instead of <emphasis role="bold"> + <property>&lt;a4j:commandButton&gt;</property> + </emphasis>. You can put it anywhere, just don&apos;t forget to use + &lt;h:form&gt; … &lt;/h:form&gt; around it. </para> + </section> + <section> + <title>Relevant resources links</title> + <para> To see how <emphasis role="bold"> + <property>&lt;a4j:jsFunction&gt;</property> + </emphasis> works on practice, look at a4j-jsFunction example from <ulink + url="http://labs.jboss.com/jbossajax4jsf/demo/index.html">he... + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/keepAlive.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/keepAlive.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/keepAlive.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<section> + <para>The <emphasis role="bold"> + <property>&lt;a4j:keepAlive&gt;</property> + </emphasis> component allows to keep a state of each bean between requests.</para> + +</section> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/keepAlive.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/keepAlive.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/keepAlive.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,91 @@ +<?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.components.KeepAlive</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.components.AjaxKeepAlive</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.components.AjaxKeepAlive</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + + <para>Simple Component definition on a page:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + <programlisting role="XML"><![CDATA[<a4j:keepAlive beanName = "#{myClass.testBean}"/>]]></programlisting> + </para> + </section> + + <section> + <title>Dynamical creation of a component from Java code</title> + + <para> + <emphasis role="bold">Example:</emphasis> + <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.ajax.AjaxKeepAlive; +... +AjaxKeepAlive myKeepAlive = new AjaxKeepAlive(); +... + ]]></programlisting> + </para> + </section> + + <section> + <title>Key attributes and ways of usage</title> + <para> + If a managed bean is declared with 'request' scope in the configuration file with the help of 'managed-bean-scope' tag then the life-time of + this bean instance is valid only for the current request. + Any attempts to make a reference to the bean instance after the request end will throw in Illegal Argument Exception by the server. + To avoid these kinds of Exception, component + <emphasis role="bold"><property>&lt;a4j:keepAlive&gt;</property> + </emphasis> is used to maintain the state of the whole bean object among subsequent request. + </para> + + <para> + <emphasis role="bold">Example:</emphasis> + <programlisting role="XML"><![CDATA[<a4j:keepAlive beanName = "#{myClass.testBean}"/>]]></programlisting> +</para> + + <para> + Note that the attribute 'beanName' must point to a legal jsf EL expression which resolves to a managed mean instance. For example for + the above code the class definition may look like this: + + <programlisting role="XML"><![CDATA[ +class MyClass{ + ... + private TestBean testBean; + // Getters and Setters for testBean. + ... +} + ]]></programlisting> +</para> + + </section> + <section> + <title>Relevant resources links</title> + <para> + Some additional information about usage of components can be found <ulink url="http://jboss.com/index.html?module=bb&amp;op=viewtopic&.... + </ulink> + </para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/listener.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/listener.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/listener.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='UTF-8'?> +<section> + <para> The <emphasis role="bold"> + <property>&lt;a4j:ajaxListener&gt;</property> + </emphasis> component is the same one as <emphasis role="bold"> + <property>&lt;f:action&gt;</property> + </emphasis> or <emphasis role="bold"> + <property>&lt;f:value&gt;</property> + </emphasis> components but it is used for an AJAX container. +</para> +</section> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/loadBundle.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/loadBundle.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/loadBundle.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<section> + <para>The <emphasis role="bold"> + <property>&lt;a4j:loadBundle&gt;</property> + </emphasis> component is similar to the same component from the JSF Core library. The component loads a resource bundle + localized for the Locale of the current view and exposes it (as a Map) in the request attributes of the current request.</para> +</section> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/loadBundle.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/loadBundle.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/loadBundle.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,85 @@ +<?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.Bundle</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.Bundle</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.component.html.AjaxLoadBundle</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + + <para>Simple component definition on a page:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + <programlisting role="XML"><![CDATA[<a4j:loadBundle baseName="demo.bundle.Messages" var="Message"/>]]></programlisting> + </para> + </section> + + <section> + <title>Dynamical creation of a component from Java code</title> + + <para> + <emphasis role="bold">Example:</emphasis> + <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.AjaxLoadBundle; +... +LoadBundle myBundle = new LoadBundle(); +... + ]]></programlisting> + </para> + </section> + + <section> + <title>Key attributes and ways of usage</title> + <para> + + <emphasis role="bold"><property>&lt;a4j:loadBundle&gt;</property> + </emphasis>allows to use reference to bundle messages during the Ajax re-rendering. +<emphasis role="bold"><property>&lt;a4j:loadBundle&gt;</property> + </emphasis> is a substitute for the +<emphasis role="bold"><property>&lt;f:loadBundle&gt;</property> + </emphasis> in JSF 1.1 which is not a JSF component originally. + +<emphasis role="bold"><property>&lt;f:loadBundle&gt;</property> + </emphasis> is a jsp tag that load the bundle messages into the request scope when page is rendered. As soon as each Ajax request +works in own request scope, the bundles loaded with +<emphasis role="bold"><property>&lt;f:loadBundle&gt;</property> + </emphasis> are unavailable. +Instead of +<emphasis role="bold"><property>&lt;f:loadBundle&gt;</property> + </emphasis> that might be located anywhere on the page, the + + <emphasis role="bold"><property>&lt;a4j:loadBundle&gt;</property> + </emphasis> should be declared inside the + + <emphasis role="bold"><property>&lt;f:view&gt;</property> + </emphasis> (this does not matter in case on using Facelets) +JSF 1.2 introduces the bundle registered in the faces-config.xml. This fixed the problem with + <emphasis role="bold"><property>&lt;f:loadBundle&gt;</property> + </emphasis>. +Therefore, you can use this JSF 1.2 way to declare your bundles. + + </para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/loadScript.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/loadScript.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/loadScript.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<root> + <section> + + <title>Description</title> + <para> + Inserts script links to the head element. Render the value of the component as the value of + the &quot;src&quot; attribute, after passing it to the getResourceURL() method of the ViewHandler for this application, and passing the result through the encodeResourceURL() method of the ExternalContext. + </para> + </section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/loadScript.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/loadScript.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/loadScript.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,71 @@ +<?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.LoadScript</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.LoadScript</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlLoadScript</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.LoadScriptRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>Simple Component definition on a page:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<a4j:loadScript src="scripts/someScript.js"/> +]]></programlisting> + </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.ajax.html.HtmlLoadScript; +... +HtmlLoadScript myScript = new HtmlLoadScript(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para> + As it was mentioned <link linkend="loadScript">before</link> this componment returns its value passing it to the + getResourceUR() method of the ViewHandler for this application, and passing + the result through the encodeResourceURL() method of the ExternalContext. + </para> + <para> + It means that the Context will be inserts automatically to the link. And calls + like <property>resource://</property> will be properly handled. + </para> + <para> + Except this - you may be free to put your script links right from the child + page while using <property>facelets templates</property> . + </para> +</section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/loadStyle.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/loadStyle.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/loadStyle.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> +<root> + <section> + <title>Description</title> + <para> + Inserts stylesheet links to the head element. Render the value of the component as the value of + the &quot;src&quot; attribute, after passing it to the getResourceURL() method of the ViewHandler for this application, and passing the result through the encodeResourceURL() method of the ExternalContext. + </para> + </section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/loadStyle.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/loadStyle.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/loadStyle.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,72 @@ +<?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.LoadStyle</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.LoadStyle</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlLoadStyle</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.LoadStyleRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>Simple Component definition on a page:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<a4j:loadStyle src="styles/style.css"/> +]]></programlisting> + </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.ajax.html.HtmlLoadStyle; +... +HtmlLoadScript myStyle = new HtmlLoadStyle(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para> + As it was mentioned <link linkend="loadStyle">before</link> this componment returns its value passing it to the + getResourceUR() method of the ViewHandler for this application, and passing + the result via the encodeResourceURL() method of the ExternalContext. + </para> + <para> + It means that the Context will be inserts automatically to the link. And calls + like <property>resource://</property> will be properly handled. + </para> + <para> + Except this - you may be free to put your stylesheet links right from the child + page while using <property>facelets templates</property> . + </para> +</section> + +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/log.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/log.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/log.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:log &gt;</property> + </emphasis> component generates JavaScript for opening of the window with client-side debug information on an AJAX request.</para> + </section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/log.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/log.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/log.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,72 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + <section> + <para><table frame="all"> + <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.ajax.Log</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.ajax.Log</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.AjaxLog</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.LogRenderer</entry> + </row> + </tbody> + </tgroup> + </table></para> + </section> + <section> + <title>Creating on a page</title> + <para>To use the component, it&apos;s necessary to place the following string on a page:</para><programlisting role="XML"><![CDATA[<a4j:log/>]]></programlisting> + <para>Then, in order to open a log window, press &quot;CTRL+SHIFT+L&quot; on a page with the component.</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.ajax.html.AjaxLog; +... +AjaxLog myLog = new AjaxLog(); +...]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>Usage of the appropriate component attributes could change a representation level of debug information as well as the hot key for a window opening.</para> + <para>The hot key could be changed with the <emphasis > + <property>&quot;hotkey&quot;</property> + </emphasis> +attribute, where it&apos;s necessary to define one letter that together with &quot;CTRL+SHIFT&quot; opens a window.</para> + <para>The <emphasis > + <property>&quot;level&quot;</property> + </emphasis> +attribute with several possible values (FATAL, ERROR, WARN, INFO, ALL) could change a logging level.</para> + <para>The log could be generated not only in a new window, but also on the current page in a separate <emphasis role="bold"><property>&lt;div&gt;</property></emphasis>, this is also controlled with the <emphasis > + <property>&quot;popup&quot;</property> + </emphasis> +attribute on the component. </para> + <para>Example:</para><programlisting role="XML"><![CDATA[<a4j:log level="ALL" popup="false" width="400" height="200"/>]]></programlisting> + <para>The component defined this way is decoded on a page as <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> inside a page, where all the information beginning with informational message is generated.</para> + <note> + <title>Note:</title> + <para><emphasis role="bold">&lt;a4j:log&gt;</emphasis> is getting renewed automatically after execution of ajax requests. Don't renew <emphasis role="bold">&lt;a4j:log&gt;</emphasis> by using reRender!</para> + </note> + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/mediaOutput.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/mediaOutput.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/mediaOutput.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:mediaOutput&gt;</property> + </emphasis> component implements one of the basic features specified in the framework. The component is a facility for generating images, video, sounds and other binary resources defined by a user on-the-fly.</para> +</section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/mediaOutput.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/mediaOutput.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/mediaOutput.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,99 @@ +<?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.MediaOutput</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.Resource</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.MediaOutput</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.MediaOutputRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>To use the component it&apos;s necessary to define it on a page and set Java methods for data keeping and data transmission to output stream. </para> + <para>Component definition on a page for graphical data output</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[... +<a4j:mediaOutput element="img" cacheable="false" session="true" + createContent="#{paintBean.paint}" value="#{paintData}" + mimeType="image/jpeg"/> +... +]]></programlisting> +<para>Here is the content of paintData that is a bean containing output data</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> +<programlisting role="JAVA"><![CDATA[package demo; + +public class PaintData implements Serializable{ + private static final long serialVersionUID = 1L; + Integer width=100; + Integer weight=50; +... +]]></programlisting> +<para>The Paint method of the paintBean class is a method transmitting graphical data into output stream.</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> +<programlisting role="JAVA"><![CDATA[public void paint(OutputStream out, Object data) throws IOException{ + <!--...Some code that puts binary data to "out" Stream--> + } +]]></programlisting> + </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.ajax.html.MediaOutput; +... +MediaOutput myMedia = new MediaOutput (); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>As it was shown in the example above there are two main components:</para> + <itemizedlist> + <listitem> + createContent specifies a method accepting 2 parameters. The first (of java.io.OutputStream type) defines a stream, where any binary data is output. The second (of java.lang.Object type) contains deserialized object with data specified in the <emphasis > + <property>&quot;value&quot;</property> + </emphasis> attribute. + </listitem> + <listitem> + Value specifies a bean class keeping data for transmitting into a method that transmits it into a stream. + </listitem> + </itemizedlist> + <note><title>Note:</title>A bean class transmitted into value should implement Serializable interface. + </note> + <para>Hence, when using the component it's possible to output user data of any type on a page with AJAX requests.</para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/outputPanel.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/outputPanel.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/outputPanel.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para>The component is used for components grouping in the AJAX output area, which offers several additional output opportunities such as inserting of non-present in tree components, saving of transient elements after AJAX request and some others.</para> +</section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/outputPanel.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/outputPanel.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/outputPanel.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,136 @@ +<?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.ajax.OutputPanel</entry> + </row> + <row> + <entry>component-family</entry> + <entry>javax.faces.Panel</entry> + </row> + <row> + <entry>component-type</entry> + <entry>org.ajax4jsf.ajax.OutputPanel</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlAjaxOutputPanel</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxOutputPanelRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>Here is the simplest way for a component creation on a page.</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<a4j:outputPanel> +<!--...Some Content Inside--> +</a4j:outputPanel> +]]></programlisting> + </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.ajax.html.HtmlAjaxOutputPanel; +... +HtmlAjaxOutputPanel myPanel = new HtmlAjaxOutputPanel(); +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para><emphasis role="bold"><property>&lt;a4j:outPanel&gt;</property></emphasis> allows marking of a page area, which is updated on Ajax response. Anyway, <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> usage is optional, as in Ajax4jsf it&apos;s possible to indicate any existing component id on a component view in order to define updating areas. + +To speed up the performance, Ajax4jsf updates only a component tree. <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> usage is recommended for wrapping components that aren&apos;t rendered during the primary non-ajax response, as the components don&apos;t present in a component tree. +</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<a4j:support ... reRender="mypanel"/> +... +<a4j:outputPanel id="mypanel"> + <h:panelGrid rendered="#{not empty foo.bar}"> + ... + </h:panelGrid> +</a4j:outputPanel> +]]></programlisting> + <para>In addition to the areas directly indicated in reRender attribute of Ajax components, <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> allows to update a part of a page basing on its own flag. The flag is defined by the ajaxRendered attribute. The flag is commonly used when a part of a page must be updated or can be updated on any response.</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<a4j:outputPanel ajaxRendered="true"> + <h:messages/> +</a4j:outputPanel> +]]></programlisting> + <para>On default <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> is output as a pair of opening and closing html <emphasis role="bold"><property>&lt;span&gt;</property></emphasis> tag, but with the help of the layout attribute this output way could be changed. There are three variants for this component value:</para> + <itemizedlist> + <listitem> + inline (default) + </listitem> + <listitem> + block + </listitem> + <listitem> + none + </listitem> + </itemizedlist> + <para>If layout=&quot;block&quot; is chosen, the component is rendered as a pair of opening and closing <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> tag, to which it’s possible to apply any available style attributes available for block tags. </para> + <para>Layout=&quot;none&quot; helps to avoid an unnecessary tag round a context that could or couldn&apos;t be rendered according to the defined &quot;rendered&quot; attribute conditions. If an inner context isn’t rendered, <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> is rendered as a <emphasis role="bold"><property>&lt;span&gt;</property></emphasis> tag with the id equal to an id of a child component and &quot;display:none&quot; style. If a child component is rendered, <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> doesn&apos;t present at all in a final code.</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<a4j:support .... reRender="mypanel"/> +... +<a4j:outputPanel layout="none"> + <h:panelGrid id="mypanel" rendered="#{not empty foo.bar}"> + ... + </h:panelGrid> +</a4j:outputPanel> +]]></programlisting> + <para>As you see, the code is very similar to the one shown above, but <emphasis ><property>&quot;reRender &quot;</property></emphasis> attribute refers directly to the updating panelGrid and not to the framing outputPanel, and it&apos;s more semantically correct.</para> + <para><emphasis role="bold"><property>&lt;a4j:outPanel&gt;</property></emphasis> should be used for non-JSF component part framing, which is to be updated on Ajax response, as Ajax4jsf specifies the list of updating areas as a list of an existing JSF component. </para> + <para>On default non-JSF context isn&apos;t saved in a component tree, but is rendered anew every time. To accelerate the processing speed and Ajax response input speed, Ajax4jsf saves non-JSF context in a component tree on default. This option could be canceled by keepTransient attribute that cancels transient flag forced setting for child components. This flag setting keeps the current value set by child components.</para> + <para>Note: In JSF 1.1 implementation and lower, where non-JSF context should be framed with the &quot;f:verbatim&quot; attribute, <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> doesn&apos;t improve this JSF implementation option in any way, so you still have to use this tag where it&apos;s necessary without Ajax4jsf usage. </para> + <para>Ajax4jsf allows setting Ajax responses rendering directly basing on component tree nodes without referring to the JSP (XHTML) page code. It could be defined by selfRendered attribute setting to <emphasis > + <property>&quot;true&quot;</property> + </emphasis> + on <emphasis role="bold"> + <property>&lt;a4j:region&gt;</property> + </emphasis> and could help considerably speed up a response output. However, if a transient flag is kept as it is, this rapid processing could cause missing of transient components that present on view and don’t come into a component tree. Hence, for any particular case you could choose a way for you application optimization: speed up processing or redundant memory for keeping tree part earlier defined a transient. </para> + </section> + <section> + <title>Relevant resources links</title> + <para> + Some additional information about usage of component can be found <ulink url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&...;. + </para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/page.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/page.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/page.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> + <section> +<title>Description</title> + <para><emphasis role="bold"><property>&lt;a4j:page&gt;</property></emphasis> is a deprecated component used for solving of incompatibility problems in early Ajax4jsf and MyFaces versions. The component encodes the full html page structure. </para> + </section> +</root> Added: trunk/docs/userguide/en/src/main/docbook/included/page.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/page.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/page.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,99 @@ +<?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.components.Page</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.components.AjaxRegion.</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.components.Page</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.PageRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>This component should be defined as a child component for <emphasis role="bold"> + <property>&lt;f:view&gt;</property> + </emphasis></para> + <programlisting role="XML"><![CDATA[<f:view> + <a4j:page> + <f:facet name="head"> + <!--...Head Content here--> + </f:facet> + <!--...Page Content here--> + </a4j:page> +</f:view> +]]></programlisting> + <para>This structure is rendered as:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<HTML> + <HEAD> + <!--...Head Content here--> + </HEAD> +<body > + <!--...Page Content Here--> +</body> +</HTML>]]></programlisting> + </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.components.Page; +... +Page myPage = new Page(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The component is mostly used to solve the following problem with MyFaces for erlier Ajax4gsf versions: in MyFaces <emphasis role="bold"> + <property>&lt;f:view&gt;</property> + </emphasis> doesn&apos;t get control over the &quot;<emphasis > + <property>RENDER_RESPONSE</property> + </emphasis>&quot; phase, thus AJAX can&apos;t get control and make a response also. To avoid this problem it was necessary to use <emphasis role="bold"> + <property>&lt;a4j:page&gt;</property> + </emphasis> on the page round the AJAX updatable area. In the last versions of both frameworks the problem is successfully fixed and no <emphasis role="bold"><property>&lt;a4j:page&gt;</property></emphasis> usage is required.</para> + <para>The component is rendered as a full HTML page template (it was shown in the example). The &quot;<emphasis > + <property>head</property> + </emphasis>&quot; section is defined with the help of the corresponding facet with the name=&quot;head&quot; and also there is an attribute with the same name for contentType definition.</para> + </section> + + <section> + <title>Relevant resources links</title> + <para>All other component functionality is the same as of <emphasis role="bold"> + &lt;a4j:region&gt;. + </emphasis> Its desctriprion could be found + <member> + <ulink url="http://webdownload.exadel.com/downloads/ajax4jsf/documentation/...;. + </member> + </para> + </section> + +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:poll&gt;</property> + </emphasis> component allows periodical sending of AJAX requests to the server and is used for a page update according to a specified in milliseconds time interval.</para> +</section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/poll.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/poll.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/poll.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,90 @@ +<?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.components.Poll</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.components.AjaxPoll</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.components.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>To use this component it&apos;s necessary only to set an update interval.</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[<a4j:poll interval="1000" reRender="someDataTable" action="#{bean.action1}"/> +]]></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.ajax.html.AjaxPoll; +... +AjaxPoll myPoll = new AjaxPoll(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The component decodes all necessary JavaScript for time count and on the expiry of some interval for calling of a Ajax4jsf 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 Ajax4jsf 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> + The aditional information about component usage you can find here:<ulink url="http://jboss.com/index.html?module=bb&amp;op=viewtopic&... Users Forum. + </ulink> + </para> + </section> + +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/portlet.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/portlet.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/portlet.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:portlet&gt;</property> + </emphasis>can be used in portals. The main component purpose is realization of possibility to create several instances the same portlet on + one page. + </para> +</section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/portlet.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/portlet.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/portlet.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,73 @@ +<?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.component.Portlet</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.component.Portlet</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.component.UIPortlet</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry></entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <programlisting role="XML"><![CDATA[ +<f:view> + <a4j:portlet> + ... + </a4j:portlet> +</f:view> +]]></programlisting> + </section> + + <section> + <title>Dynamical creation of a component from Java code</title> + <programlisting role="JAVA"><![CDATA[ +import org.ajax4jsf.ajax.component.UIPortlet; +... +UIPortlet myPortlet = new UIPortlet(); +...]]></programlisting> + </section> + + <section> + <title>Key attributes and ways of usage</title> + <para> + Portal page can include some instances of the same portlet but clientId of elements should be different for each window. + In that case 'namespace' is used for each portlet. The <emphasis role="bold"><property>&lt;a4j:portlet&gt;</property></emphasis> + implemets NaimingContainer interface and adds namespace to all componets on a page. + All portlet content should be wrapped by <emphasis role="bold"><property>&lt;a4j:portlet&gt;</property></emphasis> for resolving problems mentioned + before. + </para> + + </section> + <section> + <title>Relevant resources links</title> + <para> + The aditional information about component usage you can find here: + <ulink url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&... Users Forum. + </ulink> + </para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/push.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/push.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/push.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:push&gt;</property> + </emphasis>periodically perform AJAX request to server, to simulate 'push' data.</para> +</section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/push.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/push.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/push.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,85 @@ +<?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.components.Push</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.components.AjaxPush</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.components.AjaxPush</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxPushRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <programlisting role="XML"><![CDATA[ +<a4j:push reRender="msg" eventProducer="#{messageBean.addListener}" interval="3000"/>]]></programlisting> + </section> + + <section> + <title>Dynamical creation of a component from Java code</title> + <programlisting role="JAVA"><![CDATA[ +import org.ajax4jsf.ajax.html.AjaxPush; +... +AjaxPush myPush = new AjaxPush(); +...]]></programlisting> + </section> + + <section> + <title>Key attributes and ways of usage</title> + <para>The main difference between <emphasis role="bold"><property>&lt;a4j:push&gt;</property></emphasis>and + <emphasis role="bold"><property>&lt;a4j:poll&gt;</property></emphasis> components + is that <emphasis role="bold"><property>&lt;a4j:push&gt;</property></emphasis> makes request to minimal code only (not to JSF tree) in order to check the presence of messages in the queue. + If the message exists the complete request will be performed. + The component doesn't poll registered beans but registers EventListener which receives messages about events. + </para> +<para> + There are some attributes which allows to customize of the component behaviour: +</para> +<para> +'interval' - Interval (in ms) for call push requests. Default value 1000 (1 sec). +<!-- If "0" a connection is permanent. Also user can set different value for parameter 'timeout'. --> +</para> +Code for registration of listener: + <programlisting role="JAVA"><![CDATA[ +public void addListener(EventListener listener) { +synchronized (listener) { + if (this.listener != listener) { + this.listener = (PushEventListener) listener; +} +]]></programlisting> + + +Component can get message using current code: + <programlisting role="JAVA"><![CDATA[ +System.out.println("event occurs"); +synchronized (listener) { + listener.onEvent(new EventObject(this)); +} +]]></programlisting> + +Thus, component 'push' uses asynchronous model instead of polls. + + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/region.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/region.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/region.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para> +The <emphasis role="bold"> +<property>&lt;a4j:region&gt;</property> +</emphasis> component defines an area that is decoded on the server after AJAX submission. +</para> +</section> +</root> Added: trunk/docs/userguide/en/src/main/docbook/included/region.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/region.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/region.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,120 @@ +<?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.ajax.AjaxRegion</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.components.AjaxRegion.</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlAjaxRegion</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxRegionRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>Here is an example of the region decoding on a page. </para> + <programlisting role="XML"><![CDATA[<a4j:region> + <!--..Some content that will be decoded on server after Ajax request.--> +</a4j:region>]]></programlisting> + </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.ajax.html.HtmlAjaxRegion; +... +HtmlAjaxRegion newRegion = new HtmlAjaxRegion(); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The region is a component used for manipulation with components sent to the server. It sets particular processing parameters for an area on the server, i.e. the region deals with data input on the server and has no direct impact on output. To read more on the components responsible for out, see &quot;reference&quot; +</para> + <para>The region marks an area page that is decoded on the server. In most cases it is not necessary to use the region, as ViewRoot is a default region. This component helps to reduce data quantity processed by the server, but the region doesn&apos;t influence on the standard submission rules. It means that:<itemizedlist> + <listitem> + The area that is to be submitted onto the server should be embedded in <emphasis role="bold"> +<property>&lt;h:form/a4j:form&gt;</property> +</emphasis> component. + </listitem> + <listitem> + The whole form is submitted on Ajax response and not a region that request is performed from. + </listitem> + </itemizedlist></para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<h:form id="form1"> + <a4j:region> + <a4j:commandLink reRender="someID" value="Link" id="link1"/> + <!--..Some content that will be decoded on server after Ajax request.--> + </a4j:region> +<h:form>]]></programlisting> + <para>Hence, the <emphasis role="bold"> + <property>&lt;a4j:commandLink&gt;</property> + </emphasis> request generation causes full &quot;form1&quot; form submission onto the server, the only difference is that a component tree part decoded on the serve is the part included into the region.</para> + <para>The regions could be nested in any order, the server picks out and decodes only the region, which contains a particular component that sends a request.</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<a4j:region> + <a4j:commandLink reRender="someID" value="Link" id="link1"/> + <a4j:region> + <a4j:commandLink reRender="someID" value="Link" id="link2"/> + <!--..Some content that will be decoded on server after Ajax request.--> + </a4j:region > + <!--..Some content that will be decoded on server after Ajax request.--> +</a4j:region >]]></programlisting> + <para>Therefore, the external region is decoded for the &quot;link1&quot; and the internal one is decoded for the &quot;link2&quot;.</para> + <para>Ajax4jsf allows setting Ajax responses rendering directly basing on component tree nodes without referring to the JSP (XHTML) page code. It could be defined by selfRendered attribute setting to &quot;true&quot; on <emphasis role="bold"> + <property>&lt;a4j:region&gt;</property> + </emphasis> and could help considerably speed up a response output. However, this rapid processing could cause missing of transient components that present on view and don&apos;t come into a component tree as well as omitting of <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> usage described below. +</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<a4j:region selfRendered ="true"> + <a4j:commandLink reRender="someID" value="Link" id="link1"/> + <!--..Some content with HTML used ("br" ,"h1" and other tags used)--> +</a4j:region >]]></programlisting> + <para>In this case, the processing is quicker and going on without referring to a page code, but the HTML code that isn&apos;t saved in a component tree could be lost. Thus, this optimization should be very carefully performed and a usage of the additional components ajax4jsf (<emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis>) is required. </para> + <para>The processing could be also accelerated if a region decoded for the processing passes straight away into Encode. But to update some data out of the region or on another region, use the <emphasis > + <property>&quot;renderRegionOnly&quot;</property> + </emphasis> +attribute set to &quot;false&quot; (&quot;true on default&quot;) to change this behaviour.</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<a4j:region renderRegionOnly="true"> + <a4j:commandLink reRender="someID2" value="Link1" id="link1"/> + <h:panelGroup id="someId1"> + </h:panelGroup> +</a4j:region> +<a4j:region renderRegionOnly="false"> + <a4j:commandLink reRender="someID1" value="Link2" id="link2"/> + <h:panelGroup id="someId1"> + </h:panelGroup> +</a4j:region>]]></programlisting> + <para>This example shows that one of the regions is decoded when a link is used inside. Nevertheless, + if after processing the &quot;link1&quot; is clicked, the first region passes into Encode as a root + region and encode performance time is reduced. This optimization doesn&apos;t allow data update out of the + region and should be implemented very carefully. The data out of the region described with &quot;renderRegionOnly&quot;=&quot;false&quot; is updated successfully.</para> + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/repeat.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/repeat.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/repeat.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:repeat&gt;</property> + </emphasis> component implements a basic iteration component allowing to update a set of its children with AJAX.</para> +</section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/repeat.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/repeat.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/repeat.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,118 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + + <para><table frame="all"> + <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.ajax.Repeat </entry> + </row> + <row> + <entry>component-family</entry> + <entry>javax.faces.Data </entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlAjaxRepeat </entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.RepeatRenderer </entry> + </row> + </tbody> + </tgroup> + </table></para> + + <section> + <title>Creating on a page</title> + <para>The component definition on a page is the same as for the <emphasis > + <property>&quot;facelets&quot;</property> + </emphasis> component:</para> + <programlisting role="XML"><![CDATA[<a4j:repeat id="detail" value="#{bean.props}" var="detail"> + <h:outputText value="#{detail.someProperty}"/> +</a4j:repeat>]]></programlisting> + <para>The output is generated according to a collection contained in <emphasis > + <property>&quot;bean.props&quot;</property> + </emphasis> with the &quot;detail&quot; key passed to child components.</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.ajax.html.HtmlAjaxRepeat; +... +HtmlAjaxRepeat repeater = new HtmlAjaxRepeat (); +... +]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>The main difference of this component from iterative components of other libraries is a special <emphasis > + <property>&quot;ajaxKeys&quot;</property> + </emphasis> attribute. This attribute defines strings that are updated after an AJAX request. As a result it becomes easier to update several child components separately without updating the whole page.</para> + <programlisting role="JSP"><![CDATA[<a4j:poll intervall="1000" action="#{repeater.action}" reRender="list"> +... +<table> + <tbody> + <a4j:repeat value="#{bean.props}" var="detail" binding="#{repeater.myRepeat}" + id="list" ajaxKeys="#{repeater.ajaxedRowsSet}"> + </tr> + <td> + <h:outputText value="detail.someProperty"> + </td> + </tr> + </a4j:repeat> + <tbody> +<table> +]]></programlisting> + <para>Thus, a list with a table structure from <emphasis > + <property>&quot;bean.props&quot;</property> + </emphasis> is output.</para> + <para>In the above-mentioned example the component <emphasis role="bold"> + <property>&lt;a4j:poll&gt;</property> + </emphasis> sends AJAX requests every second, calling the <emphasis > + <property>&quot;action&quot;</property> + </emphasis> method of the <emphasis > + <property>&quot;repeater&quot;</property> + </emphasis> bean. + </para> + <note> + <title>Note:</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:repeater&gt;</property> + </emphasis> component is defined as fully updated, but really updated there are only the strings which rowKeys are included into the set <emphasis > + <property>&quot;ajaxRowSet&quot;</property> + </emphasis> defined in the <emphasis > + <property>&quot;ajaxKeys&quot;</property> + </emphasis> attribute </para> + <para>The set could be defined during the action method processing using data on a model from the property <emphasis > + <property>&quot;repeater.myRepeat&quot;</property> + </emphasis></para> + </note> +<para>One more benefit of this component is absence of strictly defined markup as JSF HTML DataTable and Tomahawk DataTable has, hence the components could be used more flexibly anywhere where it&apos;s necessary to output the results of selection from some collection.</para> +<para>The next example shows collection output as a plain HTML list</para> + <programlisting role="JSP"><![CDATA[<ul> + <a4j:repeat ...> + <li>...<li/> + ... + <li>...<li/> + </a4j:repeat> +</ul> +]]></programlisting> + <para>All other general attributes are defined according to the similar attributes of iterative components (<emphasis role="bold"> + <property>&lt;h:dataTable&gt;</property> + </emphasis> or <emphasis role="bold"> + <property>&lt;ui:repeat&gt;</property> + </emphasis>) and are used in the same way.</para> + </section> +</chapter> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/status.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/status.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/status.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> + <section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:status&gt;</property> + </emphasis> component generates elements for displaying of the current AJAX requests status. There are two status modes: AJAX request is in process or finished.</para> + </section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/status.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/status.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/status.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,119 @@ +<?xml version='1.0' encoding='UTF-8'?> +<chapter> + + <para><table frame="all"> + <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.ajax.Status </entry> + </row> + <row> + <entry>component-family</entry> + <entry>javax.faces.Panel </entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlAjaxStatus </entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxStatusRenderer </entry> + </row> + </tbody> + </tgroup> + </table></para> + + <section> + <title>Creating on a page</title> + <para>There are two ways to define elements indicating a request status :</para> + <itemizedlist> + <listitem> + With <emphasis > + <property>&quot;StartText&quot;/&quot;StopText&quot;</property> + </emphasis> atributes: + <programlisting role="XML"><![CDATA[<a4j:status startText="Progress" stopText="Done" for="stat1">]]></programlisting> + <para>In this case, text elements for the corresponding status are generated.</para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + With &quot;Start&quot;/&quot;Stop&quot; facets definition: + <programlisting role="XML"><![CDATA[<a4j:status for="stat2"> + <f:facet name="start"> + <h:graphicImage value="ajax_process.gif" /> + </f:facet> + <f:facet name="stop"> + <h:graphicImage value="ajax_stoped.gif" /> + </f:facet> +</a4j:status>]]></programlisting> + <para>In this case, the elements are generated for each status and correspond the facets content.</para> + </listitem> + </itemizedlist> + </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.ajax.html.HtmlAjaxStatus; +... +HtmlAjaxStatus myStatus = new HtmlAjaxStatus(); +...]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>There are two ways for components or containers definition, which AJAX requests status is tracked by a component.<itemizedlist> + <listitem> + Definition with the <emphasis > + <property>&quot;for&quot;</property> + </emphasis> +attribute on the <emphasis role="bold"> + <property>&lt;a4j:status&gt;</property> + </emphasis> component. Here <emphasis > + <property>&quot;for&quot;</property> + </emphasis> +attribute should point at an AJAX container (<emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis>) &quot;id&quot;, which requests are tracked by a component. + </listitem> + </itemizedlist><itemizedlist> + <listitem> + Definition with the <emphasis > + <property>&quot;status&quot;</property> + </emphasis> +attribute obtained by any Ajax4jsf library action component. The attribute should point at the <emphasis role="bold"> + <property>&lt;a4j:status&gt;</property> + </emphasis> component &quot;id&quot;. Then this <emphasis role="bold"> + <property>&lt;a4j:status&gt;</property> + </emphasis> component shows the status for the request fired from this action component. + </listitem> + </itemizedlist></para> + <para>The component creates two <emphasis role="bold"><property>&lt;span&gt;</property></emphasis> elements with content defined for each status, one of the elements (start) is initially hidden. At the beginning of an AJAX request, elements state is inversed, hence the second element is shown and the first is hidden. At the end of a response processing, elements display states return to its initial values.</para> + <para>Example:</para> + <programlisting role="XML"><![CDATA[<a4j:status startText="Started" stopText="stopped" layout="block"/>]]></programlisting> + <para>is decoded on a page as:</para><programlisting role="XML"><![CDATA[<span id="j_id20:status.start" style="display: none"> + Started +</span> +<span id="j_id20:status.stop"> + Stopped +</span>]]></programlisting> + <para>And after the generation of an AJAX response is changed to:</para> + <programlisting role="XML"><![CDATA[<span id="j_id20:status.start"> + Started +</span> +<span id="j_id20:status.stop" style="display: none"> + Stopped +</span>]]></programlisting> + <para>There is a possibility to group a <emphasis role="bold"><property>&lt;a4j:status&gt;</property></emphasis> elements content into <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> elements, instead of <emphasis role="bold"><property>&lt;span&gt;</property></emphasis>. To use it, just redefine the <emphasis > + <property>&quot;layout&quot;</property> + </emphasis> +attribute from &quot;incline&quot;(default) to &quot;block&quot;.</para> + </section> +</chapter> Added: trunk/docs/userguide/en/src/main/docbook/included/support.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/support.desc.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/support.desc.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,9 @@ +<?xml version='1.0' encoding='UTF-8'?> +<root> +<section> +<title>Description</title> + <para>The <emphasis role="bold"> + <property>&lt;a4j:support&gt;</property> + </emphasis> component adds an AJAX support to any existing JSF component. It allows a component to generate asynchronous requests on the necessary event demand and with partial update of page content after a response incoming from the server.</para> +</section> +</root> \ No newline at end of file Added: trunk/docs/userguide/en/src/main/docbook/included/support.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/support.xml (rev 0) +++ trunk/docs/userguide/en/src/main/docbook/included/support.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -0,0 +1,154 @@ +<?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.ajax.Support</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.ajax4jsf.components.AjaxSupport</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.ajax4jsf.ajax.html.HtmlAjaxSupport</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.ajax4jsf.components.AjaxSupportRenderer</entry> + </row> + </tbody> + </tgroup> + </table> + + <section> + <title>Creating on a page</title> + <para>To use a component, place <emphasis role="bold"> + <property>&lt;a4j:support&gt;</property> + </emphasis> as nested to the component requesting AJAX functionality and specify an event of a + parent component that generates AJAX request and the components to be rerendered after a response + from the server.</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<h:inputText value="#{bean.text}"> + <a4j:support event="onkeyup" reRender="repeater"/> +</h:inputText> +<h:outputText id="repeater" value="#{bean.text}"/>]]></programlisting> + <para>On every keyup event generated by an input field, a form is submitted on the server with the help of Ajax and + on a response coming from the server, element with &quot;repeater&quot; id, founded in a DOM tree is + redrawn according to a new data from the response.</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.ajax.html.HtmlAjaxSupport; +... +HtmlAjaxSupport mySupport = new HtmlAjaxSupport();>]]></programlisting> + </section> + <section> + <title>Key attributes and ways of usage</title> + <para>A4j support addition is very similar to correspondent event redefinition of a component, i.e. +</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<h:inputText value="#{bean.text}"> + <a4j:support event="onkeyup" reRender="repeater"/> +</h:inputText> +]]></programlisting> +<para>Is decoded on the page as:</para> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> +<programlisting role="XML"><![CDATA[ +<input onkeyup="A4J.AJAX.Submit( Some request parameters )"/> +]]></programlisting> + <para>As you see from the code, the &quot;onkeyup&quot; +event calls a utility ajax4jsf method that submit a form creating a special marks for a filter informing that it is an Ajax request. Thus, any supports quantity could be added to every component, the supports define component behavior on these events. </para> + <note> + <para>The components: <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis>, <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis>, <emphasis role="bold"> + <property>&lt;a4j:poll&gt;</property> + </emphasis> and others from Ajax4jsf library are already supplied with <emphasis role="bold"> + <property>&lt;a4j:support&gt;</property> + </emphasis> functionality and there is no necessity to add the support to them. </para> + </note> + <para>With the help of <emphasis > + <property>&quot;onsubmit&quot;</property></emphasis> and <emphasis > + <property>&quot;oncomplete&quot;</property></emphasis> attributes the component allows using JavaScript before (for request sending conditions checking) and after an AJAX response processing termination (for performance of user-defined activities on the client) </para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<h:selectOneMenu value="#{bean.text}"> + <f:selectItem itemValue="First Item " itemLabel="First Item"/> + <f:selectItem itemValue=" Second Item " itemLabel="Second Item"/> + <f:selectItem itemValue=" Third Item " itemLabel="Third Item"/> + <a4j:support event="onblur" reRender="panel" onsubmit="if(!confirm('Are you sure to change the option ?')) + {form.reset(); return false;}" oncomplete="alert('Value succesfully stored')"/> +</h:selectOneMenu>]]></programlisting> + <para>In example there is the condition checking (confirm) is used before request sending and message printing after the request processing is over. </para> + <para>The components allows different AJAX request managing ways for its various optimization in particular conditions such as: +<itemizedlist> + <listitem> + <emphasis role="bold">Limitation of the submit area and updating area for the request.</emphasis> + <para><emphasis ><property>&quot;ajaxSingle&quot;</property></emphasis> is an attribute that allows submission on the server only component sending a request, as if the component presented on a separate form. + +</para> + <para><emphasis ><property>&quot;limitToList&quot;</property></emphasis> is an attribute that allows to limit areas, which are updated after the responses. Only these components defined in the reRender attribute are updated. </para> + </listitem> + </itemizedlist></para> + <para><emphasis role="bold">Example 1:</emphasis></para> + <programlisting role="XML"><![CDATA[<h:form> + <h:inputText value="#{person.name}"> + <a4j:support event="onkeyup" reRender="test" ajaxSingle="true"/> + </h:inputText> + <h:inputText value="#{person.middleName}"/> +</form>]]></programlisting> + <para>In this example the request contains only the input component causes the request generation, not all the components contained on a form, because of &quot;ajaxSingle=true&quot; usage. </para> + <para><emphasis role="bold">Example 2:</emphasis></para> + <programlisting role="XML"><![CDATA[<h:form> + <a4j:outputPanel ajaxRendered="true"> + <h:messages/> + </a4j:outputPanel> + <h:inputText value="#{person.name}"> + <a4j:support event="onkeyup" reRender="test" limitToList="true"/> + </h:inputText> + <h:outputText value="#{person.name}" id="test"/> +</form>]]></programlisting> + <para>In this example the component &quot;h:messages&quot; is always updated (as it capturing all AJAX requests, located in ajaxRendered <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis>), except the case when a response is sent from the input component from the example. On sending this component marks that updating area is limited to the defined in it components, it means that on its usage with &quot;limitToList&quot;=&quot;true&quot; the only component updated is the one with &quot;d&quot;=&quot;test&quot;.</para> + <itemizedlist> + <listitem> + <emphasis role="bold">Limitation of requests frequency and updates quantity after the responses. </emphasis> + <para><emphasis ><property>&quot;requestDelay&quot;</property></emphasis> is an attribute that defines a time interval in seconds minimally permissible between responses. + +</para> + <para><emphasis ><property>&quot;eventQueue&quot;</property></emphasis> is an attribute for naming of the queue where the next response is kept in till its processing, but if the next event comes in till this time is over, the waiting event is taken away, replacing with a new one. + +</para> + <para><emphasis ><property>&quot;ignoreDupResponces&quot;</property></emphasis> is an attribute that allows to disable any updates on the client after an AJAX request if another AJAX request is already sent. +</para> + <para><emphasis ><property>&quot;timeout&quot;</property></emphasis> is an attribute that allows to set a time interval in millisecond to define a maximum time period of response wait time. In case of the interval interaction, a new request is sent and the previous one is canceled. Postprocessing of a response isn't performed. +</para> + <para><emphasis role="bold">Example:</emphasis></para> + <programlisting role="XML"><![CDATA[<h:form> + <h:inputText value="#{person.name}"> + <a4j:support event="onkeyup" reRender="test" + requestDelay="1000" ignoreDupResponces="true" eventsQueue="myQueue"/> + </h:inputText> + <h:outputText value="#{person.name}" id="test"/> +</form>]]></programlisting> + <para>This example clearly shows mentioned <ulink url="index.html#support">above</ulink> attributes. If quick typing in a text field happens, every next requests sending is delayed for a second and requests quantity is reduced. The requests are kept in the queue &quot;myQueue&quot; till its the sending. +Moreover, if the next request is already sent, the rerendering after the previous request is banned, and + it helps to avoid unnecessary processing on the client.</para> + </listitem> + </itemizedlist> + </section> + </chapter> \ No newline at end of file Modified: trunk/docs/userguide/en/src/main/docbook/master.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/master.xml 2007-08-06 13:05:44 UTC (rev 2072) +++ trunk/docs/userguide/en/src/main/docbook/master.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -2,7 +2,9 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN" "../../../../../resources/support/docbook-dtd/docbookx.dtd" [ <!ENTITY rfcintro SYSTEM "modules/RFCintro.xml"> -<!ENTITY rfcdocumentroadmap SYSTEM "modules/RFCdocumentroadmap.xml"> + +<!--<!ENTITY rfcdocumentroadmap SYSTEM "modules/RFCdocumentroadmap.xml"> --> + <!ENTITY rfctechreqs SYSTEM "modules/RFCtechreqs.xml"> <!ENTITY rfcsetwebappl SYSTEM "modules/RFCsetwebappl.xml"> <!ENTITY wadParams SYSTEM "modules/AUGWADParams.xml"> Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2007-08-06 13:05:44 UTC (rev 2072) +++ trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2007-08-06 13:07:23 UTC (rev 2073) @@ -13,7 +13,316 @@ <keyword>skin</keyword> </keywordset> </chapterinfo> +<title>Basic concepts of the Ajax4jsf Framework</title> + <section id="introToBasics"> + <?dbhtml filename="introToBasics.html"?> + <title>Introduction</title> + <para>The framework is implemented as a component library which adds AJAX capability into existing + pages, so you don&apos;t need to write any JavaScript code or to replace existing + components with new AJAX widgets. <property>Ajax4jsf</property> enables page-wide AJAX support instead of the + traditional component-wide support. So, you can define the event on the page that + invokes an AJAX request and the areas of the page that should be synchronized with the JSF + Component Tree after the AJAX request changes the data on the server according to the + events fired on the client.</para> + <para>Next Figure shows how it works:</para> + <figure> + <title>Request Processing flow</title> + </figure> + <mediaobject> + <imageobject> + <imagedata fileref="images/newpic1.jpg"/> + </imageobject> + </mediaobject> + <para><property>Ajax4jsf</property> allows to define (by means of JSF tags) different parts of a JSF page you + wish to update with an AJAX request and provide a few options to send AJAX requests to + the server. Also JSF page doesn&apos;t change from a &quot;regular&quot; JSF + page and you don&apos;t need to write any JavaScript or XMLHttpRequest objects by hands, everything is done automatically.</para> + </section> + <section id="Ajax4jsfArchitectureOverview"> + <?dbhtml filename="Ajax4jsfArchitectureOverview.html"?> + <title>Ajax4jsf Architecture Overview</title> + <para>Next figure lists several important elements of the <property>Ajax4jsf</property> framework</para> + <figure> + <title>Ajax4jsf component structure</title> + </figure> + <mediaobject> + <imageobject> + <imagedata fileref="images/newpic2.jpg"/> + </imageobject> + </mediaobject> + <formalpara> + <title>Ajax Filter.</title> + <para>To get all benefits of <property>Ajax4jsf</property>, you should register an AJAX Filter in web.xml + file of your application.The AJAX Filter recognizes multiple request types. The sequence diagram on Figure 3 + shows the difference in processing of a &quot;regular&quot; JSF request and an AJAX request.</para> + </formalpara> + <para>In the first case the whole JSF tree will be encoded, + in the second one option it depends on the &quot;size&quot; of the AJAX region (you can define AJAX region + by using the <emphasis role="bold"><property>&lt;a4j:region&gt;</property></emphasis>). As you can see, in the second case the filter parses + the content of an AJAX response before sending it to the client side.</para> + <para>Have a look at the next picture to understand these two ways:</para> + <figure> + <title>Request Processing sequence diagram</title> + </figure> + <mediaobject> + <imageobject> + <imagedata fileref="images/newpic3.jpg"/> + </imageobject> + </mediaobject> + <para>In both cases, the information about required static or dynamic resources that your application + requests is registered in the ResourseBuilder class.</para> + <para>When a request for a resource comes (Figure 4), the AJAX filter checks the Resource Cache + for this resource and if it is there, the resource is sent to the client. Otherwise, + the filter searches for the resource among those that are registered by the + ResourceBuilder. If the resource is registered, the AJAX filter will send a request to the + ResourceBuilder to create (deliver) the resource.</para> + <para>Next Figure shows the ways of resource request processing.</para> + <figure> + <title>Resource request sequence diagram</title> + </figure> + <mediaobject> + <imageobject> + <imagedata fileref="images/newpic4.jpg"/> + </imageobject> + </mediaobject> + <formalpara> + <title>AJAX Action Components</title> + <para> + There are four AJAX Action Components: AjaxCommandButton, AjaxCommandLink, AjaxPoll and AjaxSupport. + You can use them to send AJAX requests from the client side. + </para> + </formalpara> + <formalpara> + <title>AJAX Containers</title> + <para> + AjaxContainer is an interface that describes an area on your JSF page that should be decoded + during an AJAX request. AjaxViewRoot and AjaxRegion are implementations of this interface. + </para> + </formalpara> + <formalpara> + <title>JavaScript Engine</title> + <para><property> Ajax4jsf</property> JavaScript Engine runs on the client-side. It knows how to update different areas + on your JSF page based on the information from the Ajax response. Do + not use this JavaScript code directly, as it is available automatically. + </para> + </formalpara> + </section> + <section id="LimitationsAndRules"> + <?dbhtml filename="LimitationAndRules.html"?> + <title>Limitations and Rules</title> + <para>In order to create AJAX4JSF applications properly, keep the following points in mind:</para> + <itemizedlist> + <listitem> + The AJAX framework should not append or delete, but only replace elements on the page. For successful updates, an element with the same ID as in the response must exist on the page. If you&apos;d like to append any code to a page, put in a placeholder for it (any empty element). For the same reason, it&apos;s recommended to place messages in the<emphasis > + <property>&quot;AjaxOutput&quot;</property> + </emphasis> component (as no messages is also a message). + </listitem> + <listitem> + Don&apos;t use <emphasis role="bold"> + <property>&lt;f:verbatim&gt;</property> + </emphasis> for self-rendered containers, since this component is transient and not saved in the tree. + </listitem> + <listitem> + AJAX requests are made by XMLHttpRequest functions in XML format, but this XML bypasses most validations and the corrections that might be made in a browser. So, create only a strict standards-compliant code for HTML and XHTML, without skipping any required elements or attributes. Any necessary XML corrections are automatically made by the XML filter on the server, but lot&apos;s of unexpected effects can be produced by an incorrect HTML code. + </listitem> + </itemizedlist> + </section> + <section id="HowTo..."> + <?dbhtml filename="HowTo.html"?> + <title>How To...</title> + <section id="SendAnAJAXRequest"> + <?dbhtml filename="SendAnAJAXRequest.html"?> + <title>Send an AJAX request</title> + <para>There are different ways to send AJAX requests from your JSF page. You may use + <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis>, <emphasis role="bold"> + <property>&lt;a4j:commandLink&gt;</property>, <emphasis role="bold"><property>&lt;a4j:poll&gt;</property></emphasis> + </emphasis> or <emphasis role="bold"> + <property>&lt;a4j:support&gt;</property> + </emphasis> tags. + </para> + <para>All these tags hide the usual JavaScript activities that are required for an XMHttpRequest + object building and an AJAX request sending. Also, they allow you to decide which components of + your JSF page are to be re-rendered as a result of the AJAX response (you can list the + IDs of these components in the &quot;reRender&quot; attribute). + </para> + <para> + <emphasis role="bold"> + <property>&lt;a4j:commandButton&gt;</property> + </emphasis> and <emphasis role="bold"> + <property>&lt;a4j:commandLink&gt;</property> + </emphasis> tags are used to send an AJAX + request on &quot;onclick&quot; JavaScript event. + </para> + <para> + <emphasis role="bold"> + <property>&lt;a4j:poll&gt;</property> + </emphasis> tag is used to send an AJAX + request periodically using a timer. + </para> + <para>The <emphasis role="bold"> + <property>&lt;a4j:support&gt;</property> + </emphasis> tag allows you to add AJAX functionality to standard JSF components + and send AJAX request onto a chosen JavaScript event: &quot;onkeyup&quot;, &quot;onmouseover&quot;, + etc. + </para> + <para>Most important attributes of components that provide AJAX request calling features are:</para> + <itemizedlist> + <listitem> + <emphasis > + <property>&quot;reRender&quot;</property> + </emphasis>attribute as it was mentioned <link linkend="SendAnAJAXRequest">before</link> specifies components to be reRendered + after AJAX response. The attribute can be specified using EL expression and formed dynamicaly on the + server side (see <ulink url="index.html#FAQ">FAQ chapter</ulink>). + </listitem> + <listitem> + <emphasis > + <property>&quot;RequestDelay&quot;</property> + </emphasis> attribute is used for a requests frequency regulation. + </listitem> + </itemizedlist> + <programlisting role="XML"><![CDATA[<h:inputText size="50" value="#{bean.text}"> + <a4j:support event="onkeyup" RequestDelay="3"/> +</h:inputText>]]></programlisting> + <para>So every next request from the frequent keyboard events will be delayed + on 3 ms to reduce the number of requests. + </para> + <itemizedlist> + <listitem> + <emphasis > + <property>&quot;EventsQueue&quot;</property> + </emphasis> is a queue that stores the next request. + </listitem> + <listitem> + <emphasis > + <property>&quot;LimitToList&quot;</property> + </emphasis> attribute is used to regulate updatable regions. Setting + it to true limits the updatable areas only to ones specified in a + reRender list, in other case all Output Panels of the region are updated. + </listitem> + <listitem> <emphasis > + <property>&quot;ajaxSingle&quot;</property> + </emphasis> attributes specify regions to be sent with a request, + if &quot;false&quot; it is a full region, in other case it&apos;s is only a control caused + event. +</listitem> + </itemizedlist> + </section> + <section id="DecideWhatToSend"> + <?dbhtml filename="DecideWhatToSend.html"?> + <title>Decide What to Send</title> + <para>You may describe a region on the page you wish to send to the server, in this way you can + control what part of the JSF View is decoded on the server side when you send an + AJAX request. + </para> + <para>The easiest way to describe an AJAX region on your JSF page is to do nothing, + because the content between the <emphasis role="bold"> + <property>&lt;f:view&gt;</property> + </emphasis> and <emphasis role="bold"> + <property>&lt;/f:view&gt;</property> + </emphasis> tags is considered + the default AJAX region. + </para> + <para>You may define multiple AJAX regions on the JSF page (they can even be nested) by using + the <emphasis role="bold"> + <property>&lt;a4j:region&gt;</property> + </emphasis> tag. + </para> + <para>If you wish to render the content of an AJAX response outside of the active region then + the value of the &quot;renderRegionOnly&quot; attribute should be set to &quot;false&quot;. Otherwise, your + AJAX updates are limited to elements of the active region. + </para> + </section> + <section id="DecideWhatToChange"> + <?dbhtml filename="DecideWhatToChange.html"?> + <title>Decide What to Change</title> + <para>Using IDs in the &quot;reRender&quot; attribute to define &quot;AJAX zones&quot; for update works fine in + many cases. + </para> + <para>But you can not use this approach if your page contains, e.g. a <emphasis role="bold"><property>&lt;f:verbatim&gt;</property></emphasis> + tag and you wish to update its content on an AJAX response. + </para> + <para>The problem with the <emphasis role="bold"> + <property>&lt;f:verbatim/&gt;</property> + </emphasis> tag as described above is related to the + value of the transientFlag of JSF components. If the value of this flag is true, the + component must not participate in state saving or restoring of process. + </para> + <para>In order to provide a solution to this kind of problems, Ajax4jsf uses the concept of + an output panel that is defined by the <emphasis role="bold"> + <property>&lt;a4j:outputPanel&gt;</property> + </emphasis> tag. If you put a <emphasis role="bold"><property>&lt;f:verbatim&gt;</property></emphasis> + tag inside of the output panel, then the content of the <emphasis role="bold"> + <property>&lt;f:verbatim/&gt;</property> + </emphasis> tag and content of + other panel&apos;s child tags could be updated on AJAX response. There are two ways to + control this: + <itemizedlist> + <listitem> + By setting the &quot;ajaxRendered&quot; attribute value to &quot;true&quot;. +</listitem> + <listitem> + By setting the &quot;reRender&quot; attribute value of an Action Component to the output panel ID. +</listitem> + </itemizedlist> + </para> + </section> + </section> + <section id="RequestErrorsAndSessionExpirationHandling"> + <?dbhtml filename="RequestErrorsAndSessionExpirationHandling.html"?> + <title>Request Errors and Session Expiration Handling</title> + <para>Ajax4jsf allows to redefine standard handlers responsible for processing of different exceptional situations. It helps to define own JavaScript, which is executed when this situations occur.</para> + <section id="RequestErrorsHandling"> + <?dbhtml filename="RequestErrorsHandling.html"?> + <title>Request Errors Handling</title> + <para>To execute your own code on the client in case of an error during AJAX request, it's necessary to redefine the standard "A4J.AJAX.onError " method:</para> + <programlisting role="JAVA"><![CDATA[A4J.AJAX.onError = function(req,status,message) { + // Custom Developer Code +};]]></programlisting> + <para>The function defined this way accepts as parameters:</para> + <itemizedlist> + <listitem>req - a params string of a request that calls an error</listitem> + <listitem>status - the number of an error returned by the server</listitem> + <listitem>message - a default message for the given error</listitem> + </itemizedlist> + <para>Thus, it&apos;s possible to create your own handler that is called on timeouts, inner server errors, and etc.</para> + </section> + <section id="SessionExpiredHandling"> + <?dbhtml filename="SessionExpiredHandling.html"?> + <title>Session Expired Handling</title> + <para>Beginning with Ajax4jsf version 1.0.5 it&apos;s possible to redefine also the <emphasis > + <property>&quot;onExpired&quot;</property> + </emphasis> framework method that is called on the <emphasis > + <property>&quot;Session Expiration&quot;</property> + </emphasis> event.</para> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="JAVA"><![CDATA[A4J.AJAX.onExpired = function(loc,expiredMsg){ + // Custom Developer Code +}; +]]></programlisting> + +<para>Here the function receives in params:</para> + <itemizedlist> + <listitem>loc - URL of the current page (on demand can be updated) </listitem> + <listitem>expiredMsg - a default message on <emphasis > + <property>&quot;Session Expiration&quot;</property> + </emphasis>event.</listitem> + </itemizedlist> +<note> +<title>Note:</title> +Until the version 1.0.5 the method can&apos;t be redefined on <emphasis > + <property>&quot;Session Expiration&quot;</property>, + </emphasis> a confirmation dialog with a request for view reloading was always called. +</note> + </section> +</section> +&FAQ; + + + <section> + <title>Skinnability</title> <section id="WhySkinnability"> @@ -521,9 +830,8 @@ </listitem> </itemizedlist> </section> - </section> - -<section><title>Built-in skinnability in Ajax4jsf</title> +<section> +<title>Built-in skinnability in Ajax4jsf</title> <para>Ajax4jsf gives an opportunity to incorporate <property>skinnability</property> into UI design. With this framework you can easily use named skin parameters in properties files to control the appearance of the skins that are applied @@ -586,5 +894,15 @@ <member> <ulink url="http://java.sun.com/javaee/javaserverfaces/reference/docs/index... </member> - </simplelist></section> + </simplelist> + </section> + + </section> + +<section id="OtherRelevantResources"> + <title>Other Relevant Resources</title> + <para><ulink url="http://jsf.javabeat.net/articles/2007/06/introduction-to-ajax4j... to Ajax4Jsf</ulink> by Shunmuga Raja</para> + +</section> + </chapter> \ No newline at end of file