10 a.m.
Author: vkorluzhenko
Date: 2007-10-26 11:00:17 -0400 (Fri, 26 Oct 2007)
New Revision: 3568
Modified:
trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml
Log:
http://jira.jboss.com/jira/browse/RF-1110 - section "Creating and Using Your Own Skin
File" was rewritten.
Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2007-10-26
14:49:45 UTC (rev 3567)
+++ trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2007-10-26
15:00:17 UTC (rev 3568)
@@ -128,38 +128,38 @@
incorrect HTML code. </listitem>
</itemizedlist>
</section>
-
+
<section id="AjaxRequestOptimization">
- <?dbhtml filename="AjaxRequestOptimization.html"?>
- <title>Ajax Request Optimization</title>
- <section id="Re-Rendering">
- <?dbhtml filename="Re-Rendering.html"?>
- <title>Re-Rendering</title>
- <para>Ajax attributes are common for Ajax components such as <emphasis
role="bold">
- <property><a4j:support></property>
- </emphasis>, <emphasis role="bold">
- <property><a4j:commandButton></property>
- </emphasis>, <emphasis role="bold">
- <property><a4j:jsFunction></property>
- </emphasis>, <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis>, <emphasis role="bold">
- <property><a4j:push></property>
- </emphasis> and so on. Also, most RichFaces components with built-in Ajax
support have
- these attributes for a similar purpose. Ajax components attributes help
RichFaces to
- expose its features. Most of the attributes have default values. Thus, you can
start
- working with RichFaces without knowing the usage of these attribute. However,
their usage
- allows to tune the required Ajax behavior very smoothly.</para>
+ <?dbhtml filename="AjaxRequestOptimization.html"?>
+ <title>Ajax Request Optimization</title>
+ <section id="Re-Rendering">
+ <?dbhtml filename="Re-Rendering.html"?>
+ <title>Re-Rendering</title>
+ <para>Ajax attributes are common for Ajax components such as <emphasis
role="bold">
+ <property><a4j:support></property>
+ </emphasis>, <emphasis role="bold">
+ <property><a4j:commandButton></property>
+ </emphasis>, <emphasis role="bold">
+ <property><a4j:jsFunction></property>
+ </emphasis>, <emphasis role="bold">
+ <property><a4j:poll></property>
+ </emphasis>, <emphasis role="bold">
+ <property><a4j:push></property>
+ </emphasis> and so on. Also, most RichFaces components with built-in Ajax
support have these
+ attributes for a similar purpose. Ajax components attributes help RichFaces to
expose its
+ features. Most of the attributes have default values. Thus, you can start working
with
+ RichFaces without knowing the usage of these attribute. However, their usage
allows to tune
+ the required Ajax behavior very smoothly.</para>
- <para><emphasis>
- <property>"reRender"</property>
- </emphasis> is a key attribute. The attribute allows to point to area(s)
on a page that
- should be updated as a response on Ajax interaction. The value of the
<emphasis>
- <property>"reRender"</property>
- </emphasis> attribute is an id of the JSF component or an id list.
</para>
- <para>A simple example is placed below:</para>
+ <para><emphasis>
+ <property>"reRender"</property>
+ </emphasis> is a key attribute. The attribute allows to point to area(s) on
a page that
+ should be updated as a response on Ajax interaction. The value of the
<emphasis>
+ <property>"reRender"</property>
+ </emphasis> attribute is an id of the JSF component or an id list.
</para>
+ <para>A simple example is placed below:</para>
- <programlisting role="XML"><![CDATA[...
+ <programlisting role="XML"><![CDATA[...
<a4j:commandButton value="update"
reRender="infoBlock"/>
...
<h:panelGrid id="infoBlock">
@@ -168,31 +168,31 @@
...
]]></programlisting>
- <para>The value of <emphasis>
- <property>"reRender"</property>
- </emphasis> attribute of the <emphasis role="bold">
- <property><a4j:commandButton></property>
- </emphasis> tag defines which part(s) of your page is (are) to be
updated. In this case,
- the only part of the page to update is the <emphasis
role="bold">
- <property><h:panelGrid></property>
- </emphasis> tag because its ID value matches to the value of
<emphasis>
- <property>"reRender"</property>
- </emphasis> attribute. As you see, it's not difficult to update
multiple elements
- on the page, only list their IDs as the value of <emphasis>
- <property>"reRender"</property>
- </emphasis>.</para>
+ <para>The value of <emphasis>
+ <property>"reRender"</property>
+ </emphasis> attribute of the <emphasis role="bold">
+ <property><a4j:commandButton></property>
+ </emphasis> tag defines which part(s) of your page is (are) to be updated.
In this case, the
+ only part of the page to update is the <emphasis role="bold">
+ <property><h:panelGrid></property>
+ </emphasis> tag because its ID value matches to the value of
<emphasis>
+ <property>"reRender"</property>
+ </emphasis> attribute. As you see, it's not difficult to update
multiple elements
+ on the page, only list their IDs as the value of <emphasis>
+ <property>"reRender"</property>
+ </emphasis>.</para>
- <para><emphasis>
- <property>"reRender"</property>
- </emphasis> uses <ulink
-
url="http://java.sun.com/javaee/javaserverfaces/1.2_MR1/docs/api/jav...
- >UIComponent.findComponent() algorithm</ulink> (with some additional
exceptions) to find
- the component in the component tree. As can you see, the algorithm presumes
several steps.
- Each other step is used if the previous step is not successful. Therefore, you
can define
- how fast the component is found mentioning it more precisely. The following
example shows
- the difference in approaches (both buttons will work
successfully):</para>
+ <para><emphasis>
+ <property>"reRender"</property>
+ </emphasis> uses <ulink
+
url="http://java.sun.com/javaee/javaserverfaces/1.2_MR1/docs/api/jav...
+ >UIComponent.findComponent() algorithm</ulink> (with some additional
exceptions) to find
+ the component in the component tree. As can you see, the algorithm presumes
several steps.
+ Each other step is used if the previous step is not successful. Therefore, you
can define
+ how fast the component is found mentioning it more precisely. The following
example shows
+ the difference in approaches (both buttons will work successfully):</para>
- <programlisting role="XML"><![CDATA[...
+ <programlisting role="XML"><![CDATA[...
<h:form id="form1">
...
<a4j: commandButton value="Usual Way" reRender="infoBlock,
infoBlock2" />
@@ -212,288 +212,281 @@
...
]]></programlisting>
- <para>It's also possible to use JSF EL expression as a value of
the reRender
- attribute. It might be a property of types Set, Collection, Array or simple
String. The EL
- for reRender is resolved right before the Render Response phase. Hence, you can
calculate
- what should be re-rendered on any previous phase during the Ajax request
processing.</para>
+ <para>It's also possible to use JSF EL expression as a value of the
reRender
+ attribute. It might be a property of types Set, Collection, Array or simple
String. The EL
+ for reRender is resolved right before the Render Response phase. Hence, you can
calculate
+ what should be re-rendered on any previous phase during the Ajax request
processing.</para>
- <para>Most common problem with using reRender is pointing it to the
component that has a <emphasis>
- <property>"reRender"</property>
- </emphasis> attribute. Note, that JSF does not mark the place in the
browser DOM where the
- outcome of the component should be placed in case the <emphasis>
- <property>"rendered"</property>
- </emphasis> condition returns false. Therefore, after the component
becomes rendered
- during the Ajax request, RichFaces delivers the rendered code to the client,
but does not
- update a page, because the place for update is unknown. You need to point to
one of the
- parent components that has no <emphasis>
- <property>"rendered"</property>
- </emphasis> attribute. As an alternative, you can wrap the component with
<emphasis
- role="bold">
- <property><a4j:outputPanel></property>
- </emphasis>
layout=<property>"none"</property>.</para>
+ <para>Most common problem with using reRender is pointing it to the component
that has a <emphasis>
+ <property>"reRender"</property>
+ </emphasis> attribute. Note, that JSF does not mark the place in the
browser DOM where the
+ outcome of the component should be placed in case the <emphasis>
+ <property>"rendered"</property>
+ </emphasis> condition returns false. Therefore, after the component becomes
rendered during
+ the Ajax request, RichFaces delivers the rendered code to the client, but does
not update a
+ page, because the place for update is unknown. You need to point to one of the
parent
+ components that has no <emphasis>
+ <property>"rendered"</property>
+ </emphasis> attribute. As an alternative, you can wrap the component with
<emphasis
+ role="bold">
+ <property><a4j:outputPanel></property>
+ </emphasis>
layout=<property>"none"</property>.</para>
- <para><emphasis>
- <property>"ajaxRendered" </property>
- </emphasis> attribute of the <emphasis role="bold">
- <property><a4j:outputPanel></property>
- </emphasis> set to
<property>"true"</property> allows to define the area
- of the page that will be re-rendered even if it is not pointed in the reRender
attribute
- explicitly. It might be useful if you have an area on a page that should be
updated as a
- response on any Ajax request. For example, the following code allows to output
error
- messages regardless of what Ajax request causes the Validation phase failed.
</para>
- <programlisting role="XML"><![CDATA[...
+ <para><emphasis>
+ <property>"ajaxRendered" </property>
+ </emphasis> attribute of the <emphasis role="bold">
+ <property><a4j:outputPanel></property>
+ </emphasis> set to
<property>"true"</property> allows to define the area
+ of the page that will be re-rendered even if it is not pointed in the reRender
attribute
+ explicitly. It might be useful if you have an area on a page that should be
updated as a
+ response on any Ajax request. For example, the following code allows to output
error
+ messages regardless of what Ajax request causes the Validation phase failed.
</para>
+ <programlisting role="XML"><![CDATA[...
<a4j:outputPanel ajaxRendered="true">
<h:messages />
</a4j:outputPanel>
...
]]></programlisting>
- <para><emphasis>
- <property>"limitToList"</property>
- </emphasis> attribute allows to dismiss the behavior of the <emphasis
role="bold">
- <property><a4j:outputPanel></property>
- </emphasis>
- <emphasis>
- <property>"ajaxRendered" </property>
- </emphasis> attribute. "limitToList" =
- <property>"false"</property> means to update
only the area(s) that
- mentioned in the <emphasis/>"reRender"<property/>
attribute explicitly.
- All output panels with
-
"ajaxRendered"=<property>"true"</property>
will be
- ignored.</para>
- </section>
+ <para><emphasis>
+ <property>"limitToList"</property>
+ </emphasis> attribute allows to dismiss the behavior of the <emphasis
role="bold">
+ <property><a4j:outputPanel></property>
+ </emphasis>
+ <emphasis>
+ <property>"ajaxRendered" </property>
+ </emphasis> attribute. "limitToList" =
+ <property>"false"</property> means to update only
the area(s) that
+ mentioned in the <emphasis/>"reRender"<property/>
attribute explicitly.
+ All output panels with
+
"ajaxRendered"=<property>"true"</property>
will be
+ ignored.</para>
+ </section>
- <section id="QueueandTrafficFloodProtection">
- <?dbhtml filename="QueueandTrafficFloodProtection.html"?>
- <title>Queue and Traffic Flood Protection</title>
- <para><emphasis>
- <property>"eventsQueue"</property>
- </emphasis> attribute defines the name of the queue that will be used to
order upcoming
- Ajax requests. By default, RichFaces does not queue Ajax requests. If events
are produced
- simultaneously, they will come to the server simultaneously. JSF
implementations
- (especially, the very first ones) does not guaranty that the request that comes
first will
- be served or passed into the JSF lifecycle first. The order how the server side
data will
- be modified in case of simultaneous request might be unpredictable. Usage of
eventsQueue
- attribute allows to avoid possible mess. Define the queue name explicitly, if
you expect
- intensive Ajax traffic in your application.</para>
- <para>The next request posted in the same queue will wait until the previos
one is not
- processed and Ajax Response is returned back if the <emphasis>
- <property>"eventsQueue"</property>
- </emphasis> attribute is defined. In addition, Richfaces starts to remove
from the queue
- "similar" requests. "Similar'"requests
are the
- requests produced by the same event. For example, according to the following
code, only
- the newest request will be sent to the server if a user types very fast and has
typed the
- several characters already before the previous Ajax Response is
back.</para>
+ <section id="QueueandTrafficFloodProtection">
+ <?dbhtml filename="QueueandTrafficFloodProtection.html"?>
+ <title>Queue and Traffic Flood Protection</title>
+ <para><emphasis>
+ <property>"eventsQueue"</property>
+ </emphasis> attribute defines the name of the queue that will be used to
order upcoming Ajax
+ requests. By default, RichFaces does not queue Ajax requests. If events are
produced
+ simultaneously, they will come to the server simultaneously. JSF implementations
+ (especially, the very first ones) does not guaranty that the request that comes
first will
+ be served or passed into the JSF lifecycle first. The order how the server side
data will be
+ modified in case of simultaneous request might be unpredictable. Usage of
eventsQueue
+ attribute allows to avoid possible mess. Define the queue name explicitly, if you
expect
+ intensive Ajax traffic in your application.</para>
+ <para>The next request posted in the same queue will wait until the previos
one is not
+ processed and Ajax Response is returned back if the <emphasis>
+ <property>"eventsQueue"</property>
+ </emphasis> attribute is defined. In addition, Richfaces starts to remove
from the queue
+ "similar" requests. "Similar'"requests
are the requests
+ produced by the same event. For example, according to the following code, only
the newest
+ request will be sent to the server if a user types very fast and has typed the
several
+ characters already before the previous Ajax Response is back.</para>
- <programlisting role="XML"><![CDATA[...
+ <programlisting role="XML"><![CDATA[...
<h:inputText value="#{userBean.name}">
<a4j:support event="onkeyup" eventsQueue="foo"
reRender="bar" />
</h:inputText>
...
]]></programlisting>
- <para><emphasis>
- <property>"requestDelay"</property>
- </emphasis> attribute defines the time (in ms) that the request will be
wait in the queue
- before it is ready to send. When the delay time is over, the request will be
sent to the
- server or removed if the newest "similar" request is in a
queue already
- .</para>
- <para><emphasis>
- <property>"ignoreDupResponses"</property>
- </emphasis> attribute orders to ignore the Ajax Response produced by the
request if the
- newest "similar" request is in a queue already.
-
"ignoreDupResponses"=<property>"true"</property>
- does not cancel the request while it is processed on the server, but just
allows to avoid
- unnecessary updates on the client side if the response loses the
actuality.</para>
- <para>Defining the <emphasis>
- <property>"eventsQueue"</property>
- </emphasis> along with <emphasis>
- <property>"requestDelay"</property>
- </emphasis> allows to protect against unnecessary traffic flood and
synchronizes Ajax
- requests order. If you have several sources of Ajax requests, you can define
the same
- queue name there. This might be very helpful if you have Ajax components that
invoke
- request asynchronously from the ones produced by events from users. For
example, <emphasis
- role="bold">
- <property><a4j:poll></property>
- </emphasis> or <emphasis role="bold">
- <property><a4j:push></property>
- </emphasis>. In case the requests from such components modify the same
data, the
- synchronization might be very helpful.</para>
+ <para><emphasis>
+ <property>"requestDelay"</property>
+ </emphasis> attribute defines the time (in ms) that the request will be
wait in the queue
+ before it is ready to send. When the delay time is over, the request will be sent
to the
+ server or removed if the newest "similar" request is in a queue
already .</para>
+ <para><emphasis>
+ <property>"ignoreDupResponses"</property>
+ </emphasis> attribute orders to ignore the Ajax Response produced by the
request if the
+ newest "similar" request is in a queue already.
+
"ignoreDupResponses"=<property>"true"</property>
does
+ not cancel the request while it is processed on the server, but just allows to
avoid
+ unnecessary updates on the client side if the response loses the
actuality.</para>
+ <para>Defining the <emphasis>
+ <property>"eventsQueue"</property>
+ </emphasis> along with <emphasis>
+ <property>"requestDelay"</property>
+ </emphasis> allows to protect against unnecessary traffic flood and
synchronizes Ajax
+ requests order. If you have several sources of Ajax requests, you can define the
same queue
+ name there. This might be very helpful if you have Ajax components that invoke
request
+ asynchronously from the ones produced by events from users. For example,
<emphasis
+ role="bold">
+ <property><a4j:poll></property>
+ </emphasis> or <emphasis role="bold">
+ <property><a4j:push></property>
+ </emphasis>. In case the requests from such components modify the same
data, the
+ synchronization might be very helpful.</para>
- <para>More information can be found on the <ulink
-
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
- >RichFaces Users Forum</ulink>.</para>
- </section>
+ <para>More information can be found on the <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >RichFaces Users Forum</ulink>.</para>
+ </section>
- <section id="DataProcessingOptions">
- <?dbhtml filename="DataProcessingOptions.html"?>
- <title>Data Processing Options</title>
- <para>RichFaces uses form based approach for Ajax request sending. This
means each time,
- when a user click an Ajax button or <emphasis role="bold">
- <property><a4j:poll></property>
- </emphasis> produces an asynchronous request, the data from the closest
JSF form is
- submitted with the XMLHTTPRequest object. The form data contains the values
from the form
- input element and auxiliary information such as state saving
data.</para>
- <para>When <emphasis>
- <property>"ajaxSingle"</property>
- </emphasis> attribute value is
<property>"true"</property>, it orders to
- include only a value of the current component (along with <emphasis
role="bold">
- <property><f:param></property>
- </emphasis> or <emphasis role="bold">
- <property><a4j:action></property>
- </emphasis> param values if any) to the request map. In case of
<emphasis role="bold">
- <property>a4j:support</property>
- </emphasis>, it will be a value of the parent component.</para>
- <para>Note, that
-
"ajaxSingle"=<property>"true"</property>
reduces the
- upcoming traffic, but does not prevent decoding other input components on the
server side.
- Some JSF components, such as <emphasis role="bold">
- <property><h:selectOneMenu></property>
- </emphasis> do recognize the missing data in the request map value as a
null value and try
- to pass the validation process with a failed result. Thus, use <emphasis
role="bold">
- <property><a4j:region></property>
- </emphasis> to limit a part of the component tree that will be processed
on the server
- side when it is required.</para>
- <para><emphasis>
- <property>"immediate"</property>
- </emphasis> attribute has the same purpose as any other non-JSF
component. The default <emphasis>
- <property>"ActionListener"</property>
- </emphasis> should be executed immediately (i.e. during the Apply Request
Values phase of
- a request processing lifecycle), rather than waiting until the Invoke
Application phase.
- Using immediate=<property>"true"</property> is
one of the ways to have
- some data model values updated when other cannot be updated because of a
problem with
- passing the Validation phase successfully. This might be important inside the
<emphasis
- role="bold">
- <property><h:dataTable></property>
- </emphasis> like components where using <emphasis
role="bold">
- <property><a4j:region></property>
- </emphasis> is impossible due to the <emphasis
role="bold">
- <property><h:dataTable></property>
- </emphasis> component architecture.</para>
+ <section id="DataProcessingOptions">
+ <?dbhtml filename="DataProcessingOptions.html"?>
+ <title>Data Processing Options</title>
+ <para>RichFaces uses form based approach for Ajax request sending. This means
each time, when
+ a user click an Ajax button or <emphasis role="bold">
+ <property><a4j:poll></property>
+ </emphasis> produces an asynchronous request, the data from the closest JSF
form is
+ submitted with the XMLHTTPRequest object. The form data contains the values from
the form
+ input element and auxiliary information such as state saving data.</para>
+ <para>When <emphasis>
+ <property>"ajaxSingle"</property>
+ </emphasis> attribute value is
<property>"true"</property>, it orders to
+ include only a value of the current component (along with <emphasis
role="bold">
+ <property><f:param></property>
+ </emphasis> or <emphasis role="bold">
+ <property><a4j:action></property>
+ </emphasis> param values if any) to the request map. In case of
<emphasis role="bold">
+ <property>a4j:support</property>
+ </emphasis>, it will be a value of the parent component.</para>
+ <para>Note, that
"ajaxSingle"=<property>"true"</property>
+ reduces the upcoming traffic, but does not prevent decoding other input
components on the
+ server side. Some JSF components, such as <emphasis role="bold">
+ <property><h:selectOneMenu></property>
+ </emphasis> do recognize the missing data in the request map value as a
null value and try
+ to pass the validation process with a failed result. Thus, use <emphasis
role="bold">
+ <property><a4j:region></property>
+ </emphasis> to limit a part of the component tree that will be processed on
the server side
+ when it is required.</para>
+ <para><emphasis>
+ <property>"immediate"</property>
+ </emphasis> attribute has the same purpose as any other non-JSF component.
The default <emphasis>
+ <property>"ActionListener"</property>
+ </emphasis> should be executed immediately (i.e. during the Apply Request
Values phase of a
+ request processing lifecycle), rather than waiting until the Invoke Application
phase. Using
+ immediate=<property>"true"</property> is one of
the ways to have some
+ data model values updated when other cannot be updated because of a problem with
passing the
+ Validation phase successfully. This might be important inside the <emphasis
role="bold">
+ <property><h:dataTable></property>
+ </emphasis> like components where using <emphasis
role="bold">
+ <property><a4j:region></property>
+ </emphasis> is impossible due to the <emphasis
role="bold">
+ <property><h:dataTable></property>
+ </emphasis> component architecture.</para>
- <para><emphasis>
- <property>"bypassUpdates"</property>
- </emphasis> attribute allows to bypass the Update Model phase. It might
be useful if you
- need to check user input against the available validator, but not to update the
model with
- those data. Note, that an action will be invoked at the end of the Validation
phase only
- if the Validation phase is passed successfully. The listeners of the
Application phase
- will not be invoked in any case.</para>
- </section>
+ <para><emphasis>
+ <property>"bypassUpdates"</property>
+ </emphasis> attribute allows to bypass the Update Model phase. It might be
useful if you
+ need to check user input against the available validator, but not to update the
model with
+ those data. Note, that an action will be invoked at the end of the Validation
phase only if
+ the Validation phase is passed successfully. The listeners of the Application
phase will not
+ be invoked in any case.</para>
+ </section>
- <section id="ActionandNavigation">
- <?dbhtml filename="ActionandNavigation.html"?>
- <title>Action and Navigation</title>
- <para>Ajax component is similar to any other non-Ajax JSF component like
<emphasis
+ <section id="ActionandNavigation">
+ <?dbhtml filename="ActionandNavigation.html"?>
+ <title>Action and Navigation</title>
+ <para>Ajax component is similar to any other non-Ajax JSF component like
<emphasis role="bold">
+ <property><h:commandButton></property>
+ </emphasis>. It allows to submit the form. You can use <emphasis>
+ <property>"action"</property>
+ </emphasis> and <emphasis>
+ <property>"actionListener"</property>
+ </emphasis> attribute to invoke the action method and define the action
event.</para>
+ <para><emphasis>
+ <property>"action"</property>
+ </emphasis> method must return null if you want to have an Ajax Response
with a partual page
+ update. This is regular mode called "Ajax request generates Ajax
Response". In case of
+ action does not return null, but the action outcome that matches one of
navigation rules,
+ RichFaces starts to work in "Ajax request generates Non-Ajax Response"
mode. This mode might
+ be helpful in two major cases:</para>
+ <itemizedlist>
+ <listitem>RichFaces allows to organize a page flow inside the <emphasis
role="bold">
+ <property><a4j:include></property>
+ </emphasis> component. This is a typical scenario for Wizard like
behavior. The new
+ content is rendered inside the <emphasis role="bold">
+ <property><a4j:include></property>
+ </emphasis> area. The content is taken from the navigation rule of the
faces configuration
+ file (usually, the faces-config.xml). Note, that the content of the
"wizard" is not
+ isolated from the rest of the page. The included page should not have own
<emphasis
role="bold">
+ <property><f:view></property>
+ </emphasis> (it does not matter if you use facelets). You need to have an
Ajax component
+ inside the <emphasis role="bold">
+ <property><a4j:include></property>
+ </emphasis> to navigate between the wizard pages. Otherwize, the whole
page update will be
+ performed.</listitem>
+ <listitem>If you want to involve the server side validators and navigate to
the next page
+ only if the Validation phase is passed successfully, you can replace
<emphasis role="bold">
<property><h:commandButton></property>
- </emphasis>. It allows to submit the form. You can use <emphasis>
- <property>"action"</property>
- </emphasis> and <emphasis>
- <property>"actionListener"</property>
- </emphasis> attribute to invoke the action method and define the action
event.</para>
- <para><emphasis>
- <property>"action"</property>
- </emphasis> method must return null if you want to have an Ajax Response
with a partual
- page update. This is regular mode called "Ajax request generates Ajax
Response". In case
- of action does not return null, but the action outcome that matches one of
navigation
- rules, RichFaces starts to work in "Ajax request generates Non-Ajax
Response" mode. This
- mode might be helpful in two major cases:</para>
- <itemizedlist>
- <listitem>RichFaces allows to organize a page flow inside the
<emphasis role="bold">
- <property><a4j:include></property>
- </emphasis> component. This is a typical scenario for Wizard like
behavior. The new
- content is rendered inside the <emphasis role="bold">
- <property><a4j:include></property>
- </emphasis> area. The content is taken from the navigation rule of the
faces
- configuration file (usually, the faces-config.xml). Note, that the content of
the
- "wizard" is not isolated from the rest of the page. The included
page should not have
- own <emphasis role="bold">
- <property><f:view></property>
- </emphasis> (it does not matter if you use facelets). You need to have
an Ajax component
- inside the <emphasis role="bold">
- <property><a4j:include></property>
- </emphasis> to navigate between the wizard pages. Otherwize, the whole
page update will
- be performed.</listitem>
- <listitem>If you want to involve the server side validators and navigate
to the next page
- only if the Validation phase is passed successfully, you can replace
<emphasis
- role="bold">
- <property><h:commandButton></property>
- </emphasis> with <emphasis role="bold">
- <property><a4j:commandButton></property>
- </emphasis> and point to the action method that navigates to the next
page. If
- Validation process fails, the partial page update will occur and a user will
see an
- error message. Otherwize, the application proceeds to the next page. Make
sure, you
- define <redirect/> option for the navigation rule to avoid
memory
- leaks.</listitem>
- </itemizedlist>
- </section>
+ </emphasis> with <emphasis role="bold">
+ <property><a4j:commandButton></property>
+ </emphasis> and point to the action method that navigates to the next
page. If Validation
+ process fails, the partial page update will occur and a user will see an error
message.
+ Otherwize, the application proceeds to the next page. Make sure, you define
+ <redirect/> option for the navigation rule to avoid memory
leaks.</listitem>
+ </itemizedlist>
+ </section>
- <section id="JavascriptInteractions">
- <?dbhtml filename="JavascriptInteractions.html"?>
- <title>JavaScript Interactions</title>
- <para>RichFaces allows writing Ajax-enabled JSF application without writing
any Javascript
- code. However, you can still invoke the javascript code if you need. There are
several
- ajax attributes that helps to do it.</para>
- <para><emphasis>
- <property>"onsubmit"</property>
- </emphasis> attribute allows to invoke JavaScript code before an Ajax
request is sent. If <emphasis>
- <property>"onsubmit"</property>
- </emphasis> returns
<property>"false"</property>, the Ajax request is
- canceled. The code of <emphasis>
- <property>"onsubmit"</property>
- </emphasis> is inserted before the RichFaces Ajax call. Hence, the
<emphasis>
- <property>"onsubmit"</property>
- </emphasis> should not has a "return" statement if you
want the Ajax
- request to be sent. If you are going to invoke a JavaScript function that
returns
- <property>"true"</property> or
- <property>"false"</property>, use the conditional
statement to return
- something only when you need to cancel the request. For example: </para>
- <programlisting role="XML"><![CDATA[...
+ <section id="JavascriptInteractions">
+ <?dbhtml filename="JavascriptInteractions.html"?>
+ <title>JavaScript Interactions</title>
+ <para>RichFaces allows writing Ajax-enabled JSF application without writing
any Javascript
+ code. However, you can still invoke the javascript code if you need. There are
several ajax
+ attributes that helps to do it.</para>
+ <para><emphasis>
+ <property>"onsubmit"</property>
+ </emphasis> attribute allows to invoke JavaScript code before an Ajax
request is sent. If <emphasis>
+ <property>"onsubmit"</property>
+ </emphasis> returns
<property>"false"</property>, the Ajax request is
+ canceled. The code of <emphasis>
+ <property>"onsubmit"</property>
+ </emphasis> is inserted before the RichFaces Ajax call. Hence, the
<emphasis>
+ <property>"onsubmit"</property>
+ </emphasis> should not has a "return" statement if you
want the Ajax
+ request to be sent. If you are going to invoke a JavaScript function that
returns
+ <property>"true"</property> or
+ <property>"false"</property>, use the conditional
statement to return
+ something only when you need to cancel the request. For example: </para>
+ <programlisting role="XML"><![CDATA[...
onsubmit="if (mynosendfunct()==false){return false}"
...
]]></programlisting>
- <para><emphasis>
- <property>"onclick"</property>
- </emphasis> attribute is similar to the <emphasis>
- <property>"onsubmit"</property>
- </emphasis>, but for clickable components such as <emphasis
role="bold">
- <property><a4j:commandLink></property>
- </emphasis> and <emphasis role="bold">
- <property><a4j:commandButton></property>
- </emphasis>. If it returns
<property>"false"</property>, the Ajax
- request is canceled also.</para>
- <para><emphasis>
- <property>"oncomplete"</property>
- </emphasis> attribute allows to invoke the JavaScript code right after
the Ajax Response
- is returned back and the DOM tree of the browser is updated. Richfaces
registers the code
- for further invocation of XMLHTTP request object before an Ajax request is
sent. This
- means the code will not be changed during processing of the request on the
server if you
- use JSF EL value binding. Also, you cannot use "this'"
inside the code,
- because it will not point the component where Ajax request was
initiated.</para>
+ <para><emphasis>
+ <property>"onclick"</property>
+ </emphasis> attribute is similar to the <emphasis>
+ <property>"onsubmit"</property>
+ </emphasis>, but for clickable components such as <emphasis
role="bold">
+ <property><a4j:commandLink></property>
+ </emphasis> and <emphasis role="bold">
+ <property><a4j:commandButton></property>
+ </emphasis>. If it returns
<property>"false"</property>, the Ajax request
+ is canceled also.</para>
+ <para><emphasis>
+ <property>"oncomplete"</property>
+ </emphasis> attribute allows to invoke the JavaScript code right after the
Ajax Response is
+ returned back and the DOM tree of the browser is updated. Richfaces registers the
code for
+ further invocation of XMLHTTP request object before an Ajax request is sent. This
means the
+ code will not be changed during processing of the request on the server if you
use JSF EL
+ value binding. Also, you cannot use "this'" inside the
code, because it
+ will not point the component where Ajax request was initiated.</para>
- <para><emphasis>
- <property>"data"</property>
- </emphasis> attribute allows to get the additional data from the server
during an Ajax
- call. You can use JSF EL to point the property of the managed bean and its
value will be
- serialized in JSON format and be available on the client side. You can refer to
it using
- the <emphasis>
- <property>"data"</property>
- </emphasis> variable. For example:</para>
- <programlisting role="XML"><![CDATA[...
+ <para><emphasis>
+ <property>"data"</property>
+ </emphasis> attribute allows to get the additional data from the server
during an Ajax call.
+ You can use JSF EL to point the property of the managed bean and its value will
be
+ serialized in JSON format and be available on the client side. You can refer to
it using the <emphasis>
+ <property>"data"</property>
+ </emphasis> variable. For example:</para>
+ <programlisting role="XML"><![CDATA[...
<a4j:commandButton value="Update" data="#{userBean.name}"
oncomplete="showTheName(data.name)" />
...
]]></programlisting>
- <para>Richfaces allows to serialize not only primitive types into JSON
format, but also
- complex types including arrays and collections. The beans should be
serializable to be
- refered with <emphasis>
- <property>"data"</property>
- </emphasis>.</para>
- </section>
-
+ <para>Richfaces allows to serialize not only primitive types into JSON
format, but also
+ complex types including arrays and collections. The beans should be serializable
to be
+ refered with <emphasis>
+ <property>"data"</property>
+ </emphasis>.</para>
</section>
-
+
+ </section>
+
<section id="HowTo...">
<?dbhtml filename="HowTo.html"?>
<title>How To...</title>
@@ -580,8 +573,8 @@
</itemizedlist-->
</section>
-
+
<section id="DecideWhatToSend">
<?dbhtml filename="DecideWhatToSend.html"?>
<title>Decide What to Send</title>
@@ -1272,34 +1265,37 @@
<?dbhtml filename="CreatingAndUsingYourOwnSkinFile.html"?>
<title>Creating and Using Your Own Skin File</title>
- <para>In order to create your own skin whose constants are used by style
classes at the first
- level, do the following:</para>
+ <para>In order to create your own skin file, do the following:</para>
<itemizedlist>
<listitem>
- <para>Create a file whose name follows the format of a skin file and
place it into the
- ClassPath for the application. (Any skin file follows the naming format,
<emphasis>
- <property><name.skin.properties></property>
- </emphasis>.)</para>
+ <para>Create a file and define in it skin constants which are used by
style classes (see
+ section <link
linkend="SkinParametersTablesInRichFaces">"Skin Parameters Tables
+ in RichFaces"</link>). The name of skin file should
correspond to the
+ following format: <property>name.skin.properties</property>. As
an example of such file
+ you can see RichFaces predefined skin parameters (skins): blueSky, classic,
deepMarine,
+ etc. These files are located in the richfaces-impl-xxxxx.jar inside the
/META-INF/skins
+ folder.</para>
</listitem>
<listitem>
- <para>Add a skin definition context-param element to the
application's web.xml
- file:</para>
-
-
+ <para>Add a skin definition <contex-param> to the web.xml
of your
+ application. An example is placed below:</para>
<para>
<emphasis role="bold">Example:</emphasis>
</para>
- <programlisting role="XML"><context-param>
- <param-name>org.richfaces.SKIN</param-name>
- <param-value>name</param-value>
-</context-param></programlisting>
+ <programlisting role="XML"><![CDATA[...
+ <context-param>
+ <param-name>org.richfaces.SKIN</param-name>
+ <param-value>name</param-value>
+ </context-param>
+...
+]]></programlisting>
</listitem>
<listitem>
- <para>In the skins file, specify your own values for skin constants as
described in the
- table.</para>
+ <para>Put your <property>name.skin.properties</property> file
in one of the following classpath elements:
+ META-INF/skins/ or default package (e.g. WEB-INF/classes).</para>
</listitem>
</itemizedlist>
</section>