Author: artdaw
Date: 2009-07-07 15:13:33 -0400 (Tue, 07 Jul 2009)
New Revision: 14818
Added:
branches/community/3.3.X/docs/userguide/en/src/main/resources/images/supportSample.png
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.desc.xml
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.xml
Log:
https://jira.jboss.org/jira/browse/RF-7340 - <a4j:support> was reviewed
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.desc.xml
===================================================================
---
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.desc.xml 2009-07-07
18:11:35 UTC (rev 14817)
+++
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.desc.xml 2009-07-07
19:13:33 UTC (rev 14818)
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<root>
+<section>
<section>
<sectioninfo>
<keywordset>
@@ -9,8 +9,16 @@
</sectioninfo>
<title>Description</title>
- <para>The <emphasis
role="bold"><property><a4j:support></property></emphasis>
component enriches any existing JSF or RichFaces component with an Ajax capability by
generating an asynchronous Ajax requests for them.
- The requests are invoked by definite user activity and used for updating
and re-rendering page contents partially after a response from server.
+ <para>
+ The <emphasis
role="bold"><property><a4j:support></property></emphasis>
component
+ is the most important core component in the RichFaces library.
+ It enriches any existing non-Ajax JSF or RichFaces component with an Ajax
capability.
+ All the other RichFaces Ajax components are based on the same principles
+ <emphasis
role="bold"><property><a4j:support></property></emphasis>
has.
+ <!--
+ The requests are invoked by definite user activity and used for updating
+ and re-rendering page contents partially after a response from server.
+ -->
</para>
</section>
-</root>
\ No newline at end of file
+</section>
\ No newline at end of file
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.xml
===================================================================
---
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.xml 2009-07-07
18:11:35 UTC (rev 14817)
+++
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/support.xml 2009-07-07
19:13:33 UTC (rev 14818)
@@ -1,64 +1,75 @@
<?xml version='1.0' encoding='UTF-8'?>
-<chapter>
- <chapterinfo>
- <keywordset>
- <keyword>a4j:support</keyword>
- </keywordset>
- </chapterinfo>
- <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.Support</entry>
- </row>
- <row>
-
<entry>component-family</entry>
-
<entry>org.ajax4jsf.AjaxSupport</entry>
- </row>
- <row>
-
<entry>component-class</entry>
-
<entry>org.ajax4jsf.component.html.HtmlAjaxSupport</entry>
- </row>
- <row>
-
<entry>renderer-type</entry>
-
<entry>org.ajax4jsf.components.AjaxSupportRenderer</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <section>
- <title>Creating the Component with a Page Tag</title>
- <para>To create the simplest variant on a page nest the
<emphasis
role="bold"><property><a4j:support></property></emphasis>
into a component that is needed an Ajax functionality.
- Specify an event that will trigger an Ajax request and the
components to be rerendered after a response from server.</para>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting
role="XML"><![CDATA[<h:inputText value="#{bean.text}">
+<section>
+ <sectioninfo>
+ <keywordset>
+ <keyword>a4j:support</keyword>
+ </keywordset>
+ </sectioninfo>
+ <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.Support</entry>
+ </row>
+ <row>
+ <entry>component-family</entry>
+ <entry>org.ajax4jsf.AjaxSupport</entry>
+ </row>
+ <row>
+ <entry>component-class</entry>
+ <entry>org.ajax4jsf.component.html.HtmlAjaxSupport</entry>
+ </row>
+ <row>
+ <entry>renderer-type</entry>
+ <entry>org.ajax4jsf.components.AjaxSupportRenderer</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <section>
+ <title>Creating the Component with a Page Tag</title>
+ <para>
+ To create the simplest variant on a page you should put
+ <emphasis role="bold">
+ <property><a4j:support></property>
+ </emphasis>
+ as a nested element into the component that you want to enhance with
+ Ajax functionality.
+ You should also specify an event that will trigger
+ an Ajax request.
+ </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>
+ </section>
- <para>On every key-up event occuring inside the input field the
<emphasis
role="bold"><property><a4j:support></property></emphasis>
generates an Ajax request that submits the whole Form.
- The value for the <code>bean.text</code> will be
updated in the model and the component with the <code>repeater</code> ID will
be redrawn according to a new data after server responce.
- </para>
- </section>
-
- <section>
- <title>Creating the Component Dynamically Using
Java</title>
- <para>In order to add the <emphasis
role="bold"><property><a4j:support></property></emphasis>
in Java code you should add it as
<emphasis><property>facet</property></emphasis>, not
children:</para>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="JAVA"><![CDATA[HtmlInputText
inputText = new HtmlInputText();
+ <section>
+ <title>Creating the Component Dynamically Using Java</title>
+ <para>
+ In order to add the
+ <emphasis role="bold">
+ <property><a4j:support></property>
+ </emphasis>
+ in Java code you should add it as
+ <property>facet</property>
+ , not as a child:
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="JAVA"><![CDATA[HtmlInputText inputText = new
HtmlInputText();
...
HtmlAjaxSupport ajaxSupport = new HtmlAjaxSupport();
ajaxSupport.setActionExpression(FacesContext.getCurrentInstance().getApplication().getExpressionFactory().createMethodExpression(
@@ -67,151 +78,191 @@
ajaxSupport.setReRender("output");
inputText.getFacets().put("a4jsupport", ajaxSupport);
]]></programlisting>
- </section>
-
- <section>
- <title>Details of Usage</title>
- <para>
- The <emphasis
role="bold"><property><a4j:support></property></emphasis>
component created on a page as following
- </para>
-
- <programlisting role="XML"><![CDATA[<h:inputText
value="#{bean.text}">
+ </section>
+
+ <section>
+ <title>Details of Usage</title>
+ <para>
+ The <emphasis role="bold">
+ <property><a4j:support></property>
+ </emphasis>
+ component has two key attributes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ mandatory
+ <emphasis><property>"event"</property></emphasis>
attribute that defines the JavaScript event
+ the Ajax support will be attached to
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis><property>"reRender"</property></emphasis>
attribute that defines id(s)
+ of JSF component(s) that should be rerendered after an Ajax request
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ As mentioned above the <emphasis
role="bold"><property><a4j:support></property></emphasis>
component
+ adds Ajax capability to non-Ajax JSF components.
+ Let's create ajaxed <emphasis
role="bold"><property><h:selectOneMenu></property></emphasis>
called
+ "Planets and Their Moons".
+ </para>
+ <para>
+ We begin with the common behavior description. When a page is rendered you see only
one select box with the list of planets.
+ When you select a planet the <emphasis
role="bold"><property><h:dataTable></property></emphasis>
+ containig moons of the selected planet appears.
+ </para>
+ <para>
+ In other words we need <emphasis
role="bold"><property><h:selectOneMenu></property></emphasis>
+ with the nested <emphasis
role="bold"><property><a4j:support></property></emphasis>
component that
+ is attached to the <property>onchange</property> event.
+ </para>
+ <para>
+ When an Ajax response comes back the <emphasis
role="bold"><property><h:dataTable></property></emphasis>
+ is re-rendered on the server side and updated on the client.
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:form id="planetsForm">
+ <h:outputLabel value="Select the planet:" for="planets" />
+ <h:selectOneMenu id="planets"
value="#{planetsMoons.currentPlanet}"
valueChangeListener="#{planetsMoons.planetChanged}">
+ <f:selectItems value="#{planetsMoons.planetsList}" />
+ <a4j:support event="onchange" reRender="moons" />
+ </h:selectOneMenu>
+ <h:dataTable id="moons" value="#{planetsMoons.moonsList}"
var="item">
+ <h:column>
+ <h:outputText value="#{item}"/>
+ </h:column>
+ </h:dataTable>
+</h:form>
+...]]></programlisting>
+ <para>
+ Finally we need a backing bean:
+ </para>
+ <programlisting role="JAVA"><![CDATA[...
+public class PlanetsMoons {
+ private String currentPlanet="";
+ public List<SelectItem> planetsList = new ArrayList<SelectItem>();
+ public List<String> moonsList = new ArrayList<String>();
+ private static final String [] EARTH = {"The Moon"};
+ private static final String [] MARS = {"Deimos", "Phobos"};
+ private static final String [] JUPITER = {"Europa", "Gamymede",
"Callisto"};
+
+ public PlanetsMoons() {
+ SelectItem item = new SelectItem("earth", "Earth");
+ planetsList.add(item);
+ item = new SelectItem("mars", "Mars");
+ planetsList.add(item);
+ item = new SelectItem("jupiter", "Jupiter");
+ planetsList.add(item);
+ }
+
+ public void planetChanged(ValueChangeEvent event){
+ moonsList.clear();
+ String[] currentItems;
+ if (((String)event.getNewValue()).equals("earth")) {
+ currentItems = EARTH;
+ }else if(((String)event.getNewValue()).equals("mars")){
+ currentItems = MARS;
+ }else{
+ currentItems = JUPITER;
+ }
+ for (int i = 0; i < currentItems.length; i++) {
+ moonsList.add(currentItems[i]);
+ }
+ }
+
+ //Getters and Setters
+ ...
+}
+]]></programlisting>
+ <para>
+ There are two properties <code>planetsList</code> and
<code>moonsList</code>.
+ The <code>planetsList</code> is filled with planets names in the
constructor.
+ After you select the planet,
+ the <code>planetChanged()</code> listener is called and
+ the <code>moonsList</code> is populated with proper values of moons.
+ </para>
+ <para>
+ With the help of
+ <emphasis>
+ <property>"onsubmit"</property>
+ </emphasis>
+ and
+ <emphasis>
+ <property>"oncomplete"</property>
+ </emphasis>
+ attributes the <emphasis
role="bold"><property><a4j:support></property></emphasis>
component
+ allows to use JavaScript calls before an Ajax request
+ and after an Ajax response respectively.
+ You can easily add confirmation dialog for the planet select box and colorize
+ <emphasis
role="bold"><property><h:dataTable></property></emphasis>
after the Ajax response:
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:form id="planetsForm">
+ <h:outputLabel value="Select the planet:" for="planets" />
+ <h:selectOneMenu id="planets"
value="#{planetsMoons.currentPlanet}"
valueChangeListener="#{planetsMoons.planetChanged}">
+ <f:selectItems value="#{planetsMoons.planetsList}" />
+ <a4j:support event="onchange" reRender="moons"
+ onsubmit="if(!confirm('Are you sure to change the planet?'))
{form.reset(); return false;}"
+ oncomplete="document.getElementById('planetsForm:moonsPanel').style.backgroundColor='#c8dcf9';"
/>
+ </h:selectOneMenu>
+ <h:dataTable id="moons" value="#{planetsMoons.moonsList}"
var="item">
+ <h:column>
+ <h:outputText value="#{item}"/>
+ </h:column>
+ </h:dataTable>
+</h:form>
+...]]></programlisting>
+ <para>
+ There is the result:
+ </para>
+ <figure>
+ <title>
+ "Planets and Their Moons"
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/supportSample.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Information about the
+ <emphasis>
+ <property>"process"</property>
+ </emphasis>
+ attribute usage you can find in the "
+ <link linkend="process">Decide what to process</link>
+ " guide section.
+ </para>
+
+ <note>
+ <title>Tip:</title>
+ <para>
+ The
+ <emphasis role="bold">
+ <property><a4j:support></property>
+ </emphasis>
+ component created on a page as following
+ </para>
+ <programlisting role="XML"><![CDATA[<h:inputText
value="#{bean.text}">
<a4j:support event="onkeyup" reRender="output"
action="#{bean.action}"/>
</h:inputText>]]></programlisting>
-
- <para>is decoded in HTML as</para>
-
- <programlisting role="XML"><![CDATA[<input
onkeyup="A4J.AJAX.Submit( Some request parameters
)"/>]]></programlisting>
-
- <para>The
<emphasis><property>"onkeyup"</property></emphasis>
event calls an utility RichFaces method that submits Form by creating special marks for
the RichFaces filter informing that it is an Ajax request.
- Any quantity of supports that define component behavior could be added
to a component.
- </para>
-
- <note>
- <para>A lot of RichFaces components comes with built-in Ajax
support (read the Guide to find out what exactly) and have no need in the <emphasis
role="bold"><property><a4j:support></property></emphasis>.
- </para>
- </note>
-
- <para>With the help of
<emphasis><property>"onsubmit"</property></emphasis>
and
<emphasis><property>"oncomplete"</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 component allows different Ajax request managing ways
for its various optimization in particular conditions such as:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis
role="bold">limitation of the submit area and updating area for the
request</emphasis>
- </para>
- <para>
-
<emphasis><property>"ajaxSingle"</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>"limitToList"</property></emphasis>
is an attribute that allows to limit areas, which are updated after the responses;
- only these components defined in the
<emphasis><property>"reRender"</property></emphasis>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 and not all the components contained on a form (because
<code>ajaxSingle="true"</code>).
- </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 <emphasis
role="bold"><property><h:messages></property></emphasis>
is always updated (as it capturing all Ajax requests,
- located in ajaxRendered <emphasis
role="bold"><property><a4j:outputPanel></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
<code>limitToList="true"</code> the only component updated
is the one with <code>id="test"</code>.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">limitation of
requests frequency and updates quantity after the responses</emphasis>
- </para>
-
- <para>
-
<emphasis><property>"requestDelay"</property></emphasis>
is an attribute that defines a time interval in seconds minimally permissible between
responses;
- </para>
-
- <para>
-
<emphasis><property>"eventsQueue"</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>"ignoreDupResponces"</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>"timeout"</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 above
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 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>
-
- <para>
- Information about the
<emphasis><property>"process"</property></emphasis>
attribute usage you can find in the "<link
linkend="process">Decide what to process</link>" guide
section.
- </para>
- </section>
-
- <section>
- <title>Relevant resources links</title>
- <para>
- Visit <ulink
url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf...
demo page</ulink> at RichFaces live demo for examples of component usage and their
sources.
- </para>
-
- </section>
-</chapter>
+ <para>is decoded in HTML as</para>
+ <programlisting role="XML"><![CDATA[<input
onkeyup="A4J.AJAX.Submit( Some request parameters
)"/>]]></programlisting>
+ </note>
+ </section>
+ <section>
+ <title>Relevant resources links</title>
+ <para>
+ Visit
+ <ulink
+
url="http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf...
demo page</ulink>
+ at RichFaces live demo for examples of component usage and their
+ sources.
+ </para>
+
+ </section>
+</section>
Added:
branches/community/3.3.X/docs/userguide/en/src/main/resources/images/supportSample.png
===================================================================
(Binary files differ)
Property changes on:
branches/community/3.3.X/docs/userguide/en/src/main/resources/images/supportSample.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream