Author: jbalunas(a)redhat.com Date: 2010-06-03 12:46:33 -0400 (Thu, 03 Jun 2010) New Revision: 17492 Modified: root/docs/trunk/Component_Reference/en-US/Component_Reference.xml root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Actions.xml root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Common_Ajax_attributes.xml root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Containers.xml root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Resources.xml Log: Updated component guide to represent what is in Alpha2 Modified: root/docs/trunk/Component_Reference/en-US/Component_Reference.xml =================================================================== --- root/docs/trunk/Component_Reference/en-US/Component_Reference.xml 2010-06-03 16:45:54 UTC (rev 17491) +++ root/docs/trunk/Component_Reference/en-US/Component_Reference.xml 2010-06-03 16:46:33 UTC (rev 17492) @@ -5,7 +5,8 @@ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> - --><xi:include href="chap-Component_Reference-Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + --> + <xi:include href="chap-Component_Reference-Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="chap-Component_Reference-Common_Ajax_attributes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="chap-Component_Reference-Common_features.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <part id="part-Component_Reference-a4j_tag_library"> @@ -13,7 +14,8 @@ <xi:include href="chap-Component_Reference-Actions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="chap-Component_Reference-Resources.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="chap-Component_Reference-Containers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="chap-Component_Reference-Validation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- FIXME NOT IN A2 --> +<!-- <xi:include href="chap-Component_Reference-Validation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--> <xi:include href="chap-Component_Reference-Processing_management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </part> <part id="part-Component_Reference-rich_tag_library"> Modified: root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Actions.xml =================================================================== --- root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Actions.xml 2010-06-03 16:45:54 UTC (rev 17491) +++ root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Actions.xml 2010-06-03 16:46:33 UTC (rev 17492) @@ -73,37 +73,38 @@ Variables from JavaScript functions can be used for the <varname>value</varname> attribute. In such an implementation, the <varname>noEscape</varname> attribute should be set to <literal>true</literal>. Using <code>noEscape="true"</code>, the <varname>value</varname> attribute can contain any JavaScript expression or JavaScript function invocation, and the result will be sent to the server as the <varname>value</varname> attribute. </para> </section> + +<!-- TODO NOT IN A2 --> +<!-- <section id="sect-Component_Reference-Actions-a4jajaxListener">--> +<!-- <title><sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- listener-class: <classname>org.ajax4jsf.event.AjaxListener</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- event-class: <classname>org.ajax4jsf.event.AjaxEvent</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- tag-class: <classname>org.ajax4jsf.taglib.html.jsp.AjaxListenerTag</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> component adds an action listener to a parent component. It works similar to the JavaServer Faces <sgmltag>&lt;f:actionListener&gt;</sgmltag> or <sgmltag>&lt;f:valueChangeListener&gt;</sgmltag> components, except that the invocation of <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> is not canceled if validation of the <emphasis>Update Model</emphasis> phase fails. The <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> component is guaranteed to be invoked with each Ajax response.--> +<!-- </para>--> +<!-- <para>--> +<!-- Basic usage requires only the <varname>type</varname> attribute, which defines the fully-qualified Java class name for the listener. This Java class should implement the <classname>org.ajax4jsf.event.AjaxListener</classname> interface, which is a base listener for all listeners and is capable of receiving Ajax events. The object from which the event originated could be accessed using the <methodname>java.util.EventObject.getSource()</methodname> method.--> +<!-- </para>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> component is not invoked for non-Ajax requests, or when the RichFaces works in the <emphasis>Ajax request generates non-Ajax response</emphasis> mode, so the <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> invocation is a good indicator that an Ajax response is going to be processed.--> +<!-- </para>--> +<!-- </section>--> - <section id="sect-Component_Reference-Actions-a4jajaxListener"> - <title><sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - listener-class: <classname>org.ajax4jsf.event.AjaxListener</classname> - </para> - </listitem> - <listitem> - <para> - event-class: <classname>org.ajax4jsf.event.AjaxEvent</classname> - </para> - </listitem> - <listitem> - <para> - tag-class: <classname>org.ajax4jsf.taglib.html.jsp.AjaxListenerTag</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> component adds an action listener to a parent component. It works similar to the JavaServer Faces <sgmltag>&lt;f:actionListener&gt;</sgmltag> or <sgmltag>&lt;f:valueChangeListener&gt;</sgmltag> components, except that the invocation of <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> is not canceled if validation of the <emphasis>Update Model</emphasis> phase fails. The <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> component is guaranteed to be invoked with each Ajax response. - </para> - <para> - Basic usage requires only the <varname>type</varname> attribute, which defines the fully-qualified Java class name for the listener. This Java class should implement the <classname>org.ajax4jsf.event.AjaxListener</classname> interface, which is a base listener for all listeners and is capable of receiving Ajax events. The object from which the event originated could be accessed using the <methodname>java.util.EventObject.getSource()</methodname> method. - </para> - <para> - The <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> component is not invoked for non-Ajax requests, or when the RichFaces works in the <emphasis>Ajax request generates non-Ajax response</emphasis> mode, so the <sgmltag>&lt;a4j:ajaxListener&gt;</sgmltag> invocation is a good indicator that an Ajax response is going to be processed. - </para> - </section> - <section id="sect-Component_Reference-Actions-a4jcommandButton"> <title><sgmltag>&lt;a4j:commandButton&gt;</sgmltag></title> <itemizedlist> @@ -200,8 +201,9 @@ </para> </section> + <!-- FIXME this is really rich:componentControl --> <section id="sect-Component_Reference-Actions-a4jcomponentControl"> - <title><sgmltag>&lt;a4j:componentControl&gt;</sgmltag></title> + <title><sgmltag>&lt;rich:componentControl&gt;</sgmltag></title> <remark>The following reference data is taken from the old <sgmltag>&lt;rich:componentControl&gt;</sgmltag> reference. The details may be different now that the component is part of the <classname>a4j</classname> tag library.</remark> <itemizedlist> <listitem> @@ -231,17 +233,17 @@ </listitem> </itemizedlist> <para> - The <sgmltag>&lt;a4j:componentControl&gt;</sgmltag> allows JavaScript API functions to be called on components after defined events. Initialization variants and activation events can be customized, and parameters can be passed to the target component. + The <sgmltag>&lt;rich:componentControl&gt;</sgmltag> allows JavaScript API functions to be called on components after defined events. Initialization variants and activation events can be customized, and parameters can be passed to the target component. </para> <para> The <varname>event</varname>, <varname>for</varname>, and <varname>operation</varname> attributes are all that is required to attach JavaScript functions to the parent component. The <varname>event</varname> attribute specifies the event that triggers the JavaScript API function call. The <varname>for</varname> attribute defines the target component, and the <varname>operation</varname> attribute specifies the JavaScript function to perform. </para> <example id="exam-Component_Reference-a4jcomponentControl-a4jcomponentControl_basic_usage"> - <title>a4j:componentControl basic usage</title> + <title>rich:componentControl basic usage</title> <programlisting language="XML" role="XML">&lt;h:commandButton value="Show Modal Panel"&gt; &lt;!--componentControl is attached to the commandButton--&gt; - &lt;a4j:componentControl for="ccModalPanelID" event="onclick" operation="show"/&gt; + &lt;rich:componentControl for="ccModalPanelID" event="onclick" operation="show"/&gt; &lt;/h:commandButton&gt; </programlisting> <para> @@ -249,10 +251,10 @@ </para> </example> <para> - The <varname>attachTo</varname> attribute can be used to attach the event to a component other than the parent component. If no <varname>attachTo</varname> attribute is supplied, the <sgmltag>&lt;a4j:componentControl&gt;</sgmltag> component's parent is used, as in <xref linkend="exam-Component_Reference-a4jcomponentControl-a4jcomponentControl_basic_usage" />. + The <varname>attachTo</varname> attribute can be used to attach the event to a component other than the parent component. If no <varname>attachTo</varname> attribute is supplied, the <sgmltag>&lt;rich:componentControl&gt;</sgmltag> component's parent is used, as in <xref linkend="exam-Component_Reference-a4jcomponentControl-a4jcomponentControl_basic_usage" />. </para> <example id="exam-Component_Reference-a4jcomponentControl-Attaching_a4jcomponentControl_to_a_component"> - <title>Attaching <sgmltag>&lt;a4j:componentControl&gt;</sgmltag> to a component</title> + <title>Attaching <sgmltag>&lt;rich:componentControl&gt;</sgmltag> to a component</title> <programlisting language="XML" role="XML">&lt;rich:componentControl attachTo="doExpandCalendarID" event="onclick" operation="Expand" for="ccCalendarID" /&gt; </programlisting> @@ -290,7 +292,7 @@ The <varname>name</varname> attribute can be used to define a normal JavaScript function that triggers the specified operation on the target component. </para> <para> - The <varname>attachTiming</varname> attribute can determine the page loading phase during which the <sgmltag>&lt;a4j:componentControl&gt;</sgmltag> is attached to the source component: + The <varname>attachTiming</varname> attribute can determine the page loading phase during which the <sgmltag>&lt;rich:componentControl&gt;</sgmltag> is attached to the source component: </para> <variablelist> <varlistentry> @@ -327,37 +329,38 @@ </para> </section> - <section id="sect-Component_Reference-Actions-a4jhtmlCommandLink"> - <title><sgmltag>&lt;a4j:htmlCommandLink&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.HtmlCommandLink</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>javax.faces.Command</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.component.html.HtmlCommandLink</classname> - </para> - </listitem> - <listitem> - <para> - renderer-type: <classname>org.ajax4jsf.HtmlCommandLinkRenderer</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:htmlCommandLink&gt;</sgmltag> component functions similarly to the standard <sgmltag>&lt;h:commandLink&gt;</sgmltag> component, but addresses some of the potential issues that can occur. - </para> - <para> - When using the standard component, hidden fields were not rendered to child elements if they were deemed unnecessary, so command links relating to content on the initial page could become broken if they were later updated through Ajax. The <sgmltag>&lt;a4j:htmlCommandLink&gt;</sgmltag> component addresses this by always rendering all hidden fields. - </para> - </section> +<!-- FIXME NOT IS A2 --> +<!-- <section id="sect-Component_Reference-Actions-a4jhtmlCommandLink">--> +<!-- <title><sgmltag>&lt;a4j:htmlCommandLink&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.HtmlCommandLink</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>javax.faces.Command</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.component.html.HtmlCommandLink</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- renderer-type: <classname>org.ajax4jsf.HtmlCommandLinkRenderer</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:htmlCommandLink&gt;</sgmltag> component functions similarly to the standard <sgmltag>&lt;h:commandLink&gt;</sgmltag> component, but addresses some of the potential issues that can occur.--> +<!-- </para>--> +<!-- <para>--> +<!-- When using the standard component, hidden fields were not rendered to child elements if they were deemed unnecessary, so command links relating to content on the initial page could become broken if they were later updated through Ajax. The <sgmltag>&lt;a4j:htmlCommandLink&gt;</sgmltag> component addresses this by always rendering all hidden fields.--> +<!-- </para>--> +<!-- </section>--> <section id="sect-Component_Reference-Actions-a4jjsFunction"> <title><sgmltag>&lt;a4j:jsFunction&gt;</sgmltag></title> @@ -501,8 +504,9 @@ </para> </listitem> </itemizedlist> + <!-- FIXME Move a4j:repeat --> <para> - The <sgmltag>&lt;a4j:repeat&gt;</sgmltag> component is used to iterate changes through a repeated collection of components. It allows specific rows of items to be updated without sending Ajax requests for the entire collection. The <sgmltag>&lt;a4j:repeat&gt;</sgmltag> component forms the basis for many of the tabular components detailed in <xref linkend="chap-Component_Reference-Tables_and_grids" />. + REVIEW COMMENT - a4j:repeat is not an action, should be moved. The <sgmltag>&lt;a4j:repeat&gt;</sgmltag> component is used to iterate changes through a repeated collection of components. It allows specific rows of items to be updated without sending Ajax requests for the entire collection. The <sgmltag>&lt;a4j:repeat&gt;</sgmltag> component forms the basis for many of the tabular components detailed in <xref linkend="chap-Component_Reference-Tables_and_grids" />. </para> <para> The contents of the collection are determined using Expression Language (<acronym>EL</acronym>). The data model for the contents is specified with the <varname>value</varname> attribute. The <varname>var</varname> attribute names the object to use when iterating through the collection. This object is then referenced in the relevant child components. After an Ajax request, only the rows specified with the <varname>ajaxKeys</varname> attribute are updated rather than the entire collection. <xref linkend="exam-Component_Reference-Tables_and_grids-a4jrepeat_example" /> shows how to use <sgmltag>&lt;a4j:repeat&gt;</sgmltag> to maintain a simple table. @@ -519,17 +523,18 @@ </para> </section> + <!-- FIXME - a4j:support is now a4j:ajax in 4.0 --> <section id="sect-Component_Reference-Actions-a4jsupport"> - <title><sgmltag>&lt;a4j:support&gt;</sgmltag></title> + <title><sgmltag>&lt;a4j:ajax&gt;</sgmltag></title> <itemizedlist> <listitem> <para> - component-type: <classname>org.ajax4jsf.Support</classname> + component-type: <classname>org.ajax4jsf.Ajax</classname> </para> </listitem> <listitem> <para> - component-family: <classname>org.ajax4jsf.AjaxSupport</classname> + component-family: <classname>org.ajax4jsf.Ajax</classname> </para> </listitem> <listitem> @@ -544,20 +549,20 @@ </listitem> </itemizedlist> <para> - The <sgmltag>&lt;a4j:support&gt;</sgmltag> component allows Ajax capability to be added to any non-Ajax component. It is placed as a direct child to the component that requires Ajax support. The <sgmltag>&lt;a4j:support&gt;</sgmltag> component uses the common attributes listed in <xref linkend="chap-Component_Reference-Common_Ajax_attributes" />. + REVIEW COMMENT: a4j:support is a4j:ajax in 4.0, paths need to be updated. The <sgmltag>&lt;a4j:ajax&gt;</sgmltag> component allows Ajax capability to be added to any non-Ajax component. It is placed as a direct child to the component that requires Ajax support. The <sgmltag>&lt;a4j:ajax&gt;</sgmltag> component uses the common attributes listed in <xref linkend="chap-Component_Reference-Common_Ajax_attributes" />. </para> <note> <title>Attaching JavaScript functions</title> <para> - When attaching the <sgmltag>&lt;a4j:support&gt;</sgmltag> component to non-Ajax JavaServer Faces command components, such as <sgmltag>&lt;h:commandButton&gt;</sgmltag> and <sgmltag>&lt;h:commandLink&gt;</sgmltag>, it is important to set <code>disabledDefault="true"</code>. If this attribute is not set, a non-Ajax request is sent after the Ajax request and the page is refreshed unexpectedly. + When attaching the <sgmltag>&lt;a4j:ajax&gt;</sgmltag> component to non-Ajax JavaServer Faces command components, such as <sgmltag>&lt;h:commandButton&gt;</sgmltag> and <sgmltag>&lt;h:commandLink&gt;</sgmltag>, it is important to set <code>disabledDefault="true"</code>. If this attribute is not set, a non-Ajax request is sent after the Ajax request and the page is refreshed unexpectedly. </para> </note> <example id="exam-Component_Reference-a4jsupport-a4jsupport_example"> - <title><sgmltag>&lt;a4j:support&gt;</sgmltag> example</title> + <title><sgmltag>&lt;a4j:ajax&gt;</sgmltag> example</title> <programlisting language="XML" role="XML">&lt;h:panelGrid columns="2"&gt; &lt;h:inputText id="myinput" value="#{userBean.name}"&gt; - &lt;a4j:support event="onkeyup" reRender="outtext" /&gt; + &lt;a4j:ajax event="onkeyup" reRender="outtext" /&gt; &lt;/h:inputText&gt; &lt;h:outputText id="outtext" value="#{userBean.name}" /&gt; &lt;/h:panelGrid&gt; Modified: root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Common_Ajax_attributes.xml =================================================================== --- root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Common_Ajax_attributes.xml 2010-06-03 16:45:54 UTC (rev 17491) +++ root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Common_Ajax_attributes.xml 2010-06-03 16:46:33 UTC (rev 17492) @@ -124,9 +124,9 @@ RichFaces uses a form-based approach for sending Ajax requests. As such, each time a request is sent the data from the requesting component's parent <acronym>JSF</acronym> form is submitted along with the <acronym>XMLHTTPRequest</acronym> object. The form data contains values from the input element and auxiliary information such as state-saving data. </para> <section id="sect-Component_Reference-Data_processing-process"> - <title><varname>process</varname></title> + <title><varname>execute</varname></title> <para> - The <varname>process</varname> attribute allows <acronym>JSF</acronym> processing to be limited to defined components. To only process the requesting component, <code>process="@this"</code> can be used. + The <varname>execute</varname> attribute allows <acronym>JSF</acronym> processing to be limited to defined components. To only process the requesting component, <code>execute="@this"</code> can be used. </para> </section> Modified: root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Containers.xml =================================================================== --- root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Containers.xml 2010-06-03 16:45:54 UTC (rev 17491) +++ root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Containers.xml 2010-06-03 16:46:33 UTC (rev 17492) @@ -6,109 +6,110 @@ <para> This chapter details those components in the <classname>a4j</classname> tag library which define an area used as a container or wrapper for other components. </para> - <section id="sect-Component_Reference-Containers-a4jform"> - <title><sgmltag>&lt;a4j:form&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.Form</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>javax.faces.Form</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.component.html.AjaxForm</classname> - </para> - </listitem> - <listitem> - <para> - renderer-type: <classname>org.ajax4jsf.FormRenderer</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:form&gt;</sgmltag> builds on the functionality of the JavaServer Faces (<acronym>JSF</acronym>) component <sgmltag>&lt;h:form&gt;</sgmltag>, adding Ajax capabilities to the form. - </para> - <note> - <title>Command link rendering fixed</title> - <para> - The <acronym>JSF</acronym> component <sgmltag>&lt;h:form&gt;</sgmltag>, on which the <sgmltag>&lt;a4j:form&gt;</sgmltag> component is based, had an issue whereby the <sgmltag>&lt;h:commandLink&gt;</sgmltag> component could not be re-rendered without re-rendering the entire form. <sgmltag>&lt;a4j:form&gt;</sgmltag> and <sgmltag>&lt;a4j:commandLink&gt;</sgmltag> fix this issue. - </para> - </note> - <para> - The <sgmltag>&lt;a4j:form&gt;</sgmltag> component can add indirect Ajax support to non-Ajax components on the form by setting <code>ajaxSubmit="true"</code>. It then uses the standard Ajax component attributes and updates components specified with the <varname>render</varname> attribute. - </para> - <important> - <title><varname>ajaxSubmit</varname></title> - <para> - <sgmltag>&lt;a4j:form&gt;</sgmltag> should not use <code>ajaxSubmit="true"</code> if it contains other Ajax-capable components. - </para> - <para> - Additionally, due to security reasons the file upload form element cannot be indirectly made Ajax-capable with <sgmltag>&lt;a4j:form&gt;</sgmltag>. - </para> - </important> - </section> +<!-- FIXME NOT IN A2 --> +<!-- <section id="sect-Component_Reference-Containers-a4jform">--> +<!-- <title><sgmltag>&lt;a4j:form&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.Form</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>javax.faces.Form</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.component.html.AjaxForm</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- renderer-type: <classname>org.ajax4jsf.FormRenderer</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:form&gt;</sgmltag> builds on the functionality of the JavaServer Faces (<acronym>JSF</acronym>) component <sgmltag>&lt;h:form&gt;</sgmltag>, adding Ajax capabilities to the form.--> +<!-- </para>--> +<!-- <note>--> +<!-- <title>Command link rendering fixed</title>--> +<!-- <para>--> +<!-- The <acronym>JSF</acronym> component <sgmltag>&lt;h:form&gt;</sgmltag>, on which the <sgmltag>&lt;a4j:form&gt;</sgmltag> component is based, had an issue whereby the <sgmltag>&lt;h:commandLink&gt;</sgmltag> component could not be re-rendered without re-rendering the entire form. <sgmltag>&lt;a4j:form&gt;</sgmltag> and <sgmltag>&lt;a4j:commandLink&gt;</sgmltag> fix this issue.--> +<!-- </para>--> +<!-- </note>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:form&gt;</sgmltag> component can add indirect Ajax support to non-Ajax components on the form by setting <code>ajaxSubmit="true"</code>. It then uses the standard Ajax component attributes and updates components specified with the <varname>render</varname> attribute.--> +<!-- </para>--> +<!-- <important>--> +<!-- <title><varname>ajaxSubmit</varname></title>--> +<!-- <para>--> +<!-- <sgmltag>&lt;a4j:form&gt;</sgmltag> should not use <code>ajaxSubmit="true"</code> if it contains other Ajax-capable components.--> +<!-- </para>--> +<!-- <para>--> +<!-- Additionally, due to security reasons the file upload form element cannot be indirectly made Ajax-capable with <sgmltag>&lt;a4j:form&gt;</sgmltag>.--> +<!-- </para>--> +<!-- </important>--> +<!-- </section>--> +<!-- --> +<!-- <section id="sect-Component_Reference-Containers-a4jinclude">--> +<!-- <title><sgmltag>&lt;a4j:include&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.Include</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>javax.faces.Output</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.component.html.Include</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- renderer-type: <classname>org.ajax4jsf.components.AjaxIncludeRenderer</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:include&gt;</sgmltag> component allows one view to be included as part of another page. This is useful for applications where multiple views might appear on the one page, with navigation between the views. Views can use partial page navigation in Ajax mode, or standard <acronym>JSF</acronym> navigation for navigation between views.--> +<!-- </para>--> +<!-- <para>--> +<!-- The <varname>viewId</varname> attribute is required to reference the resource that will be included as a view on the page. It uses a full context-relative path to point to the resource, similar to the paths used for the <sgmltag>&lt;from-view-id&gt;</sgmltag> and <sgmltag>&lt;to-view-id&gt;</sgmltag> tags in the <filename>faces-config.xml</filename> <acronym>JSF</acronym> navigation rules.--> +<!-- </para>--> +<!-- <example id="exam-Component_Reference-a4jinclude-A_wizard_using_a4jinclude">--> +<!-- <title>A wizard using <sgmltag>&lt;a4j:include&gt;</sgmltag></title>--> +<!-- <para>--> +<!-- The page uses <sgmltag>&lt;a4j:include&gt;</sgmltag> to include the first step of the wizard:--> +<!-- </para>--> +<!-- --> +<!--<programlisting language="XML" role="XML">--> +<!--<xi:include href="extras/exam-Component_Reference-a4jinclude-A_wizard_using_a4jinclude-0.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />--> +<!--</programlisting>--> +<!-- <para>--> +<!-- The first step is fully contained in a separate file, <filename>wstep1.xhtml</filename>. Subsequent steps are set up similarly with additional <guibutton>Previous</guibutton> buttons.--> +<!-- </para>--> +<!-- --> +<!--<programlisting language="XML" role="XML">--> +<!--<xi:include href="extras/exam-Component_Reference-a4jinclude-A_wizard_using_a4jinclude-1.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />--> +<!--</programlisting>--> +<!-- <para>--> +<!-- The navigation is defined in the <filename>faces-config.xml</filename> configuration file:--> +<!-- </para>--> +<!-- --> +<!--<programlisting language="XML" role="XML">--> +<!--<xi:include href="extras/exam-Component_Reference-a4jinclude-A_wizard_using_a4jinclude-2.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />--> +<!--</programlisting>--> +<!-- </example>--> +<!-- </section>--> - <section id="sect-Component_Reference-Containers-a4jinclude"> - <title><sgmltag>&lt;a4j:include&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.Include</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>javax.faces.Output</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.component.html.Include</classname> - </para> - </listitem> - <listitem> - <para> - renderer-type: <classname>org.ajax4jsf.components.AjaxIncludeRenderer</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:include&gt;</sgmltag> component allows one view to be included as part of another page. This is useful for applications where multiple views might appear on the one page, with navigation between the views. Views can use partial page navigation in Ajax mode, or standard <acronym>JSF</acronym> navigation for navigation between views. - </para> - <para> - The <varname>viewId</varname> attribute is required to reference the resource that will be included as a view on the page. It uses a full context-relative path to point to the resource, similar to the paths used for the <sgmltag>&lt;from-view-id&gt;</sgmltag> and <sgmltag>&lt;to-view-id&gt;</sgmltag> tags in the <filename>faces-config.xml</filename> <acronym>JSF</acronym> navigation rules. - </para> - <example id="exam-Component_Reference-a4jinclude-A_wizard_using_a4jinclude"> - <title>A wizard using <sgmltag>&lt;a4j:include&gt;</sgmltag></title> - <para> - The page uses <sgmltag>&lt;a4j:include&gt;</sgmltag> to include the first step of the wizard: - </para> - -<programlisting language="XML" role="XML"> -<xi:include href="extras/exam-Component_Reference-a4jinclude-A_wizard_using_a4jinclude-0.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - <para> - The first step is fully contained in a separate file, <filename>wstep1.xhtml</filename>. Subsequent steps are set up similarly with additional <guibutton>Previous</guibutton> buttons. - </para> - -<programlisting language="XML" role="XML"> -<xi:include href="extras/exam-Component_Reference-a4jinclude-A_wizard_using_a4jinclude-1.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - <para> - The navigation is defined in the <filename>faces-config.xml</filename> configuration file: - </para> - -<programlisting language="XML" role="XML"> -<xi:include href="extras/exam-Component_Reference-a4jinclude-A_wizard_using_a4jinclude-2.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - </example> - </section> - <section id="sect-Component_Reference-Containers-a4joutputPanel"> <title><sgmltag>&lt;a4j:outputPanel&gt;</sgmltag></title> <itemizedlist> @@ -161,92 +162,93 @@ </para> </section> - <section id="sect-Component_Reference-Containers-a4jpage"> - <title><sgmltag>&lt;a4j:page&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.components.Page</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>org.ajax4jsf.components.AjaxRegion</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.component.html.HtmlPage</classname> - </para> - </listitem> - <listitem> - <para> - renderer-type: <classname>org.ajax4jsf.components.AjaxPageRenderer</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:page&gt;</sgmltag> component encodes a full HTML-page structure using only one tag. It renders complete <sgmltag>&lt;!DOCTYPE&gt;</sgmltag>, <sgmltag>&lt;html&gt;</sgmltag>, <sgmltag>&lt;head&gt;</sgmltag>, <sgmltag>&lt;title&gt;</sgmltag>, and <sgmltag>&lt;body&gt;</sgmltag> tags using the specified attributes and facets. Additionally, the <sgmltag>&lt;a4j:page&gt;</sgmltag> component solves an incompatibility issue between early versions of <productname>MyFaces</productname> - and the <productname>Ajax4jsf</productname> - framework. - </para> - <para> - The <varname>pageTitle</varname> attribute is rendered as a <sgmltag>&lt;title&gt;</sgmltag> element. The component uses the <literal>head</literal> facet to define the contents of the HTML <sgmltag>&lt;head&gt;</sgmltag> element. The <literal>format</literal> facet defines the page layout format for encoding the <sgmltag>&lt;!DOCTYPE&gt;</sgmltag> element. There rest of the contents of the <sgmltag>&lt;a4j:page&gt;</sgmltag> component are rendered as part of the <sgmltag>&lt;body&gt;</sgmltag> element. - </para> - <example id="exam-Component_Reference-a4jpage-a4jpage_rendering"> - <title><sgmltag>&lt;a4j:page&gt;</sgmltag> rendering</title> - <para> - An <sgmltag>&lt;a4j:page&gt;</sgmltag> component can be defined as follows: - </para> - -<programlisting language="XML" role="XML"><xi:include href="extras/exam-Component_Reference-a4jpage-a4jpage_rendering-0.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - <para> - This definition will render on an XHTML page as follows: - </para> - -<programlisting language="XML" role="XML"><xi:include href="extras/exam-Component_Reference-a4jpage-a4jpage_rendering-1.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - </example> - <para> - When using the <productname>Ajax4jsf</productname> - framework with <productname>MyFaces</productname> - version 1.2.2 and lower, the <sgmltag>&lt;f:view&gt;</sgmltag> JSP tag does not receive control for encoding contents during the <literal>RENDER_RESPONSE</literal> phase. As a result, Ajax fails to receive control and send responses. The <sgmltag>&lt;a4j:page&gt;</sgmltag> component solves this problem by wrapping the Ajax areas to be updated. Later versions of <productname>MyFaces</productname> - do not have this problem, and as such do not require the use of the <sgmltag>&lt;a4j:page&gt;</sgmltag> component. - </para> - </section> - - <section id="sect-Component_Reference-Containers-a4jregion"> - <title><sgmltag>&lt;a4j:region&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.AjaxRegion</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>org.ajax4jsf.AjaxRegion</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.component.html.HtmlAjaxRegion</classname> - </para> - </listitem> - <listitem> - <para> - renderer-type: <classname>org.ajax4jsf.components.AjaxRegionRenderer</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:region&gt;</sgmltag> component specifies a part of the document object model (<acronym>DOM</acronym>) tree to be processed on the server. The processing includes data handling during decoding, conversion, validation, and model updating. When not using <sgmltag>&lt;a4j:region&gt;</sgmltag>, the entire view functions as a region. - </para> - <para> - The whole form is still submitted to the server, but only the specified region is processed. Regions can be nested, in which case only the immediate region of the component initiating the request will be processed. - </para> - </section> +<!-- FIXME NOT IN A2 --> +<!-- <section id="sect-Component_Reference-Containers-a4jpage">--> +<!-- <title><sgmltag>&lt;a4j:page&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.components.Page</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>org.ajax4jsf.components.AjaxRegion</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.component.html.HtmlPage</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- renderer-type: <classname>org.ajax4jsf.components.AjaxPageRenderer</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:page&gt;</sgmltag> component encodes a full HTML-page structure using only one tag. It renders complete <sgmltag>&lt;!DOCTYPE&gt;</sgmltag>, <sgmltag>&lt;html&gt;</sgmltag>, <sgmltag>&lt;head&gt;</sgmltag>, <sgmltag>&lt;title&gt;</sgmltag>, and <sgmltag>&lt;body&gt;</sgmltag> tags using the specified attributes and facets. Additionally, the <sgmltag>&lt;a4j:page&gt;</sgmltag> component solves an incompatibility issue between early versions of <productname>MyFaces</productname>--> +<!-- and the <productname>Ajax4jsf</productname>--> +<!-- framework.--> +<!-- </para>--> +<!-- <para>--> +<!-- The <varname>pageTitle</varname> attribute is rendered as a <sgmltag>&lt;title&gt;</sgmltag> element. The component uses the <literal>head</literal> facet to define the contents of the HTML <sgmltag>&lt;head&gt;</sgmltag> element. The <literal>format</literal> facet defines the page layout format for encoding the <sgmltag>&lt;!DOCTYPE&gt;</sgmltag> element. There rest of the contents of the <sgmltag>&lt;a4j:page&gt;</sgmltag> component are rendered as part of the <sgmltag>&lt;body&gt;</sgmltag> element.--> +<!-- </para>--> +<!-- <example id="exam-Component_Reference-a4jpage-a4jpage_rendering">--> +<!-- <title><sgmltag>&lt;a4j:page&gt;</sgmltag> rendering</title>--> +<!-- <para>--> +<!-- An <sgmltag>&lt;a4j:page&gt;</sgmltag> component can be defined as follows:--> +<!-- </para>--> +<!-- --> +<!--<programlisting language="XML" role="XML"><xi:include href="extras/exam-Component_Reference-a4jpage-a4jpage_rendering-0.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />--> +<!--</programlisting>--> +<!-- <para>--> +<!-- This definition will render on an XHTML page as follows:--> +<!-- </para>--> +<!-- --> +<!--<programlisting language="XML" role="XML"><xi:include href="extras/exam-Component_Reference-a4jpage-a4jpage_rendering-1.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />--> +<!--</programlisting>--> +<!-- </example>--> +<!-- <para>--> +<!-- When using the <productname>Ajax4jsf</productname>--> +<!-- framework with <productname>MyFaces</productname>--> +<!-- version 1.2.2 and lower, the <sgmltag>&lt;f:view&gt;</sgmltag> JSP tag does not receive control for encoding contents during the <literal>RENDER_RESPONSE</literal> phase. As a result, Ajax fails to receive control and send responses. The <sgmltag>&lt;a4j:page&gt;</sgmltag> component solves this problem by wrapping the Ajax areas to be updated. Later versions of <productname>MyFaces</productname>--> +<!-- do not have this problem, and as such do not require the use of the <sgmltag>&lt;a4j:page&gt;</sgmltag> component.--> +<!-- </para>--> +<!-- </section>--> +<!-- --> +<!-- <section id="sect-Component_Reference-Containers-a4jregion">--> +<!-- <title><sgmltag>&lt;a4j:region&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.AjaxRegion</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>org.ajax4jsf.AjaxRegion</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.component.html.HtmlAjaxRegion</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- renderer-type: <classname>org.ajax4jsf.components.AjaxRegionRenderer</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:region&gt;</sgmltag> component specifies a part of the document object model (<acronym>DOM</acronym>) tree to be processed on the server. The processing includes data handling during decoding, conversion, validation, and model updating. When not using <sgmltag>&lt;a4j:region&gt;</sgmltag>, the entire view functions as a region.--> +<!-- </para>--> +<!-- <para>--> +<!-- The whole form is still submitted to the server, but only the specified region is processed. Regions can be nested, in which case only the immediate region of the component initiating the request will be processed.--> +<!-- </para>--> +<!-- </section>--> </chapter> Modified: root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Resources.xml =================================================================== --- root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Resources.xml 2010-06-03 16:45:54 UTC (rev 17491) +++ root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Resources.xml 2010-06-03 16:46:33 UTC (rev 17492) @@ -6,219 +6,220 @@ <para> This chapter covers those components used to handle and manage resources and beans. </para> - <section id="sect-Component_Reference-Resources-a4jloadBundle"> - <title><sgmltag>&lt;a4j:loadBundle&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.Bundle</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>org.ajax4jsf.Bundle</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.component.html.AjaxLoadBundle</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> component is used to load resource bundles to aid in localization of an application. The bundles are localized to the locale of the current view, and properties are stored as a map in the current request attributes. - </para> - <para> - The <sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> component allows bundles to be accessed by Ajax requests working in their own address scopes. This solves the problem of using the <acronym>JSF</acronym> <sgmltag>&lt;h:loadBundle&gt;</sgmltag> component with Ajax, where bundle information loaded with the page was unavailable for later Ajax requests. - </para> - <para> - Resource bundles are registered in the Faces configuration file, <filename>faces-config.xml</filename>. - </para> - <example id="exam-Component_Reference-a4jloadBundle-a4jloadBundle_example"> - <title><sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> example</title> - <para> - This example shows a simple application capable of switching between different localized languages. - </para> - <procedure> - <step id="step-Component_Reference-a4jloadBundle_example-Create_resource_bundles"> - <title>Create resource bundles</title> - <para> - String resource bundles are contained in files with a <filename class="extension">.properties</filename> extension. The files consist of a list of entries, each with a unique name and a corresponding value. A seperate file is required for each language. Append the filename with the locale identifier (<literal>en</literal> for English, for example). - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/figu-Component_Reference-a4jloadBundle-Create_resource_bundles.png" format="PNG" width="444" /> - </imageobject> - <textobject> - <para> - Resource bundles for English (<literal>en</literal>), German (<literal>de</literal>), and Italian (<literal>it</literal>). A single entry (<literal>greeting</literal>) has been localized for each bundle. - </para> - </textobject> - </mediaobject> - </step> - <step id="step-Component_Reference-a4jloadBundle_example-Register_bundles_in_Faces_configuration_file"> - <title>Register bundles in Faces configuration file</title> - <para> - The resource bundles need to be registered in the Faces configuration file, <filename>faces-config.xml</filename>. The filename is defined with the <sgmltag>&lt;message-bundle&gt;</sgmltag> tag, without the locale code and without the extension. The supported locale codes are listed with <sgmltag>&lt;supported-locale&gt;</sgmltag> tags. - </para> - -<programlisting language="XML" role="XML"> -<xi:include href="extras/exam-Component_Reference-a4jloadBundle-a4jloadBundle_example-0.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - </step> - <step id="step-Component_Reference-a4jloadBundle_example-Create_method_to_set_locale"> - <title>Create method to set locale</title> - <para> - The <acronym>JSF</acronym> <methodname>javax.faces.component.UIViewRoot.setLocale()</methodname> method can be used to update the locale through a Java class: - </para> - -<programlisting language="Java" role="JAVA"> -<xi:include href="extras/exam-Component_Reference-a4jloadBundle-a4jloadBundle_example-1.js" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - </step> - <step id="step-Component_Reference-a4jloadBundle_example-Add_a4jloadBundle_to_the_JSP_page"> - <title>Add <sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> to the <acronym>JSP</acronym> page</title> - <para> - The <sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> component is added to the application, and links to change the locale will update the displayed text. - </para> - -<programlisting language="XML" role="XML"> -<xi:include href="extras/exam-Component_Reference-a4jloadBundle-a4jloadBundle_example-2.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - <mediaobject> - <imageobject> - <imagedata fileref="images/figu-Component_Reference-a4jloadBundle-Add_a4jloadBundle_to_the_JSP_page.png" format="PNG" /> - </imageobject> - <textobject> - <para> - The output text displayed on a page. It can be changed by clicking the command link for either German, English, or Italian. - </para> - </textobject> - </mediaobject> - </step> - </procedure> - - <para> - Clicking on the different links will render the localized string as appropriate. - </para> - </example> - </section> +<!-- FIXME NOT IN A2 --> +<!-- <section id="sect-Component_Reference-Resources-a4jloadBundle">--> +<!-- <title><sgmltag>&lt;a4j:loadBundle&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.Bundle</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>org.ajax4jsf.Bundle</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.component.html.AjaxLoadBundle</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> component is used to load resource bundles to aid in localization of an application. The bundles are localized to the locale of the current view, and properties are stored as a map in the current request attributes.--> +<!-- </para>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> component allows bundles to be accessed by Ajax requests working in their own address scopes. This solves the problem of using the <acronym>JSF</acronym> <sgmltag>&lt;h:loadBundle&gt;</sgmltag> component with Ajax, where bundle information loaded with the page was unavailable for later Ajax requests.--> +<!-- </para>--> +<!-- <para>--> +<!-- Resource bundles are registered in the Faces configuration file, <filename>faces-config.xml</filename>.--> +<!-- </para>--> +<!-- <example id="exam-Component_Reference-a4jloadBundle-a4jloadBundle_example">--> +<!-- <title><sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> example</title>--> +<!-- <para>--> +<!-- This example shows a simple application capable of switching between different localized languages.--> +<!-- </para>--> +<!-- <procedure>--> +<!-- <step id="step-Component_Reference-a4jloadBundle_example-Create_resource_bundles">--> +<!-- <title>Create resource bundles</title>--> +<!-- <para>--> +<!-- String resource bundles are contained in files with a <filename class="extension">.properties</filename> extension. The files consist of a list of entries, each with a unique name and a corresponding value. A seperate file is required for each language. Append the filename with the locale identifier (<literal>en</literal> for English, for example).--> +<!-- </para>--> +<!-- <mediaobject>--> +<!-- <imageobject>--> +<!-- <imagedata fileref="images/figu-Component_Reference-a4jloadBundle-Create_resource_bundles.png" format="PNG" width="444" />--> +<!-- </imageobject>--> +<!-- <textobject>--> +<!-- <para>--> +<!-- Resource bundles for English (<literal>en</literal>), German (<literal>de</literal>), and Italian (<literal>it</literal>). A single entry (<literal>greeting</literal>) has been localized for each bundle.--> +<!-- </para>--> +<!-- </textobject>--> +<!-- </mediaobject>--> +<!-- </step>--> +<!-- <step id="step-Component_Reference-a4jloadBundle_example-Register_bundles_in_Faces_configuration_file">--> +<!-- <title>Register bundles in Faces configuration file</title>--> +<!-- <para>--> +<!-- The resource bundles need to be registered in the Faces configuration file, <filename>faces-config.xml</filename>. The filename is defined with the <sgmltag>&lt;message-bundle&gt;</sgmltag> tag, without the locale code and without the extension. The supported locale codes are listed with <sgmltag>&lt;supported-locale&gt;</sgmltag> tags.--> +<!-- </para>--> +<!-- --> +<!--<programlisting language="XML" role="XML">--> +<!--<xi:include href="extras/exam-Component_Reference-a4jloadBundle-a4jloadBundle_example-0.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />--> +<!--</programlisting>--> +<!-- </step>--> +<!-- <step id="step-Component_Reference-a4jloadBundle_example-Create_method_to_set_locale">--> +<!-- <title>Create method to set locale</title>--> +<!-- <para>--> +<!-- The <acronym>JSF</acronym> <methodname>javax.faces.component.UIViewRoot.setLocale()</methodname> method can be used to update the locale through a Java class:--> +<!-- </para>--> +<!-- --> +<!--<programlisting language="Java" role="JAVA">--> +<!--<xi:include href="extras/exam-Component_Reference-a4jloadBundle-a4jloadBundle_example-1.js" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />--> +<!--</programlisting>--> +<!-- </step>--> +<!-- <step id="step-Component_Reference-a4jloadBundle_example-Add_a4jloadBundle_to_the_JSP_page">--> +<!-- <title>Add <sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> to the <acronym>JSP</acronym> page</title>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:loadBundle&gt;</sgmltag> component is added to the application, and links to change the locale will update the displayed text.--> +<!-- </para>--> +<!-- --> +<!--<programlisting language="XML" role="XML">--> +<!--<xi:include href="extras/exam-Component_Reference-a4jloadBundle-a4jloadBundle_example-2.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />--> +<!--</programlisting>--> +<!-- <mediaobject>--> +<!-- <imageobject>--> +<!-- <imagedata fileref="images/figu-Component_Reference-a4jloadBundle-Add_a4jloadBundle_to_the_JSP_page.png" format="PNG" />--> +<!-- </imageobject>--> +<!-- <textobject>--> +<!-- <para>--> +<!-- The output text displayed on a page. It can be changed by clicking the command link for either German, English, or Italian.--> +<!-- </para>--> +<!-- </textobject>--> +<!-- </mediaobject>--> +<!-- </step>--> +<!-- </procedure>--> +<!-- --> +<!-- <para>--> +<!-- Clicking on the different links will render the localized string as appropriate.--> +<!-- </para>--> +<!-- </example>--> +<!-- </section>--> +<!-- --> +<!-- <section id="sect-Component_Reference-Resources-a4jloadScript">--> +<!-- <title><sgmltag>&lt;a4j:loadScript&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.LoadScript</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>org.ajax4jsf.LoadScript</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.component.html.HtmlLoadScript</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- renderer-type: <classname>org.ajax4jsf.LoadScriptRenderer</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:loadScript&gt;</sgmltag> component allows scripts to be loaded from external sources such as <filename>jar</filename> files.--> +<!-- </para>--> +<!-- <para>--> +<!-- The required <varname>src</varname> attribute defines the path to the script. A leading slash (<literal>/</literal>) represents the root of the web context. The <code>resource://</code> prefix can be used to access a file in the RichFaces resource framework. The path is passed to the <methodname>getResourceURL()</methodname> method of the application's <classname>ViewHandler</classname>, with the result then being passed through the <methodname>encodeResourceURL()</methodname> method of <classname>ExternalContext</classname>.--> +<!-- </para>--> +<!-- <example id="exam-Component_Reference-a4jloadScript-a4jloadScript_example">--> +<!-- <title><sgmltag>&lt;a4j:loadScript&gt;</sgmltag> example</title>--> +<!-- --> +<!--<programlisting language="XML" role="XML">--> +<!--&lt;a4j:loadScript src="resource:///org/mycompany/assets/script/focus.js" /&gt;--> +<!--</programlisting>--> +<!-- </example>--> +<!-- </section>--> +<!-- --> +<!-- <section id="sect-Component_Reference-Resources-a4jloadStyle">--> +<!-- <title><sgmltag>&lt;a4j:loadStyle&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.LoadStyle</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>org.ajax4jsf.LoadStyle</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.component.html.HtmlLoadStyle</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- renderer-type: <classname>org.ajax4jsf.LoadStyleRenderer</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:loadStyle&gt;</sgmltag> component allows a style sheet to be loaded from an external source, such as a <filename>jar</filename> file. The style sheet links are inserted into the head element.--> +<!-- </para>--> +<!-- <para>--> +<!-- The required <varname>src</varname> attribute defines the path to the script. A leading slash (<literal>/</literal>) represents the root of the web context. The <code>resource://</code> prefix can be used to access a file in the RichFaces resource framework. The path is passed to the <methodname>getResourceURL()</methodname> method of the application's <classname>ViewHandler</classname>, with the result then being passed through the <methodname>encodeResourceURL()</methodname> method of <classname>ExternalContext</classname>.--> +<!-- </para>--> +<!-- <example id="exam-Component_Reference-a4jloadStyle-a4jloadStyle_example">--> +<!-- <title><sgmltag>&lt;a4j:loadStyle&gt;</sgmltag> example</title>--> +<!-- --> +<!--<programlisting language="XML" role="XML">--> +<!--&lt;a4j:loadStyle src="resource:///org/mycompany/assets/script/focus.js" /&gt;--> +<!--</programlisting>--> +<!-- </example>--> +<!-- </section>--> +<!-- --> +<!-- <section id="sect-Component_Reference-Resources-a4jkeepAlive">--> +<!-- <title><sgmltag>&lt;a4j:keepAlive&gt;</sgmltag></title>--> +<!-- <itemizedlist>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-type: <classname>org.ajax4jsf.components.KeepAlive</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-family: <classname>org.ajax4jsf.components.AjaxKeepAlive</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- <listitem>--> +<!-- <para>--> +<!-- component-class: <classname>org.ajax4jsf.components.AjaxKeepAlive</classname>--> +<!-- </para>--> +<!-- </listitem>--> +<!-- </itemizedlist>--> +<!-- <para>--> +<!-- The <sgmltag>&lt;a4j:keepAlive&gt;</sgmltag> component allows the state of a managed bean to be retained between Ajax requests.--> +<!-- </para>--> +<!-- <para>--> +<!-- Managed beans can be declared with the <literal>request</literal> scope in the <filename>faces-config.xml</filename> configuration file, using the <sgmltag>&lt;managed-bean-scope&gt;</sgmltag> tag. Any references to the bean instance after the request has ended will cause the server to throw an illegal argument exception. The <sgmltag>&lt;a4j:keepAlive&gt;</sgmltag> component avoids this be maintaining the state of the whole bean object for subsequent requests.--> +<!-- </para>--> +<!-- <para>--> +<!-- The <varname>beanName</varname> attribute uses JSF Expression Language (<acronym>EL</acronym>) to define the request scope bean name to keep alive. The expression must resolve to a managed bean instance. The <varname>ajaxOnly</varname> attribute determines whether or not the value of the bean should be available during non-Ajaxx requests; if <code>ajaxOnly="true"</code>, the request-scope bean keeps its value during Ajax requests, but any non-Ajax requests will re-create the bean as a regular request-scope bean.--> +<!-- </para>--> +<!-- <example id="exam-Component_Reference-a4jkeepAlive-a4jkeepAlive_example">--> +<!-- <title><sgmltag>&lt;a4j:keepAlive&gt;</sgmltag> example</title>--> +<!-- --> +<!--<programlisting language="XML" role="XML">--> +<!--&lt;a4j:keepAlive beanName="#{myClass.testBean}" /&gt;--> +<!--</programlisting>--> +<!-- </example>--> +<!-- </section>--> - <section id="sect-Component_Reference-Resources-a4jloadScript"> - <title><sgmltag>&lt;a4j:loadScript&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.LoadScript</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>org.ajax4jsf.LoadScript</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.component.html.HtmlLoadScript</classname> - </para> - </listitem> - <listitem> - <para> - renderer-type: <classname>org.ajax4jsf.LoadScriptRenderer</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:loadScript&gt;</sgmltag> component allows scripts to be loaded from external sources such as <filename>jar</filename> files. - </para> - <para> - The required <varname>src</varname> attribute defines the path to the script. A leading slash (<literal>/</literal>) represents the root of the web context. The <code>resource://</code> prefix can be used to access a file in the RichFaces resource framework. The path is passed to the <methodname>getResourceURL()</methodname> method of the application's <classname>ViewHandler</classname>, with the result then being passed through the <methodname>encodeResourceURL()</methodname> method of <classname>ExternalContext</classname>. - </para> - <example id="exam-Component_Reference-a4jloadScript-a4jloadScript_example"> - <title><sgmltag>&lt;a4j:loadScript&gt;</sgmltag> example</title> - -<programlisting language="XML" role="XML"> -&lt;a4j:loadScript src="resource:///org/mycompany/assets/script/focus.js" /&gt; -</programlisting> - </example> - </section> - - <section id="sect-Component_Reference-Resources-a4jloadStyle"> - <title><sgmltag>&lt;a4j:loadStyle&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.LoadStyle</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>org.ajax4jsf.LoadStyle</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.component.html.HtmlLoadStyle</classname> - </para> - </listitem> - <listitem> - <para> - renderer-type: <classname>org.ajax4jsf.LoadStyleRenderer</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:loadStyle&gt;</sgmltag> component allows a style sheet to be loaded from an external source, such as a <filename>jar</filename> file. The style sheet links are inserted into the head element. - </para> - <para> - The required <varname>src</varname> attribute defines the path to the script. A leading slash (<literal>/</literal>) represents the root of the web context. The <code>resource://</code> prefix can be used to access a file in the RichFaces resource framework. The path is passed to the <methodname>getResourceURL()</methodname> method of the application's <classname>ViewHandler</classname>, with the result then being passed through the <methodname>encodeResourceURL()</methodname> method of <classname>ExternalContext</classname>. - </para> - <example id="exam-Component_Reference-a4jloadStyle-a4jloadStyle_example"> - <title><sgmltag>&lt;a4j:loadStyle&gt;</sgmltag> example</title> - -<programlisting language="XML" role="XML"> -&lt;a4j:loadStyle src="resource:///org/mycompany/assets/script/focus.js" /&gt; -</programlisting> - </example> - </section> - - <section id="sect-Component_Reference-Resources-a4jkeepAlive"> - <title><sgmltag>&lt;a4j:keepAlive&gt;</sgmltag></title> - <itemizedlist> - <listitem> - <para> - component-type: <classname>org.ajax4jsf.components.KeepAlive</classname> - </para> - </listitem> - <listitem> - <para> - component-family: <classname>org.ajax4jsf.components.AjaxKeepAlive</classname> - </para> - </listitem> - <listitem> - <para> - component-class: <classname>org.ajax4jsf.components.AjaxKeepAlive</classname> - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;a4j:keepAlive&gt;</sgmltag> component allows the state of a managed bean to be retained between Ajax requests. - </para> - <para> - Managed beans can be declared with the <literal>request</literal> scope in the <filename>faces-config.xml</filename> configuration file, using the <sgmltag>&lt;managed-bean-scope&gt;</sgmltag> tag. Any references to the bean instance after the request has ended will cause the server to throw an illegal argument exception. The <sgmltag>&lt;a4j:keepAlive&gt;</sgmltag> component avoids this be maintaining the state of the whole bean object for subsequent requests. - </para> - <para> - The <varname>beanName</varname> attribute uses JSF Expression Language (<acronym>EL</acronym>) to define the request scope bean name to keep alive. The expression must resolve to a managed bean instance. The <varname>ajaxOnly</varname> attribute determines whether or not the value of the bean should be available during non-Ajaxx requests; if <code>ajaxOnly="true"</code>, the request-scope bean keeps its value during Ajax requests, but any non-Ajax requests will re-create the bean as a regular request-scope bean. - </para> - <example id="exam-Component_Reference-a4jkeepAlive-a4jkeepAlive_example"> - <title><sgmltag>&lt;a4j:keepAlive&gt;</sgmltag> example</title> - -<programlisting language="XML" role="XML"> -&lt;a4j:keepAlive beanName="#{myClass.testBean}" /&gt; -</programlisting> - </example> - </section> - <section id="sect-Component_Reference-Resources-a4jmediaOutput"> <title><sgmltag>&lt;a4j:mediaOutput&gt;</sgmltag></title> <itemizedlist>