Author: smukhina
Date: 2007-08-02 09:29:43 -0400 (Thu, 02 Aug 2007)
New Revision: 2006
Added:
trunk/docs/userguide/en/src/main/resources/images/newpic1.jpg
trunk/docs/userguide/en/src/main/resources/images/newpic2.jpg
trunk/docs/userguide/en/src/main/resources/images/newpic3.jpg
trunk/docs/userguide/en/src/main/resources/images/newpic4.jpg
Modified:
trunk/docs/userguide/en/src/main/docbook/modules/AUGWADParams.xml
trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml
trunk/docs/userguide/en/src/main/docbook/modules/RFCfaq.xml
trunk/docs/userguide/en/src/main/docbook/modules/RFClinks.xml
trunk/docs/userguide/en/src/main/docbook/modules/RFCtechreqs.xml
Log:
http://jira.jboss.com/jira/browse/RF-522
Guides chapters merging
Modified: trunk/docs/userguide/en/src/main/docbook/modules/AUGWADParams.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/modules/AUGWADParams.xml 2007-08-02 13:16:21
UTC (rev 2005)
+++ trunk/docs/userguide/en/src/main/docbook/modules/AUGWADParams.xml 2007-08-02 13:29:43
UTC (rev 2006)
@@ -105,6 +105,13 @@
(skin name) or a property of a org.ajax4jsf.framework.skin type.
Skin in last case, this instance is used as a current skin</entry>
</row>
+ <row>
+ <entry>org.ajax4jsf.COMPRESS_SCRIPT</entry>
+ <entry>true</entry>
+ <entry>This parameter could be used to increase the flexibility
of Ajax4jsf usage. It doesn't allow A4J to reformat JavaScript files (makes it
impossible to debug)
+ </entry>
+ </row>
+
</tbody>
</tgroup>
</table></para>
Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2007-08-02
13:16:21 UTC (rev 2005)
+++ trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2007-08-02
13:29:43 UTC (rev 2006)
@@ -22,12 +22,324 @@
<para>RichFaces is based on the Ajax4jsf framework, so
<property>AJAX</property> request support is performed with this
- framework. This support is explained in the Architecture Overview section of the
Ajax4jsf Developers Guide found under the
- <property><ulink
-
url="http://labs.jboss.com/portal/jbossajax4jsf">Ajax4jsf<...
- project. In this section, we will focus on skinnability.</para>
+ framework.</para>
+
+<section>
+ <title>Basic concepts of the Ajax4jsf Framework</title>
+ <section id="introToBasics">
+ <?dbhtml filename="introToBasics.html"?>
+ <title>Introduction</title>
+ <para>The framework is implemented as a component library which adds AJAX
capability into existing
+ pages, so you don't need to write any JavaScript code or to replace
existing
+ components with new AJAX widgets. <property>Ajax4jsf</property> enables
page-wide AJAX support instead of the
+ traditional component-wide support. So, you can define the event on the page that
+ invokes an AJAX request and the areas of the page that should be synchronized with
the JSF
+ Component Tree after the AJAX request changes the data on the server according to
the
+ events fired on the client.</para>
+ <para>Next Figure shows how it works:</para>
+ <figure>
+ <title>Request Processing flow</title>
+ </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/newpic1.jpg"/>
+ </imageobject>
+ </mediaobject>
+ <para><property>Ajax4jsf</property> allows to define (by means of
JSF tags) different parts of a JSF page you
+ wish to update with an AJAX request and provide a few options to send AJAX
requests to
+ the server. Also JSF page doesn't change from a
"regular" JSF
+ page and you don't need to write any JavaScript or XMLHttpRequest
objects by hands, everything is done automatically.</para>
</section>
+ <section id="ArchitectureOverview1">
+ <?dbhtml filename="ArchitectureOverview.html"?>
+ <title>Architecture Overview</title>
+ <para>Next figure lists several important elements of the
<property>Ajax4jsf</property> framework</para>
+ <figure>
+ <title>Ajax4jsf component structure</title>
+ </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/newpic2.jpg"/>
+ </imageobject>
+ </mediaobject>
+ <formalpara>
+ <title>Ajax Filter.</title>
+ <para>To get all benefits of <property>Ajax4jsf</property>, you
should register an AJAX Filter in web.xml
+ file of your application.The AJAX Filter recognizes multiple request types. The
sequence diagram on Figure 3
+ shows the difference in processing of a "regular" JSF request and
an AJAX request.</para>
+ </formalpara>
+ <para>In the first case the whole JSF tree will be encoded,
+ in the second one option it depends on the "size" of the AJAX
region (you can define AJAX region
+ by using the <emphasis
role="bold"><property><a4j:region></property></emphasis>).
As you can see, in the second case the filter parses
+ the content of an AJAX response before sending it to the client side.</para>
+ <para>Have a look at the next picture to understand these two
ways:</para>
+ <figure>
+ <title>Request Processing sequence diagram</title>
+ </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/newpic3.jpg"/>
+ </imageobject>
+ </mediaobject>
+ <para>In both cases, the information about required static or dynamic resources
that your application
+ requests is registered in the ResourseBuilder class.</para>
+ <para>When a request for a resource comes (Figure 4), the AJAX filter checks
the Resource Cache
+ for this resource and if it is there, the resource is sent to the client.
Otherwise,
+ the filter searches for the resource among those that are registered by the
+ ResourceBuilder. If the resource is registered, the AJAX filter will send a request
to the
+ ResourceBuilder to create (deliver) the resource.</para>
+ <para>Next Figure shows the ways of resource request processing.</para>
+ <figure>
+ <title>Resource request sequence diagram</title>
+ </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/newpic4.jpg"/>
+ </imageobject>
+ </mediaobject>
+ <formalpara>
+ <title>AJAX Action Components</title>
+ <para>
+ There are four AJAX Action Components: AjaxCommandButton, AjaxCommandLink,
AjaxPoll and AjaxSupport.
+ You can use them to send AJAX requests from the client side.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>AJAX Containers</title>
+ <para>
+ AjaxContainer is an interface that describes an area on your JSF page that should
be decoded
+ during an AJAX request. AjaxViewRoot and AjaxRegion are implementations of this
interface.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>JavaScript Engine</title>
+ <para><property> Ajax4jsf</property> JavaScript Engine runs on
the client-side. It knows how to update different areas
+ on your JSF page based on the information from the Ajax response. Do
+ not use this JavaScript code directly, as it is available automatically.
+ </para>
+ </formalpara>
+ </section>
+ <section id="LimitationsAndRules">
+ <?dbhtml filename="LimitationAndRules.html"?>
+ <title>Limitations and Rules</title>
+ <para>In order to create AJAX4JSF applications properly, keep the following
points in mind:</para>
+ <itemizedlist>
+ <listitem>
+ The AJAX framework should not append or delete, but only replace elements on the
page. For successful updates, an element with the same ID as in the response must exist on
the page. If you'd like to append any code to a page, put in a placeholder for it
(any empty element). For the same reason, it's recommended to place messages in
the<emphasis >
+ <property>"AjaxOutput"</property>
+ </emphasis> component (as no messages is also a message).
+ </listitem>
+ <listitem>
+ Don't use <emphasis role="bold">
+ <property><f:verbatim></property>
+ </emphasis> for self-rendered containers, since this component is
transient and not saved in the tree.
+ </listitem>
+ <listitem>
+ AJAX requests are made by XMLHttpRequest functions in XML format, but this XML
bypasses most validations and the corrections that might be made in a browser. So, create
only a strict standards-compliant code for HTML and XHTML, without skipping any required
elements or attributes. Any necessary XML corrections are automatically made by the XML
filter on the server, but lot's of unexpected effects can be produced by an
incorrect HTML code.
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="HowTo...">
+ <?dbhtml filename="HowTo.html"?>
+ <title>How To...</title>
+ <section id="SendAnAJAXRequest">
+ <?dbhtml filename="SendAnAJAXRequest.html"?>
+ <title>Send an AJAX request</title>
+ <para>There are different ways to send AJAX requests from your JSF page. You
may use
+ <emphasis
role="bold"><property><a4j:commandButton></property></emphasis>,
<emphasis role="bold">
+ <property><a4j:commandLink></property>, <emphasis
role="bold"><property><a4j:poll></property></emphasis>
+ </emphasis> or <emphasis role="bold">
+ <property><a4j:support></property>
+ </emphasis> tags.
+ </para>
+ <para>All these tags hide the usual JavaScript activities that are required
for an XMHttpRequest
+ object building and an AJAX request sending. Also, they allow you to decide
which components of
+ your JSF page are to be re-rendered as a result of the AJAX response (you can
list the
+ IDs of these components in the "reRender" attribute).
+ </para>
+ <para>
+ <emphasis role="bold">
+ <property><a4j:commandButton></property>
+ </emphasis> and <emphasis role="bold">
+ <property><a4j:commandLink></property>
+ </emphasis> tags are used to send an AJAX
+ request on "onclick" JavaScript event.
+ </para>
+ <para>
+ <emphasis role="bold">
+ <property><a4j:poll></property>
+ </emphasis> tag is used to send an AJAX
+ request periodically using a timer.
+ </para>
+ <para>The <emphasis role="bold">
+ <property><a4j:support></property>
+ </emphasis> tag allows you to add AJAX functionality to standard JSF
components
+ and send AJAX request onto a chosen JavaScript event:
"onkeyup", "onmouseover",
+ etc.
+ </para>
+ <para>Most important attributes of components that provide AJAX request
calling features are:</para>
+ <itemizedlist>
+ <listitem>
+ <emphasis >
+ <property>"reRender"</property>
+ </emphasis>attribute as it was mentioned <link
linkend="SendAnAJAXRequest">before</link> specifies components to be
reRendered
+ after AJAX response. The attribute can be specified using EL expression and
formed dynamicaly on the
+ server side (see <ulink url="index.html#FAQ">FAQ
chapter</ulink>).
+ </listitem>
+ <listitem>
+ <emphasis >
+ <property>"RequestDelay"</property>
+ </emphasis> attribute is used for a requests frequency regulation.
+ </listitem>
+ </itemizedlist>
+ <programlisting role="XML"><![CDATA[<h:inputText
size="50" value="#{bean.text}">
+ <a4j:support event="onkeyup" RequestDelay="3"/>
+</h:inputText>]]></programlisting>
+ <para>So every next request from the frequent keyboard events will be
delayed
+ on 3 ms to reduce the number of requests.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <emphasis >
+ <property>"EventsQueue"</property>
+ </emphasis> is a queue that stores the next request.
+ </listitem>
+ <listitem>
+ <emphasis >
+ <property>"LimitToList"</property>
+ </emphasis> attribute is used to regulate updatable regions. Setting
+ it to true limits the updatable areas only to ones specified in a
+ reRender list, in other case all Output Panels of the region are updated.
+ </listitem>
+ <listitem> <emphasis >
+ <property>"ajaxSingle"</property>
+ </emphasis> attributes specify regions to be sent with a request,
+ if "false" it is a full region, in other case
it's is only a control caused
+ event.
+</listitem>
+ </itemizedlist>
+ </section>
+ <section id="DecideWhatToSend">
+ <?dbhtml filename="DecideWhatToSend.html"?>
+ <title>Decide What to Send</title>
+ <para>You may describe a region on the page you wish to send to the server,
in this way you can
+ control what part of the JSF View is decoded on the server side when you send
an
+ AJAX request.
+ </para>
+ <para>The easiest way to describe an AJAX region on your JSF page is to do
nothing,
+ because the content between the <emphasis role="bold">
+ <property><f:view></property>
+ </emphasis> and <emphasis role="bold">
+ <property></f:view></property>
+ </emphasis> tags is considered
+ the default AJAX region.
+ </para>
+ <para>You may define multiple AJAX regions on the JSF page (they can even be
nested) by using
+ the <emphasis role="bold">
+ <property><a4j:region></property>
+ </emphasis> tag.
+ </para>
+ <para>If you wish to render the content of an AJAX response outside of the
active region then
+ the value of the "renderRegionOnly" attribute should be set
to "false". Otherwise, your
+ AJAX updates are limited to elements of the active region.
+ </para>
+ </section>
+ <section id="DecideWhatToChange">
+ <?dbhtml filename="DecideWhatToChange.html"?>
+ <title>Decide What to Change</title>
+ <para>Using IDs in the "reRender" attribute to define
"AJAX zones" for update works fine in
+ many cases.
+ </para>
+ <para>But you can not use this approach if your page contains, e.g. a
<emphasis
role="bold"><property><f:verbatim></property></emphasis>
+ tag and you wish to update its content on an AJAX response.
+ </para>
+ <para>The problem with the <emphasis role="bold">
+ <property><f:verbatim/></property>
+ </emphasis> tag as described above is related to the
+ value of the transientFlag of JSF components. If the value of this flag is
true, the
+ component must not participate in state saving or restoring of process.
+ </para>
+ <para>In order to provide a solution to this kind of problems, Ajax4jsf uses
the concept of
+ an output panel that is defined by the <emphasis role="bold">
+ <property><a4j:outputPanel></property>
+ </emphasis> tag. If you put a <emphasis
role="bold"><property><f:verbatim></property></emphasis>
+ tag inside of the output panel, then the content of the <emphasis
role="bold">
+ <property><f:verbatim/></property>
+ </emphasis> tag and content of
+ other panel's child tags could be updated on AJAX response. There are
two ways to
+ control this:
+ <itemizedlist>
+ <listitem>
+ By setting the "ajaxRendered" attribute value to
"true".
+</listitem>
+ <listitem>
+ By setting the "reRender" attribute value of an Action
Component to the output panel ID.
+</listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+ <section id="RequestErrorsAndSessionExpirationHandling">
+ <?dbhtml filename="RequestErrorsAndSessionExpirationHandling.html"?>
+ <title>Request Errors and Session Expiration Handling</title>
+ <para>Ajax4jsf allows to redefine standard handlers responsible for processing of
different exceptional situations. It helps to define own JavaScript, which is executed
when this situations occur.</para>
+ <section id="RequestErrorsHandling">
+ <?dbhtml filename="RequestErrorsHandling.html"?>
+ <title>Request Errors Handling</title>
+ <para>To execute your own code on the client in case of an error during AJAX
request, it's necessary to redefine the standard "A4J.AJAX.onError "
method:</para>
+ <programlisting role="JAVA"><![CDATA[A4J.AJAX.onError =
function(req,status,message) {
+ // Custom Developer Code
+};]]></programlisting>
+ <para>The function defined this way accepts as parameters:</para>
+ <itemizedlist>
+ <listitem>req - a params string of a request that calls an
error</listitem>
+ <listitem>status - the number of an error returned by the
server</listitem>
+ <listitem>message - a default message for the given error</listitem>
+ </itemizedlist>
+ <para>Thus, it's possible to create your own handler that is called on
timeouts, inner server errors, and etc.</para>
+ </section>
+ <section id="SessionExpiredHandling">
+ <?dbhtml filename="SessionExpiredHandling.html"?>
+ <title>Session Expired Handling</title>
+ <para>Beginning with Ajax4jsf version 1.0.5 it's possible to redefine
also the <emphasis >
+ <property>"onExpired"</property>
+ </emphasis> framework method that is called on the <emphasis >
+ <property>"Session Expiration"</property>
+ </emphasis> event.</para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="JAVA"><![CDATA[A4J.AJAX.onExpired =
function(loc,expiredMsg){
+ // Custom Developer Code
+};
+]]></programlisting>
+
+<para>Here the function receives in params:</para>
+ <itemizedlist>
+ <listitem>loc - URL of the current page (on demand can be updated)
</listitem>
+ <listitem>expiredMsg - a default message on <emphasis >
+ <property>"Session Expiration"</property>
+ </emphasis>event.</listitem>
+ </itemizedlist>
+<note>
+<title>Note:</title>
+Until the version 1.0.5 the method can't be redefined on <emphasis >
+ <property>"Session Expiration"</property>,
+ </emphasis> a confirmation dialog with a request for view reloading was always
called.
+</note>
+ </section>
+</section>
+<section id="OtherRelevantResources">
+ <title>Other Relevant Resources</title>
+ <para><ulink
url="http://jsf.javabeat.net/articles/2007/06/introduction-to-ajax4j...
to Ajax4Jsf</ulink> by Shunmuga Raja</para>
+
+</section>
+
+</section>
+
+ </section>
+
<section id="Skinnability">
<?dbhtml filename="Skinnability.html"?>
Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCfaq.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/modules/RFCfaq.xml 2007-08-02 13:16:21 UTC
(rev 2005)
+++ trunk/docs/userguide/en/src/main/docbook/modules/RFCfaq.xml 2007-08-02 13:29:43 UTC
(rev 2006)
@@ -318,8 +318,8 @@
<h:outputText value="RichFaces Home
Page"></h:outputText>
</h:outputLink>
</rich: treeNode>
- …
-</rich:tree …>
+ ...
+</rich:tree ...>
...
]]></programlisting>
</section>
@@ -510,4 +510,419 @@
</section>
+ <section id="DecidingWhatToChangeOnTheServerSide">
+ <?dbhtml filename="DecidingWhatToChangeOnTheServerSide.html"?>
+ <title>What should I change on the server side?</title>
+ <para> As it was mentioned <ulink
url="index.html#DecideWhatToChange">before</ulink>, the
+ list of zones to be reRendered can be specified as EL expression. But there
is a
+ question that must be specified more exactly. </para>
+ <para> The list of Ids is formed during beforePhase of RENDER_RESPONSE.
Therefore, in this
+ case one can point reRender to the Set type Bean's property and fill
the Set
+ during a tracking request. </para>
+ <para> It's the way to form a list of updatable areas dynamically.
</para>
+ </section>
+ <section
id="CheckSendingRequestConditions.CustomJavaScriptBeforeRequest.OnSubmitAttribute">
+ <?dbhtml
filename="CheckSendingRequestConditions.CustomJavaScriptBeforeRequest.OnSubmitAttribute.html"?>
+
+ <title>How to check sending request conditions? Custom JavaScript before
request
+ "OnSubmit" attribute.</title>
+ <para> To check on the client some terms of request sending, the
<emphasis >
+ <property>"onSubmit</property>
+ </emphasis>" attribute is added to all components, which may
cause the request. </para>
+ <para>
+ <emphasis role="bold">Example: </emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[<h:inputText
id="i" value="#{beanText.kennung}">
+ <a4j:support event="onfocus" onsubmit="doSomething();"
reRender="panelToReRender"/>
+</h:inputText>]]></programlisting>
+ <para> So in this case "<emphasis
+
><property>doSomething()</property>"</emphasis> function is
executed before
+ the AJAX request. </para>
+ <para> Besides, if this function returns "false", AJAX
request
+ isn't fired. </para>
+ <note>
+ <title>Note:</title>
+ <para>Behavior of our <emphasis >
+ <property>"onsubmit"</property>
+ </emphasis>slightly differs from the standard one. Do not return
<emphasis
+ >
+ <property>"true"</property>
+ </emphasis> if you want to fire the request - because <emphasis
role="bold">
+ <property><xxx><a4j:support
+ event="onclick" onsubmit="return
+ true;"></property>
+ </emphasis> is transformed into <xxx
onclick="return true;
+ A4J.Submit(.... );" > and the request isn't
fired also in
+ this case (but the standard event processing fired). You must only return
<emphasis
+ >
+ <property>"false"</property>
+ </emphasis> if your conditions weren't completed or
perform some actions
+ (if needed) without any returns in case you need to fire it.
</para>
+ </note>
+ </section>
+ <section id="onCompleteAttribute.DifferencesAfterRelease1.0">
+ <?dbhtml
filename="onCompleteAttribute.DifferencesAfterRelease1.0.html"?>
+ <title> What is differences of "onCompelete" attribute
after release 1.0?</title>
+ <para> To avoid differences with other JavaScript attributes, a function
placement in a
+ JavaScript call is changed, instead of simple inserting of attribute content
+ (..oncomplete :anotherFunction(this)..), it places (oncomplete:
+ function(){anotherFunction(this);}..) in anonymous function, to allow put
+ "chain" of statements in attribute. </para>
+ <para> Since, <emphasis >
+ <property>"this"</property>
+ </emphasis> keyword will point to a parameters map instead of a control
element as it
+ was before. You may use <emphasis >
+ <property>document.findElementById()</property>
+ </emphasis>to get references to this object after a request is
processed as when a page
+ is updated in AJAX you will have reference to a control, removed from a DOM
tree. </para>
+ <para> Or, if you are sure that your element is not updated, you can add
<emphasis
+ >
+ <property>"onsubmit"</property>
+ </emphasis> in <emphasis role="bold">
+ <property><a4j:support></property>
+ </emphasis> (or onclick in <emphasis role="bold">
+ <property><a4j:commandLink/Button></property>
+ </emphasis>) to place reference to known variable (<emphasis
role="bold">
+ <property><a4j:commandLink onclick="var
myControl=this;"
+
oncomplete="anotherFunction(myControl)"/></property>
+ </emphasis>). </para>
+ <important>
+ <title>New:</title>
+ <para> The onComplete syntax now is: </para>
+ <programlisting role="XML">
+ <![CDATA[<someAjaxActionComponent
...oncomplete="myFunc(req,event,data)".../>]]>
+ </programlisting>
+ <para> where the <property>event</property> is a variable
where the JS event copy that
+ fires the request is placed into. One may use it to get the element
instead of this.
+ and <property>data</property> is a variable that contains
deserialized value from
+ the <property>data</property> attribute. </para>
+ </important>
+ </section>
+ <section id="InvokeOnComponentUsingWithJSF1.2">
+ <?dbhtml filename="InvokeOnComponentUsingWithJSF1.2.html"?>
+ <title>Is it possible to use InvokeOnComponent with JSF 1.2?</title>
+ <para> Ajax4jsf currently does not use <emphasis
>invokeOnComponent</emphasis>
+ because of the 2 reasons: </para>
+ <itemizedlist>
+ <listitem> Compatibility with JSF 1.1 and MyFaces applications is kept,
due to a big
+ amount of code used in corporate applications. </listitem>
+ <listitem>
+ <emphasis > InvokeOnComponent</emphasis> works with already
known
+ clientId, and works fine for communication between widget and backed
component, or
+ updates content of already rendered component. But there are some
troubles to use
+ this method for more complex use-cases implemented in Ajax4jsf, as there
is a choice
+ for updatable components in application logic, where it's
necessary to
+ navigate in a components tree by the native id, with
+ <property>findComponent()</property> methods.
</listitem>
+ </itemizedlist>
+ <para> Thus, for example, only entire dataTable can be updated in response
(but all AJAX
+ action components inside table work properly). </para>
+ </section>
+ <!--<section id="RegionsInDataTables">
+ <?dbhtml filename="RegionsInDataTables.html"?>
+ <title>Regions in Data Tables</title>
+ <para>The regions in Data Tables aren't supported now, but the feature
will be implemented in a new Ajax4jsf version for JSF 1.2.</para>
+ </section>-->
+ <section id="keepAliveComponentGeneratesException">
+ <?dbhtml filename="keepAliveComponentGeneratesException.html"?>
+ <title>How to avoid generating exception for "keepAlive"
component?</title>
+ <para>To avoid exception, don't forget that the component stores
beans in
+ serialized view, but your bean should implement
java.io.Serializable.</para>
+ </section>
+ <section id="FilterUsageDamagesAnApplicationLayout">
+ <?dbhtml filename="FilterUsageDamagesAnApplicationLayout.html"?>
+ <title>Why does filter usage damage an application layout?</title>
+ <para>Ajax4jsf uses <property>filters</property> for correction
of xhtml code received on an
+ AJAX response, because when a response is recieved from the server, Ajax4jsf
makes
+ direct changes in DOM tree and browser doesn't make any corrections
in
+ generated xhtml. There are two ways for setting
<property>filters</property> that could
+ be used in an Ajax4jsf-based application.</para>
+ <para> The first one:</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[<context-param
filter>
+ <display-name>Ajax4jsf Filter</display-name>
+ <filter-name>ajax4jsf</filter-name>
+ <filter-class>org.ajax4jsf.Filter</filter-class>
+</filter>]]></programlisting>
+ <para>This <property>filter</property> is based on Tidy Filter
usage and recommended for
+ applications with complicated or non-standard markup, as all the necessary
xhtml code
+ corrections are made by the filter when a response comes from the
server.</para>
+ <para> Anyway, some obvious errors could damage a layout, if it happens,
make sure that the
+ markup corresponds to the xhtml-strict specification. </para>
+ <para>The second one:</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[<filter>
+ <display-name>org.ajax4jsf.FastFilter</display-name>
+ <filter-name>ajax4jsf</filter-name>
+ <filter-class>org.ajax4jsf.FastFilter</filter-class>
+</filter>]]></programlisting>
+ <para>This <property>filter</property> is based on the Nekko
pacer. In this case an output
+ xhtml code isn't strictly verified and it also could cause
lot's of
+ errors and corrupt a layout as a result. Though if you sure that your
application markup
+ is really strict for this filter, the filter considerably accelerates all
AJAX requests
+ processing. </para>
+ <para><emphasis role="bold">Extra
information</emphasis>. </para>
+ <para>forceParcer parameters setting for
<property>filters</property>:</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[<filter>
+...
+<init-param>
+<param-name>forceparser</param-name>
+<param-value>false</param-value>
+</init-param>
+...
+</filter>]]></programlisting>
+ <para>The "false" setting for initialization parameter
switches off
+ application of filters for non-AJAX requests, if "true" is
chosen, the
+ filter checks all requests. <important>
+ <title>Changes for Ajax4jsf 1.1.0</title>
+ <property>forceparser parameter</property> default value is
false from this version.
+ </important>
+ </para>
+ </section>
+ <section
id="AFormIsNotSubmittedOrASetterIsNotCalledAfterAJAXrequest">
+ <?dbhtml
filename="AFormIsNotSubmittedOrASetterIsNotCalledAfterAJAXrequest.html"?>
+ <title>Why form isn't submitted or setter isn't called
after AJAX request?</title>
+ <para>This situation could happen because of conversion/validation errors
on form
+ submission. In order to verify this, it's necessary to place this
updating via
+ an AJAX error message inside a form:</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[<a4j:outputPanel
ajaxRendered="true">
+ <h:messages/>
+</a4j:outpurPanel>]]></programlisting>
+ </section>
+
+ <section id="DelayedRenderZone">
+ <?dbhtml filename="DelayedRenderZone.html"?>
+ <title>How to create "a4j delayed render
zone"?</title>
+ <para>The <emphasis
role="bold"><a4j:support></emphasis> component has a
+ "requestDelay" attribute where you can define the
delay.</para>
+ <para>More information about this problem could be found on the <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum.</ulink>
+ </para>
+ </section>
+
+
+ <section id="HowToStopPoll">
+ <?dbhtml filename="HowToStopPoll.html"?>
+ <title>How to stop "a4j:poll"?</title>
+ <para>More information about this problem could be found on the <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum. </ulink>
+ </para>
+ </section>
+
+
+ <section id="IgnoreDupResponsesAndRequestDelay">
+ <?dbhtml filename="IgnoreDupResponsesAndRequestDelay.html"?>
+
+ <title>How to use IgnoreDupResponses and requestDelay?</title>
+ <para>The <emphasis >
+ <property>"IgnoreDupResponses"</property>
+ </emphasis> attribute appeared from 1.0.4 RC1 version and is used on
the client for
+ response ignoring after an AJAX request if a newer request has been already
sent. <para>
+ The additional information could be found <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >here</ulink>. </para>
+ <emphasis >
+ <property>"RequestDelay"</property>
+ </emphasis> attribute also defines the client behavior. It sets the
time delay, after
+ which another request could be sent, all other requests are taken away from a
queue
+ except the last one. </para>
+ </section>
+
+
+ <section id="RefreshImage">
+ <?dbhtml filename="RefreshImage.html"?>
+ <title>How to refresh an image using <a4j:support>
component?</title>
+ <para>More information about this problem could be found on the <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum. </ulink>
+ </para>
+ </section>
+
+
+
+ <section id="EventQueueUsage">
+ <?dbhtml filename="EventQueueUsage.html"?>
+ <title>How to use "EventQueue" attribute?</title>
+ <para>The <emphasis >
+ <property>"EventQueue"</property>
+ </emphasis> attribute defines the query name where the requests are
saved before their
+ sending to the server. The queue is created for redundant requests deleting
during
+ frequent events, which call several requests forming one after another. The
queue cuts
+ redundant requests and send only the last one. The queue is created in any
case and
+ named on default, the attribute usage only re-defines this name.
</para>
+ </section>
+
+ <section id="PageRequiredOrNot">
+ <?dbhtml filename="PageRequiredOrNot.html"?>
+ <title>Is <a4j:page> component required or
not?</title>
+ <para>
+ <emphasis
role="bold"><4j:page></emphasis> is a component used for
solving
+ of incompatibility problems in early Ajax4jsf and MyFaces versions. The
component
+ encodes the full html page structure. </para>
+ <para>More information about this problem could be found on the <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum. </ulink>
+ </para>
+ </section>
+
+ <section id="SeveralStatusOnPage">
+ <?dbhtml filename="SeveralStatusOnPage.html"?>
+ <title>Can I have several <a4j:status> components on one
page?</title>
+ <para>Yes, you can. More information about this problem could be found on
the <ulink
+
url="http://livedemo.exadel.com/a4j-status/">JBoss Ajax4jsf
Online Demos</ulink>.
+ </para>
+ </section>
+
+ <section id="SomeProblemsWithRendering">
+ <?dbhtml filename="SomeProblemsWithRendering.html"?>
+ <title>Can I use <a4j:region> within
<a4j:repeat>?</title>
+ <para>
+ <emphasis
role="bold"><a4j:region></emphasis> can't work
inside
+ iteration components like <emphasis
role="bold"><h:dataTable></emphasis>
+ and <emphasis
role="bold"><a4j:repeat></emphasis>. </para>
+ <para>The details could be found <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >here. </ulink>
+ </para>
+ </section>
+
+ <section id="RerenderingPartPage">
+ <?dbhtml filename="RerenderingPartPage.html"?>
+ <title>How to reRender only particular row(s) of dataTable?</title>
+ <para> If you use dataTable then you may use ajaxKeys attribute to bind the
rowKeys to be
+ reRendered there. After you need to point reRender on the whole table and
only specified
+ rows will be reRedered. Also the example of usage of <emphasis
role="bold"
+ ><a4j:repeat></emphasis> component are available
<ulink
+
url="http://livedemo.exadel.com/a4j-repeat/">here</ulink&...
+ </section>
+
+
+ <section id="CustomAjaxRequest">
+ <?dbhtml filename="CustomAjaxRequest.html"?>
+ <title>Why custom AJAX request does not work?</title>
+ <para>More information about this problem could be found on the <ulink
+
url="http://www.jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum.</ulink>
+ </para>
+ </section>
+
+
+ <section id="RerederingSingleDataTableColumn">
+ <?dbhtml filename="RerederingSingleDataTableColumn.html"?>
+ <title>How to reRender single dataTable column?</title>
+ <para>More information about this problem could be found on the <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum. </ulink>
+ </para>
+ </section>
+
+ <section id="DisableSkins">
+ <?dbhtml filename="DisableSkins.html"?>
+ <title>How to disable skinability?</title>
+ There is possibility to use special skin with name "plain". It doesn't
have any parameters.
+ It's necessary for embedding RichFaces components into existing projecst which have
its own styles.
+ <para>For information you can see discussion about this problem on the
<ulink
+
url="http://www.jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum. </ulink>
+ </para>
+ </section>
+
+ <section id="reRenderingfailed">
+ <?dbhtml filename="reRenderingfailed.html"?>
+ <title>Why does reRendering fail? Hide/Show components using
rendered.</title>
+ <para> During "show/hide" functionality implementation
the main error
+ happens because of the "reRender" attribute of some AJAX
Action
+ Component is set on a component that depends on rendered properties, i.e. a
component
+ that is to be hidden/rendered is tried to be updated. The problem is that if
+ rendered="false" in this moment, the component
isn't in the
+ DOM tree and can't be updated because of the general limitations
described in
+ the Ajax Processing chapter. </para>
+ <para>The correct variant of functionality implantation:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>With the rendered attribute wrap the component that is to be
hidden or
+ rendered on AJAX in a wrapper component (e.g.
a4j:outputPanel)</para>
+ </listitem>
+
+ <listitem>
+ <para>Set reRender of an AJAX Action component on this wrapper
component instead of
+ the component itself.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+
+ <programlisting role="XML"><![CDATA[...
+<a4j:outputPanel id="panel">
+ <h:panelGroup rendered="#{bean.rendered}">
+ <!--Some nested content to be hidden/shown depending on bean.rendered -->
+ </h:panelGroup>
+</a4j:outputPanel>
+...
+<a4j:commandButton action=".." value=".."
reRender="panel"/>
+...
+]]></programlisting>
+
+ <para>In this case the wrapper component always presents in the DOM tree
and its inner
+ content could be updated dynamically on AJAX.</para>
+ </section>
+
+ <section id="PreventDupRerenderingPoll">
+ <?dbhtml filename="PreventDupRerenderingPoll.html"?>
+ <title>How to prevent duplicate reRendering when using
<a4j:poll>?</title>
+ <para>For information you can see discussion about this problem on the
<ulink
+
url="http://www.jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum. </ulink>
+ </para>
+ </section>
+
+ <section id="JSCallPropblemsInInclude">
+ <?dbhtml filename="JSCallPropblemsInInclude.html"?>
+ <title>Why does JavaScript call don't work in
<a4j:include>?</title>
+ <para>More information about this problem could be found on the <ulink
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum. </ulink>
+ </para>
+ </section>
+
+ <section id="IncludeAndNavRules">
+ <?dbhtml filename="IncludeAndNavRules.html"?>
+ <title>How to use <a4j:include> and navigation
rules?</title>
+ <para>For information you can see discussion about this problem on the
<ulink
+
url="http://www.jboss.com/index.html?module=bb&op=viewtopic&...
+ >Ajax4Jsf Users Forum. </ulink>
+ </para>
+ </section>
+
+ <section id="ResourceNotRegisteredException">
+ <?dbhtml filename="ResourceNotRegisteredException.html"?>
+ <title>What does ResourceNotRegistered Exception mean?</title>
+
+ <para>Ajax4jsf registers its resources (scripts, images) after an
application is accessed
+ and then accesses it via a generated URL. During an application development
when a
+ developer constantly updates it on the server, it could happen that Ajax4jsf
+ re-registers its resources after every server restart and a browser tries to
access them
+ via cashed URL.</para>
+
+ <para>The problem is solved with browser cash update (e.g.
CTRL+F5).</para>
+ </section>
</chapter>
Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFClinks.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/modules/RFClinks.xml 2007-08-02 13:16:21 UTC
(rev 2005)
+++ trunk/docs/userguide/en/src/main/docbook/modules/RFClinks.xml 2007-08-02 13:29:43 UTC
(rev 2006)
@@ -36,6 +36,13 @@
<para><ulink
url="http://labs.jboss.com/wiki/RichFaces">Rich Faces
Wiki</ulink></para>
</entry>
</row>
+ <row>
+ <entry>Ajax4Jsf Wiki</entry>
+ <entry>
+ <para><ulink
url="http://labs.jboss.com/wiki/Ajax4jsf">Ajax4Jsf
Wiki</ulink></para>
+ </entry>
+ </row>
+
<row>
<entry>Ajax4jsf/Rich Faces Blog</entry>
<entry>
Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCtechreqs.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/modules/RFCtechreqs.xml 2007-08-02 13:16:21
UTC (rev 2005)
+++ trunk/docs/userguide/en/src/main/docbook/modules/RFCtechreqs.xml 2007-08-02 13:29:43
UTC (rev 2006)
@@ -52,7 +52,7 @@
to be compatible with the widest possible variety of environments.</para>
<para>This is what you need to start working with
- <property>RichFaces</property>:</para>
+ <property>RichFaces 3.1</property>:</para>
<itemizedlist>
<listitem>Java</listitem>
Added: trunk/docs/userguide/en/src/main/resources/images/newpic1.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/docs/userguide/en/src/main/resources/images/newpic1.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/userguide/en/src/main/resources/images/newpic2.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/docs/userguide/en/src/main/resources/images/newpic2.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/userguide/en/src/main/resources/images/newpic3.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/docs/userguide/en/src/main/resources/images/newpic3.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/userguide/en/src/main/resources/images/newpic4.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/docs/userguide/en/src/main/resources/images/newpic4.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream