Author: msorokin
Date: 2009-01-05 14:10:59 -0500 (Mon, 05 Jan 2009)
New Revision: 12121
Modified:
trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml
Log:
https://jira.jboss.org/jira/browse/RF-5361
Added the chapter about the queue component
Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2009-01-05
18:54:38 UTC (rev 12120)
+++ trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2009-01-05
19:10:59 UTC (rev 12121)
@@ -1,13 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="ArchitectureOverview"
xreflabel="ArchitecturalOverview">
<?dbhtml filename="ArchitectureOverview.html"?>
-
<chapterinfo>
<keywordset>
<keyword>RichFaces</keyword>
-
<keyword>CSS</keyword>
-
<keyword>skin</keyword>
</keywordset>
</chapterinfo>
@@ -25,7 +22,6 @@
<para>Next Figure shows how it works:</para>
<figure>
<title>Request Processing flow</title>
-
<mediaobject>
<imageobject>
<imagedata fileref="images/newpic1.png" scalefit="1"/>
@@ -36,8 +32,8 @@
<property>RichFaces</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>
+ "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="RichFacesArchitectureOverview">
<?dbhtml filename="RichFacesArchitectureOverview.html"?>
@@ -46,7 +42,6 @@
framework </para>
<figure>
<title>Core Ajax component structure</title>
-
<mediaobject>
<imageobject>
<imagedata fileref="images/newpic2.png"/>
@@ -58,18 +53,16 @@
<para> To get all benefits of <property>RichFaces</property> , you
should register a
Filter in web.xml file of your application. The Filter recognizes multiple request
types. Necessary information about Filter configuration can be found in the <link
- linkend="FilterConfiguration"> "Filter configuration"
</link>
- section. The sequence diagram on Figure 3 shows the difference in processing of a
- "regular" JSF request and an Ajax request. </para>
+ linkend="FilterConfiguration"> "Filter
configuration"
+ </link> section. 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. 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>
+ depends on the "size" of the Ajax region. 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>
-
<mediaobject>
<imageobject>
<imagedata fileref="images/newpic3.png" scalefit="1"/>
@@ -86,7 +79,6 @@
<para> Next Figure shows the ways of resource request processing. </para>
<figure>
<title>Resource request sequence diagram</title>
-
<mediaobject>
<imageobject>
<imagedata fileref="images/newpic4.png" scalefit="1"/>
@@ -110,7 +102,7 @@
<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. <code>AjaxViewRoot</code> and
- <code>AjaxRegion</code> are implementations of this interface.
</para>
+ <code>AjaxRegion</code> are implementations of this interface.
</para>
</formalpara>
<formalpara>
<title>JavaScript Engine</title>
@@ -124,13 +116,12 @@
<section id="IntegralParts" role="new">
<?dbhtml filename="IntegralParts.html"?>
<title>RichFaces Integral Parts</title>
- <para>
- The <property>RichFaces</property> comes with a number of integral parts
(framework, libraries):
- </para>
+ <para> The <property>RichFaces</property> comes with a number of
integral parts (framework,
+ libraries): </para>
<itemizedlist>
<listitem>
<para>
- <ulink url="http://prototypejs.org">Prototype 1.6.0.3</ulink>
+ <ulink url="http://prototypejs.org">Prototype 1.6.0.3</ulink>
</para>
</listitem>
<listitem>
@@ -140,20 +131,21 @@
</listitem>
<listitem>
<para>
- <ulink url="http://script.aculo.us">Script.aculo.us
1.8.1</ulink>
+ <ulink url="http://script.aculo.us">Script.aculo.us
1.8.1</ulink>
</para>
</listitem>
</itemizedlist>
- <para>
- For more information about framework and libraries loading see the following section
- in the <ulink
url="http://www.jboss.org/file-access/default/members/jbossrichfaces...;.
- </para>
+ <para> For more information about framework and libraries loading see the
following section
+ in the <ulink
+
url="http://www.jboss.org/file-access/default/members/jbossrichfaces...
+ >FAQ</ulink>. </para>
<note>
<title>Note:</title>
- <para>
- In order to prevent JavaScript versions conflict you should use only one version of
the framework or library.
- You could find more information about libraries exclusion in the <ulink
url="http://www.jboss.org/file-access/default/members/jbossrichfaces...;.
- </para>
+ <para> In order to prevent JavaScript versions conflict you should use only one
version
+ of the framework or library. You could find more information about libraries
+ exclusion in the <ulink
+
url="http://www.jboss.org/file-access/default/members/jbossrichfaces...
+ >FAQ</ulink>. </para>
</note>
</section>
<section id="LimitationsAndRules">
@@ -165,8 +157,8 @@
<listitem>
<para> Any 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
+ 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 role="bold">
<property>"AjaxOutput"</property>
</emphasis> component (as no messages is also a message). </para>
@@ -199,7 +191,6 @@
</listitem>
</itemizedlist>
</section>
-
<section id="AjaxRequestOptimization">
<?dbhtml filename="AjaxRequestOptimization.html"?>
<title>Ajax Request Optimization</title>
@@ -221,16 +212,15 @@
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>
+ 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[...
<a4j:commandButton value="update"
reRender="infoBlock"/>
...
@@ -239,7 +229,6 @@
</h:panelGrid>
...
]]></programlisting>
-
<para> The value of <emphasis>
<property>"reRender"</property>
</emphasis> attribute of the <emphasis role="bold">
@@ -253,7 +242,6 @@
elements on the page, only list their IDs as the value of <emphasis>
<property>"reRender"</property>
</emphasis> . </para>
-
<para>
<emphasis>
<property>"reRender"</property>
@@ -265,7 +253,6 @@
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[...
<h:form id="form1">
...
@@ -285,13 +272,11 @@
</f:subview>
...
]]></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> Most common problem with using reRender is pointing it to the component
that has
a <emphasis>
<property>"rendered"</property>
@@ -308,24 +293,22 @@
<property><a4j:outputPanel></property>
</emphasis>
<code>layout="none"</code> . </para>
-
<para>
<emphasis>
<property>"ajaxRendered"</property>
</emphasis> attribute of the <emphasis role="bold">
<property><a4j:outputPanel></property>
- </emphasis> set to "true" 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>
+ </emphasis> set to "true" 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>
@@ -334,13 +317,12 @@
</emphasis>
<emphasis>
<property>"ajaxRendered"</property>
- </emphasis> attribute. <code>limitToList =
"false"</code> means to
- update only the area(s) that mentioned in the <emphasis>
+ </emphasis> attribute. <code>limitToList =
"false"</code> means to update
+ only the area(s) that mentioned in the <emphasis>
<property>"reRender"</property>
</emphasis> attribute explicitly. All output panels with
- <code>ajaxRendered="true"</code> is ignored. An
example is
- placed below: </para>
-
+ <code>ajaxRendered="true"</code> is ignored. An
example is placed
+ below: </para>
<programlisting role="XML"><![CDATA[...
<h:form>
<h:inputText value="#{person.name}">
@@ -350,9 +332,7 @@
</form>
...
]]></programlisting>
-
</section>
-
<section id="QueueandTrafficFloodProtection">
<?dbhtml filename="QueueandTrafficFloodProtection.html"?>
<title>Queue and Traffic Flood Protection</title>
@@ -371,33 +351,31 @@
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 you type very fast and
- has typed the several characters already before the previous Ajax Response is back.
</para>
-
+ 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 you type very fast and has typed the
+ several characters already before the previous Ajax Response is back. </para>
<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>
+ 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.
- <code>ignoreDupResponses"="true"</code> 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>
+ <code>ignoreDupResponses"="true"</code> 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>
@@ -412,11 +390,9 @@
<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>
-
+
url="http://jboss.com/index.html?module=bb&op=viewtopic&...
+ RichFaces Users Forum </ulink> . </para>
<para>
<emphasis>
<property>"timeout"</property>
@@ -424,7 +400,269 @@
request. If a response is not received during this time, the request is aborted.
</para>
</section>
+ <section id="QueuePrinciples">
+ <title>Queue Principles</title>
+ <para>Starting from 3.3.0 version RichFaces has a improved queue functionality.
The new
+ implementation provides a rich flexibility for making queues of Ajax requests. You
+ can use the queue in a number of ways: </para>
+ <itemizedlist>
+ <listitem><para>
+ Global default queue, defined in the web.xml file
+ </para>
+ </listitem>
+ <listitem>
+ <para>View scoped default queue</para>
+ </listitem>
+ <listitem>
+ <para>View scoped named queue</para>
+ </listitem>
+ <listitem>
+ <para>Form-based default queue</para>
+ </listitem>
+ </itemizedlist>
+ <para>In this section we will take a closer look at the listed above types of
the queue
+ and see in more detail how they differ.</para>
+ <section>
+ <title>Global default queue, defined in the web.xml file</title>
+
+ <para>Design details</para>
+ <itemizedlist>
+ <listitem><para>Only one global queue will ever exist on a
view</para>
+
+ <para>If you define more that one with this name while attempting to set its
attributes a warning will appear in server console
+ during rendering. All the same named queues after the first instance are
ignored.</para></listitem>
+ <listitem><para>The queue class name is
"org.richfaces.queue.global"</para>
+
+ </listitem>
+
+ </itemizedlist>
+
+
+ <para>Global default queue has application scope and is defined in the
+ web.xml</para>
+ <para>It can be done as follows:</para>
+ <programlisting role="XML"><![CDATA[...
+<context-param>
+ <param-name>org.richfaces.queue.global.enabled</param-name>
+ <param-value>true</param-value>
+</context-param>
+...
+]]></programlisting>
+ <para>The global default queue is disabled by default, because artificial
+ serializing of all Ajax requests on a page can significantly affect expected
+ behavior. </para>
+
+ </section>
+ <section>
+ <title>View scoped default queue</title>
+
+ <para>Design details</para>
+ <itemizedlist>
+ <listitem><para>Only one default queue is ever active at one time for a
given view or form.</para></listitem>
+ <listitem><para>If ever more are detected a warning will appears in
server console during rendering.
+ All the same named queues after the first instance are
ignored.</para></listitem>
+ <listitem><para>View scoped default queue is also created
+ for components which have the following ajax attributes: (in this case queue has a
component scope)</para>
+ <itemizedlist>
+ <listitem><para><emphasis><property>"requestDelay"
</property></emphasis></para></listitem>
+ <listitem><para><emphasis><property>"ignoreDupResponce"
</property></emphasis></para></listitem>
+ </itemizedlist>
+
+ </listitem>
+ <listitem><para>View scoped default queue is created automatically if
the <emphasis><property>"eventsQueue"
</property></emphasis> attribute is defined with some name in a component but
not found in the view. It has a scope the same as defined in corresponding context
param.</para></listitem>
+ </itemizedlist>
+
+ <para>The view scoped default, named and formed-based types of queue utilize
the
+ <emphasis role="bold">
+ <property><a4j:queue></property></emphasis> tag to
override the
+ settings of the global queue defined in the web.xml file. </para>
+ <para> You can also programmatically enable/disable the global queue on a
single
+ view using the following:</para>
+ <programlisting role="XML"><![CDATA[...
+<a4j:queue name="org.richfaces.global_queue" disabled="true"...
/>
+...
+]]></programlisting>
+ <para>Hence, to enable the queue for a single view page you need to define
the
+ <property>"disable"</property> attribute with
+ "false". </para>
+ <para> Now, you can override the default settings using the attributes of the
+ <emphasis role="bold">
+ <property><a4j:queue></property></emphasis>
component. The full
+ <ulink
+ url="file:///C:/Projects/RichFaces/docs/userguide/en/target/docbook/publish/en-US/html_single/index.html#d0e10019"
+ >list of attributes</ulink> is given in the
<emphasis>"6.20. <a4j:queue>"</emphasis>
chapter of the guide.</para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<a4j:queue name="org.richfaces.global_queue" requestDelay="1000"
/>
+...]]></programlisting>
+ <para> View scoped queue can be also added by just definition of the queue
+ without name specified. In this case it should be placed anywhere outside
+ the forms in order not to be recognized as a form-based queue. </para>
+ <programlisting role="XML"><![CDATA[...
+<a4j:queue ... />
+...
+]]></programlisting>
+ </section>
+ <section>
+ <title>View scoped named queue</title>
+
+ <para>Design details</para>
+ <itemizedlist>
+ <listitem><para>Named queues must have a unique name,
+ if a second queue with the same name is defined all the same named queues after
the first instance are ignored.</para></listitem>
+ <listitem><para>Form elements are used as naming container for the
queue i.e. custom queue defined within the form cannot be used by the components outside
this concrete form. </para></listitem>
+
+ </itemizedlist>
+
+
+ <para>You can reference a named queue from any Ajax4JSF or RichFaces
+ component that supports the "eventsQueue" attribute. Below
+ there is an example of how the components can reference a named
+ queue.</para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<a4j:queue name="sampleQueue"/>
+<h:inputText value="#{bean.inputValue}" >
+<a4j:support id="inputSupport" event="onkeyup"
eventsQueue="sample"/>
+</h:inputText>
+<rich:comboBox value="#{bean.state}"
suggestionValues="#{bean.suggestions}" eventsQueue="sample" />
+
+...]]></programlisting>
+ <para>In this example, two components(<a4j:queue>,
+ <rich:comboBox>,) reference the named queue via the
+ "eventsQueue" attribute. </para>
+ </section>
+ <section>
+ <title>Form based default queue</title>
+ <para>Design details</para>
+ <itemizedlist>
+ <listitem><para>Only one enabled form based default queue can be active
at a time.</para>
+ <itemizedlist>
+ <listitem><para>A warning appears in server console during rendering if
more than one enabled form based queue exists.
+ All queues with the same name after the first instance should be ignored.
+ </para></listitem>
+ <listitem><para>Users can define more than one form queue, however all
but one must be disabled.
+ </para></listitem>
+
+ </itemizedlist>
+
+
+ </listitem>
+
+ </itemizedlist>
+
+ <para>Queues are often used within forms, but defining the
<emphasis><property>"eventsQueue"</property></emphasis>
attribute on every component within a form can be tedious work.
+ To avoid that you can create a default queue for a form (overriding the global
default queue ).</para>
+
+ <para>You can use either a JSF <h:form> or an Ajax4JSF
<a4j:form>. </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:form ... >
+<a4j:queue ... /><!-- note no name specified -->
+ ...
+</h:form>
+...]]></programlisting>
+
+ <para>Though, using an Ajax4JSF <a4j:form> you can refrence a
named queue via the
<emphasis><property>"eventsQueue"</property></emphasis>.
</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<a4j:form eventsQueue="fooQueue" ...>
+ ...
+</a4j:form>
+...]]></programlisting>
+ <para>However the implementation of the queue allows you to reference a named
queue from the form with a form-based queue.</para>
+
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<a4j:queue name="sampleQueue" ... /> <!-- named queue -->
+...
+<h:form ... >
+ <a4j:queue ... /><!-- form-based queue-->
+ <a4j:commandButton ... > <!-- uses the form-based queue -->
+ <a4j:commandButton eventsQueue="sampleQueue" > <!-- uses named queue
-->
+</h:form>
+...]]></programlisting>
+
+
+
+
+ </section>
+
+<section>
+ <title>Queue functionality</title>
+ <para>
+ This section will cover some queue's functionality aspects.
+
+ </para>
+
+ <section>
+ <title>Events Similarity</title>
+ <para>By default all the events raised by the same component
+ are similar to the queue (according to client Id of event source).
+ This means that if new requests come from the same component they are combined with
the previous ones.
+ For example: if we use a4j:support on an input field and the user types frequently
+ all the request raised by key up during requestDelay will be combined into one.
+ </para>
+ <para>
+
+ You can also manually specify multiple components which will produce similar requests.
The
<emphasis><property>"similarityGroupingId"</property></emphasis>
attribute is added to all the Ajax action components with 3.3.0 release.
+ Hence, for example, you can add two <a4j:support/> components to the
input
+ (one for key up and the second for blur) and define that request events are similar by
specifying the same
<emphasis><property>"similarityGroupingId"</property></emphasis>.
+
+ </para>
+ <para>
+ As written above requests are collected in the queue during requestDelay and similar
ones are combined.
+ But similar requests can only be combined if they are raised sequentially.
+ This is done in order not to block the queue and not to change the requests order.
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <para>
+ A request with some delay comes to the queue, let it be
A<superscript>1</superscript> the delay counter for this request is started.
+ If similar request(e.g. from the same component -
A<superscript>2</superscript>) appears - these two requests are
combined(A<superscript>1</superscript>A<superscript>2</superscript>
to A<superscript>combined</superscript> ) and the counter is reset.
+ </para>
+ <para>
+ But if some not similar request comes to the queue
B<superscript>1</superscript> - it is placed after the first
one(A<superscript>combined</superscript>,B<superscript>1</superscript>).
And if the A<superscript>combined</superscript> request doesn't exit the
queue and another request similar to A (let is be
A<superscript>3</superscript>) appears again - these requests are not combined
with the first one.
+ The request is placed after B<superscript>1</superscript>.
(A<superscript>combined</superscript>,
B<superscript>1</superscript>, A<superscript>3</superscript>).
+ </para>
+ <para>Such behavior allows</para>
+ <itemizedlist>
+ <listitem><para>to maximize similar requests
throughput</para></listitem>
+ <listitem><para>to send only the latest fields state for similar
requests</para></listitem>
+ <listitem><para>not to block the queue if the different types of requests
comes to queue and should wait one for another</para></listitem>
+ </itemizedlist>
+
+ <para>
+
+ The <emphasis role="bold">
+ <property><a4j:poll></property>
+ </emphasis> component has delay time 0 by default staring from 3.3.0 version in
order not to use the queue delay(its own value for this parameter redefines queue's
parameter) to avoid blocking periodical update in the queue. You can redefine this on the
component level if need.
+ </para>
+
+
+
+
+
+ </section>
+
+</section>
+
+
+ </section>
<section id="DataProcessingOptions">
<?dbhtml filename="DataProcessingOptions.html"?>
<title>Data Processing Options</title>
@@ -436,8 +674,8 @@
form input element and auxiliary information such as state saving data.
</para>
<para> When <emphasis>
<property>"ajaxSingle"</property>
- </emphasis> attribute value is "true" , it orders to include
only
- a value of the current component (along with <emphasis role="bold">
+ </emphasis> attribute value is "true" , 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>
@@ -445,7 +683,6 @@
role="bold">
<property><a4j:support></property>
</emphasis> , it is a value of the parent component. An example is placed
below: </para>
-
<programlisting role="XML"><![CDATA[...
<h:form>
<h:inputText value="#{person.name}">
@@ -458,9 +695,9 @@
<para> In this example the request contains only the input component causes the
request
generation, not all the components contained on a form, because of
<code>ajaxSingle="true"</code> usage. </para>
- <para> Note, that <code>ajaxSingle="true"</code>
reduces the upcoming
- traffic, but does not prevent decoding other input components on the server side.
- Some JSF components, such as <emphasis role="bold">
+ <para> Note, that <code>ajaxSingle="true"</code>
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
@@ -476,9 +713,9 @@
<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 <code>immediate="true"</code>
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
+ Application phase. Using <code>immediate="true"</code>
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">
@@ -486,7 +723,6 @@
</emphasis> is impossible due to the <emphasis role="bold">
<property><h:dataTable></property>
</emphasis> component architecture. </para>
-
<para>
<emphasis>
<property>"bypassUpdates"</property>
@@ -496,7 +732,6 @@
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>
@@ -512,14 +747,15 @@
<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 <code>"Ajax request
- generates Non-Ajax Response"</code>. In case of action does not
return
- null, but the action outcome that matches one of navigation rules, RichFaces starts
- to work in <code>"Ajax request generates Non-Ajax
Response"</code>
- mode. This mode might be helpful in two major cases: </para>
+ partual page update. This is regular mode called <code>"Ajax request
generates
+ Non-Ajax Response"</code>. In case of action does not return null,
but the
+ action outcome that matches one of navigation rules, RichFaces starts to work in
+ <code>"Ajax request generates Non-Ajax
Response"</code> mode. This
+ mode might be helpful in two major cases: </para>
<itemizedlist>
<listitem>
- <para> RichFaces allows to organize a page flow inside the <emphasis
role="bold">
+ <para> 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">
@@ -541,7 +777,8 @@
replace <emphasis role="bold">
<property><h:commandButton></property>
</emphasis> with <emphasis role="bold">
- <property> <a4j:commandButton> </property>
+ <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 you will
see an error message. Otherwize, the application proceeds to the next page.
@@ -552,7 +789,6 @@
</itemizedlist>
<para/>
</section>
-
<section id="JavascriptInteractions">
<?dbhtml filename="JavascriptInteractions.html"?>
<title>JavaScript Interactions</title>
@@ -565,20 +801,19 @@
</emphasis> attribute allows to invoke JavaScript code before an Ajax request
is
sent. If <emphasis>
<property>"onsubmit"</property>
- </emphasis> returns "false" , the Ajax request is canceled.
The
- code of <emphasis>
+ </emphasis> returns "false" , 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 "true" or "false" , use the conditional
- statement to return something only when you need to cancel the request. For example:
</para>
+ </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
+ "true" or "false" , 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>
@@ -588,23 +823,18 @@
<property><a4j:commandLink></property>
</emphasis> and <emphasis role="bold">
<property><a4j:commandButton></property>
- </emphasis> . If it returns "false" , the Ajax request is
canceled
- also. </para>
+ </emphasis> . If it returns "false" , the Ajax request is
canceled also. </para>
<para>
- <emphasis>
- The <property>"oncomplete"</property>
- </emphasis> attribute is used for passing JavaScript
- that would be invoked right after the AJAX response returns back and DOM is updated.
- It is not recommended to use use keyword <code>this</code> inside the
EL-expression,
- because it will not always point to the component where AJAX request was initiated.
- </para>
-
+ <emphasis> The <property>"oncomplete"</property>
+ </emphasis> attribute is used for passing JavaScript that would be invoked
right
+ after the AJAX response returns back and DOM is updated. It is not recommended to
+ use use keyword <code>this</code> inside the EL-expression, because it
will not
+ always point to the component where AJAX request was initiated. </para>
<para>
<emphasis>
<property>"onbeforedomupdate"</property>
</emphasis> attribute defines JavaScript code for call after Ajax response
receiving
and before updating DOM on a client side. </para>
-
<para>
<emphasis>
<property>"data"</property>
@@ -618,7 +848,6 @@
<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>
@@ -656,7 +885,6 @@
</listitem>
</itemizedlist>
</section>
-
<section id="IterationcomponentsAjaxattributes">
<?dbhtml filename="IterationcomponentsAjaxattributes.html"?>
<title>Iteration components Ajax attributes</title>
@@ -666,7 +894,6 @@
</emphasis> attribute defines strings that are updated after an Ajax request.
It
provides possibility to update several child components separately without updating
the whole page. </para>
-
<programlisting role="XML"><![CDATA[...
<a4j:poll intervall="1000" action="#{repeater.action}"
reRender="text">
<table>
@@ -683,9 +910,7 @@
</a4j:poll>
...
]]></programlisting>
-
</section>
-
<section id="Otherusefulattributes">
<?dbhtml filename="Otherusefulattributes.html"?>
<title>Other useful attributes</title>
@@ -698,11 +923,11 @@
<property><a4j:poll></property>
</emphasis> , etc.) points to an ID of <emphasis role="bold">
<property><a4j:status></property>
- </emphasis> component. Use this attribute if you want to share <emphasis
role="bold">
+ </emphasis> component. Use this attribute if you want to share <emphasis
role="bold"
+ >
<property><a4j:status></property>
</emphasis> component between different Ajax components from different regions.
The
following example shows it. </para>
-
<programlisting role="XML"><![CDATA[...
<a4j:region id="extr">
<h:form>
@@ -733,7 +958,6 @@
</a4j:region>
...
]]></programlisting>
-
<para> In the example <emphasis role="bold">
<property><a4j:support></property>
</emphasis> and <emphasis role="bold">
@@ -745,20 +969,15 @@
</emphasis> .Thus, the <emphasis role="bold">
<property><a4j:support></property>
</emphasis> component is shared between two components from different regions.
</para>
-
<para> More information could be found <ulink
url="http://livedemo.exadel.com/richfaces-demo/richfaces/status.jsf?...
here </ulink> . </para>
-
<para> Other useful attribute is <emphasis>
<property>"focus"</property>
</emphasis> . It points to an ID of a component where focus will be set after
an
Ajax request. </para>
-
</section>
-
</section>
-
<section id="HowTo...">
<?dbhtml filename="HowTo.html"?>
<title>How To...</title>
@@ -849,12 +1068,7 @@
<property>"ignoreDupResponses"</property>
</emphasis> is used to abort unfinished request on new event.
</listitem>
</itemizedlist-->
-
-
</section>
-
-
-
<section id="DecideWhatToSend">
<?dbhtml filename="DecideWhatToSend.html"?>
<title>Decide What to Send</title>
@@ -874,19 +1088,17 @@
<para> If you wish to render the content of an Ajax response outside of the
active
region then the value of the <emphasis>
<property>"renderRegionOnly"</property>
- </emphasis> attribute should be set to "false"
- ("false" is default value). Otherwise, your Ajax updates are
- limited to elements of the active region. </para>
+ </emphasis> attribute should be set to "false"
("false" is
+ default value). 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 <emphasis>
<property>"reRender"</property>
- </emphasis> attribute to define <code>"AJAX
zones"</code> for
- update works fine in many cases. </para>
+ </emphasis> attribute to define <code>"AJAX
zones"</code> 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>
@@ -917,8 +1129,7 @@
</emphasis> attribute value of an Action Component to the output panel
ID. </para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
</section>
<section id="process" role="updated">
<title>Decide what to process</title>
@@ -934,8 +1145,8 @@
<para> Imagine you need to process only two input fields but not all the view.
If you
wrap the first input to region or make <emphasis role="bold">
<property><a4j:support></property>
- </emphasis> component with
<code>ajaxSingle="true"</code> nested
- the second input will not be processed. </para>
+ </emphasis> component with
<code>ajaxSingle="true"</code> nested the
+ second input will not be processed. </para>
<para> Here is a simple solution: </para>
<programlisting role="XML"><![CDATA[...
<h:inputText value="#{bean.name}" id="name">
@@ -947,12 +1158,11 @@
</h:inputText>
...]]></programlisting>
<para> In the example above when the input field with the
- <code>id="name"</code> looses focus, an AJAX request
is sent.
- So only two input fields (with <code>id="name"</code>
and
- additionally with <code>id="email"</code>) are
processed:
- decoding, conversion/validation, value applying phases are executed. The input field
- with the <code>id="email"</code> is handled the same
way on blur
- event. </para>
+ <code>id="name"</code> looses focus, an AJAX request
is sent. So only
+ two input fields (with <code>id="name"</code> and
additionally with
+ <code>id="email"</code>) are processed: decoding,
+ conversion/validation, value applying phases are executed. The input field with the
+ <code>id="email"</code> is handled the same way on
blur event. </para>
<!--para>
The
<emphasis>
@@ -1024,24 +1234,19 @@
</para-->
</section>
</section>
-
-
<section id="FilterConfiguration">
<?dbhtml filename="FilterConfiguration.html"?>
<title>Filter Configuration</title>
<para> RichFaces uses a filter for a correction of code received on an Ajax
request. In case
- of a "regular" JSF request a browser makes correction
independently.
- In case of Ajax request in order to prevent layout destruction it's needed
to
- use a filter, because a received code could differ from a code validated by a browser
- and a browser doesn't make any corrections. </para>
-
+ of a "regular" JSF request a browser makes correction independently.
In case
+ of Ajax request in order to prevent layout destruction it's needed to use a
filter,
+ because a received code could differ from a code validated by a browser and a browser
+ doesn't make any corrections. </para>
<para> An example of how to set a Filter in a web.xml file of your application is
placed
below. </para>
-
<para>
<emphasis role="bold">Example:</emphasis>
</para>
-
<programlisting role="XML"><![CDATA[...
<filter>
<display-name>RichFaces Filter</display-name>
@@ -1050,56 +1255,44 @@
</filter>
...
]]></programlisting>
-
<note>
<title>Note:</title>
<para> Fast Filter is deprecated and available only for backward compatibility
with
- previous RichFaces versions. Fast Filter usage isn't recomended, because
- there is another way to use its functionality by means of <link
linkend="Neko">Neko
- filter type</link> . </para>
+ previous RichFaces versions. Fast Filter usage isn't recomended, because
there
+ is another way to use its functionality by means of <link
linkend="Neko">Neko filter
+ type</link> . </para>
</note>
-
- <para> In RichFaces 3.2 filter configuration becomes more flexible. It's
possible
- to configure different filters for different sets of pages for the same application.
</para>
-
+ <para> In RichFaces 3.2 filter configuration becomes more flexible. It's
possible to
+ configure different filters for different sets of pages for the same application.
</para>
<para>The possible filter types are:</para>
-
<itemizedlist>
<listitem>
<para>TIDY</para>
</listitem>
</itemizedlist>
-
- <para> "TIDY" filter type based on the Tidy parser. This filter
is
- recommended for applications with complicated or non-standard markup when all
necessary
- code corrections are made by the filter when a response comes from the server.
</para>
-
+ <para> "TIDY" filter type based on the Tidy parser. This filter
is recommended for
+ applications with complicated or non-standard markup when all necessary code
corrections
+ are made by the filter when a response comes from the server. </para>
<itemizedlist>
<listitem>
<para id="Neko">NEKO</para>
</listitem>
</itemizedlist>
-
- <para> "NEKO" filter type corresponds to the former
"Fast
- Filter" and it's based on the Neko parser. In case of using this
- filter code isn't strictly verified. Use this one if you are sure that your
- application markup is really strict for this filter. Otherwise it could cause
- lot's of errors and corrupt a layout as a result. This filter considerably
- accelerates all Ajax requests processing. </para>
-
+ <para> "NEKO" filter type corresponds to the former
"Fast Filter" and
+ it's based on the Neko parser. In case of using this filter code
isn't
+ strictly verified. Use this one if you are sure that your application markup is
really
+ strict for this filter. Otherwise it could cause lot's of errors and corrupt
a
+ layout as a result. This filter considerably accelerates all Ajax requests processing.
</para>
<itemizedlist>
<listitem>
<para>NONE</para>
</listitem>
</itemizedlist>
-
<para>No correction.</para>
-
<para>An example of configuration is placed below.</para>
<para>
<emphasis role="bold">Example:</emphasis>
</para>
-
<programlisting role="XML"><![CDATA[...
<context-param>
<param-name>org.ajax4jsf.xmlparser.ORDER</param-name>
@@ -1131,29 +1324,23 @@
</filter-mapping>
...
]]></programlisting>
-
<para> The example shows that <code>ORDER</code> parameter defines
the order in which
particular filter types are used for pages code correction. </para>
- <para> First of all "NONE" type is specified for the filter.
Then two
- different sets of pages are defined for which two filter types (NONE and NEKO) are
used
+ <para> First of all "NONE" type is specified for the filter.
Then two different
+ sets of pages are defined for which two filter types (NONE and NEKO) are used
correspondingly. If a page relates to the first set that is defined in the following
way: </para>
-
<programlisting
role="XML"><![CDATA[<param-value>/pages/performance\.xhtml,/pages/default.*\.xhtml</param-value>,
]]></programlisting>
-
<para> it's not corrected, because filter type for this page is defined
as
- "NONE". If a page is not from the first set, then
- "NEKO" type is set. </para>
+ "NONE". If a page is not from the first set, then
"NEKO" type is
+ set. </para>
<para> If a page relates to the second set that is defined in the following way:
</para>
-
<programlisting
role="XML"><![CDATA[<param-value>/pages/repeat\.xhtml</param-value>,
]]></programlisting>
-
- <para> then "NEKO" filter type is used for correction. If
it's
- not related to the second set, "TIDY" type is set for the filter
- ("TIDY" filter type is used for code correction). </para>
-
+ <para> then "NEKO" filter type is used for correction. If
it's not related to
+ the second set, "TIDY" type is set for the filter
("TIDY" filter
+ type is used for code correction). </para>
</section>
<section id="ScriptsandStylesLoadStrategy" role="updated">
<?dbhtml filename="ScriptsandStylesLoadStrategy" ?>
@@ -1182,10 +1369,9 @@
</context-param>
...
]]></programlisting>
- <para> The third possible value is "NONE". You have no a
special reason to
- use it unless you obtain the newest (or modified) version of the script and want to
- include it manually in a page header. </para>
-
+ <para> The third possible value is "NONE". You have no a
special reason to use it
+ unless you obtain the newest (or modified) version of the script and want to include
it
+ manually in a page header. </para>
<note>
<title>Note:</title>
<para> If you use <property>ALL</property> value of Scripts Load
Strategy, the
@@ -1198,11 +1384,9 @@
...
]]></programlisting-->
</note>
-
<para>
<emphasis
role="bold">org.richfaces.LoadStyleStrategy</emphasis>
</para>
-
<para> The following declaration allows to load only one integrated style sheet
file. </para>
<programlisting role="XML"><![CDATA[...
<context-param>
@@ -1214,24 +1398,21 @@
<para> The integrated style sheet contains style for all shipped components. The
skinnability feature still works. </para>
<para> The "DEFAULT" value is a classical on-demand variant.
</para>
- <para> The "NONE" stops loading the styles at all. The earlier
introduced
- plain skin resets all color and font parameters to null. The "NONE"
- value for <code>org.richfaces.LoadStyleStrategy</code> means that
predefined styles for
+ <para> The "NONE" stops loading the styles at all. The earlier
introduced plain
+ skin resets all color and font parameters to null. The "NONE" value
for
+ <code>org.richfaces.LoadStyleStrategy</code> means that predefined styles
for
RichFaces are not used. </para>
<para> For more information see <ulink
-
url="http://www.jboss.com/index.html?module=bb&op=viewtopic&...
- > RichFaces User Forum </ulink> . </para>
+
url="http://www.jboss.com/index.html?module=bb&op=viewtopic&...
+ RichFaces User Forum </ulink> . </para>
</section>
-
<section id="RequestErrorsAndSessionExpirationHandling">
<?dbhtml filename="RequestErrorsAndSessionExpirationHandling.html"?>
<title>Request Errors and Session Expiration Handling</title>
<para> RichFaces allows to redefine standard handlers responsible for processing
of
different exceptional situations. It helps to define own JavaScript, which is
executed
when these situations occur. </para>
- <para>
- Add the following code to web.xml:
- </para>
+ <para> Add the following code to web.xml: </para>
<programlisting role="XML"><![CDATA[<context-param>
<param-name>org.ajax4jsf.handleViewExpiredOnClient</param-name>
<param-value>true</param-value>
@@ -1261,8 +1442,8 @@
<code>message</code> - a default message for the given error
</para>
</listitem>
</itemizedlist>
- <para> Thus, it's possible to create your own handler that is called
on
- timeouts, internal server errors, and etc. </para>
+ <para> Thus, it's possible to create your own handler that is called on
timeouts,
+ internal server errors, and etc. </para>
</section>
<section id="SessionExpiredHandling">
<?dbhtml filename="SessionExpiredHandling.html"?>
@@ -1272,11 +1453,9 @@
</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){
if(window.confirm("Custom onExpired handler "+expiredMsg+" for a
location: "+loc)){
@@ -1285,7 +1464,6 @@
return false;
}
}]]></programlisting>
-
<para>Here the function receives in params:</para>
<itemizedlist>
<listitem>
@@ -1296,17 +1474,18 @@
<listitem>
<para>
<code> expiredMsg </code>- a default message on <emphasis>
- <property> "Session Expiration" </property>
+ <property> "Session Expiration"
+ </property>
</emphasis> event. </para>
</listitem>
</itemizedlist>
<note>
<title>Note:</title>
- <para>
- Note that custom
<emphasis><property>"onError"</property></emphasis>,
<emphasis><property>"onExpire"</property></emphasis>
handlers
- do not work under MyFaces. MyFaces handles exception by its internals generating
debug page.
- You could use the following code to prevent such behavior:
- </para>
+ <para> Note that custom <emphasis><property
+ >"onError"</property></emphasis>,
<emphasis><property
+ >"onExpire"</property></emphasis> handlers do not
work under
+ MyFaces. MyFaces handles exception by its internals generating debug page. You
+ could use the following code to prevent such behavior: </para>
<programlisting role="XML"><![CDATA[...
<context-param>
<param-name>org.apache.myfaces.ERROR_HANDLING</param-name>
@@ -1322,117 +1501,91 @@
</note-->
</section>
</section>
-
-
-
<section id="Skinnability">
<?dbhtml filename="Skinnability.html"?>
<title>Skinnability</title>
-
<section id="WhySkinnability">
<?dbhtml filename="WhySkinnability.html"?>
<title>Why Skinnability</title>
-
<para> If you have a look at a CSS file in an enterprise application, for
example, the
- one you're working on now, you'll see how often the same color is
- noted in it. Standard CSS has no way to define a particular color abstractly for
- defining as a panel header color, a background color of an active pop-up menu item,
- a separator color, etc. To define common interface styles, you have to copy the same
- values over and over again and the more interface elements you have the more
- copy-and-paste activity that needs to be performed. </para>
-
+ one you're working on now, you'll see how often the same color is
noted in
+ it. Standard CSS has no way to define a particular color abstractly for defining as
+ a panel header color, a background color of an active pop-up menu item, a separator
+ color, etc. To define common interface styles, you have to copy the same values over
+ and over again and the more interface elements you have the more copy-and-paste
+ activity that needs to be performed. </para>
<para> Hence, if you want to change the application palette, you have to change
all
interrelating values, otherwise your interface can appear a bit clumsy. The chances
of such an interface coming about is very high, as CSS editing usually becomes the
- duty of a general developer who doesn't necessarily have much knowledge of
- user interface design. </para>
-
+ duty of a general developer who doesn't necessarily have much knowledge of
user
+ interface design. </para>
<para> Moreover, if a customer wishes to have an interface look-and-feel that
can be
adjusted on-the-fly by an end user, your work is multiplied, as you have to deal
with several CSS files variants, each of which contains the same values repeated
numerous times. </para>
-
<para> These problems can be solved with the
<property>skinnability</property> system
built into the RichFaces project and realized fully in RichFaces. Every named skin
has some skin-parameters for the definition of a palette and the other parameters of
the user interface. By changing just a few parameters, you can alter the appearance
of dozens of components in an application in a synchronized fashion without messing
up user interface consistency. </para>
-
<para> The <property>skinnability</property> feature can't
completely replace
- standard CSS and certainly doesn't eliminate its usage.
- <property>Skinnability</property> is a high-level extension of standard
CSS,
- which can be used together with regular CSS declarations. You can also refer to skin
- parameters in CSS via JSF Expression Language. You have the complete ability to
- synchronize the appearance of all the elements in your pages. </para>
+ standard CSS and certainly doesn't eliminate its usage. <property
+ >Skinnability</property> is a high-level extension of standard CSS, which
can be
+ used together with regular CSS declarations. You can also refer to skin parameters
+ in CSS via JSF Expression Language. You have the complete ability to synchronize the
+ appearance of all the elements in your pages. </para>
</section>
-
<section id="UsingSkinnability">
<?dbhtml filename="UsingSkinnability.html"?>
<title>Using Skinnability</title>
-
<para> RichFaces <property>skinnability</property> is designed for
mixed usage with: </para>
-
<itemizedlist>
<listitem>
<para> Skin parameters defined in the RichFaces framework </para>
</listitem>
-
<listitem>
<para>Predefined CSS classes for components</para>
</listitem>
-
<listitem>
<para>User style classes</para>
</listitem>
</itemizedlist>
-
<para> The color scheme of the component can be applied to its elements using
any of
three style classes: </para>
-
<itemizedlist>
<listitem>
<para> A default style class inserted into the framework </para>
-
<para> This contains style parameters linked to some constants from a skin.
It
is defined for every component and specifies a default representation level.
Thus, an application interface could be modified by changing the values of
skin parameters. </para>
</listitem>
-
<listitem>
<para>A style class of skin extension</para>
-
<para> This class name is defined for every component element and inserted
into
the framework to allow defining a class with the same name into its CSS
files. Hence, the appearance of all components that use this class is
extended. </para>
</listitem>
-
<listitem>
<para>User style class</para>
-
- <para> It's possible to use one of the styleClass parameters for
- component elements and define your own class in it. As a result, the
- appearance of one particular component is changed according to a CSS style
- parameter specified in the class. </para>
+ <para> It's possible to use one of the styleClass parameters for
component
+ elements and define your own class in it. As a result, the appearance of one
+ particular component is changed according to a CSS style parameter specified
+ in the class. </para>
</listitem>
</itemizedlist>
</section>
-
<section id="Example">
<title>Example</title>
-
<para>Here is a simple panel component:</para>
-
-
<para>
<emphasis role="bold">Example:</emphasis>
</para>
<programlisting role="XML">
<rich:panel> ... </rich:panel>
</programlisting>
-
<para> The code generates a panel component on a page, which consists of two
elements: a
wrapper <emphasis role="bold">
<property><div></property>
@@ -1442,45 +1595,35 @@
wrapper <emphasis role="bold">
<property><div></property>
</emphasis> element looks like: </para>
-
-
<para>
<emphasis role="bold">Example:</emphasis>
</para>
<programlisting role="XML">
<div class="dr-pnl rich-panel"> ... </div>
</programlisting>
-
<para> dr-pnl is a CSS class specified in the framework via skin parameters:
</para>
-
<itemizedlist>
<listitem>
<para>
- <property>background-color</property> is defined with
- <property>generalBackgroundColor</property>
+ <property>background-color</property> is defined with <property
+ >generalBackgroundColor</property>
</para>
</listitem>
-
<listitem>
<para>
- <property>border-color</property> is defined with
- <property>panelBorderColor</property>
+ <property>border-color</property> is defined with <property
+ >panelBorderColor</property>
</para>
</listitem>
</itemizedlist>
-
- <para> It's possible to change all colors for all panels on all pages
by
- changing these skin parameters. </para>
-
+ <para> It's possible to change all colors for all panels on all pages
by changing
+ these skin parameters. </para>
<para> However, if a <emphasis role="bold">
<property><rich:panel></property>
</emphasis> class is specified somewhere on the page, its parameters are also
acquired by all panels on this page. </para>
-
<para> A developer may also change the style properties for a particular panel.
The
following definition: </para>
-
-
<para>
<emphasis role="bold">Example:</emphasis>
</para>
@@ -1488,11 +1631,8 @@
<rich:panel styleClass="customClass"> ...
</rich:panel>
</programlisting>
-
<para> Could add some style properties from customClass to one particular panel,
as a
result we get three styles: </para>
-
-
<para>
<emphasis role="bold">Example:</emphasis>
</para>
@@ -1501,326 +1641,232 @@
</div>
</programlisting>
</section>
-
<section id="SkinParametersTablesInRichFaces">
<?dbhtml filename="SkinParametersTablesInRichFaces.html"?>
-
<title>Skin Parameters Tables in RichFaces</title>
-
<para> RichFaces provides eight predefined skin parameters (skins) at the
simplest level
of common customization: </para>
-
<itemizedlist>
<listitem>
<para>DEFAULT</para>
</listitem>
-
<listitem>
<para>plain</para>
</listitem>
-
<listitem>
<para>emeraldTown</para>
</listitem>
-
<listitem>
<para>blueSky</para>
</listitem>
-
<listitem>
<para>wine</para>
</listitem>
-
<listitem>
<para>japanCherry</para>
</listitem>
-
<listitem>
<para>ruby</para>
</listitem>
-
<listitem>
<para>classic</para>
</listitem>
-
<listitem>
<para>deepMarine</para>
</listitem>
</itemizedlist>
-
<para> To plug one in, it's necessary to specify a skin name in the
<code>org.richfaces.SKIN</code> context-param. </para>
-
- <para> Here is an example of a table with values for one of the main skins,
- <property>"blueSky"</property> . </para>
-
+ <para> Here is an example of a table with values for one of the main skins,
<property
+ >"blueSky"</property> . </para>
<table>
<title>Colors</title>
-
<tgroup cols="2">
<thead>
<row>
<entry>Parameter name</entry>
-
<entry>Default value</entry>
</row>
</thead>
-
<tbody>
<row>
<entry>headerBackgroundColor</entry>
-
<entry>#BED6F8</entry>
</row>
-
<row>
<entry>headerGradientColor</entry>
-
<entry>#F2F7FF</entry>
</row>
-
<row>
<entry>headTextColor</entry>
-
<entry>#000000</entry>
</row>
-
<row>
<entry>headerWeightFont</entry>
-
<entry>bold</entry>
</row>
-
<row>
<entry>generalBackgroundColor</entry>
-
<entry>#FFFFFF</entry>
</row>
-
<row>
<entry>generalTextColor</entry>
-
<entry>#000000</entry>
</row>
-
<row>
<entry>generalSizeFont</entry>
-
<entry>11px</entry>
</row>
-
<row>
<entry>generalFamilyFont</entry>
-
<entry>Arial, Verdana, sans-serif</entry>
</row>
-
<row>
<entry>controlTextColor</entry>
-
<entry>#000000</entry>
</row>
-
<row>
<entry>controlBackgroundColor</entry>
-
<entry>#ffffff</entry>
</row>
-
<row>
<entry>additionalBackgroundColor</entry>
-
<entry>#ECF4FE</entry>
</row>
-
<row>
<entry>shadowBackgroundColor</entry>
-
<entry>#000000</entry>
</row>
-
<row>
<entry>shadowOpacity</entry>
-
<entry>1</entry>
</row>
-
<row>
<entry>panelBorderColor</entry>
-
<entry>#BED6F8</entry>
</row>
-
<row>
<entry>subBorderColor</entry>
-
<entry>#ffffff</entry>
</row>
-
<row>
<entry>tabBackgroundColor</entry>
-
<entry>#C6DEFF</entry>
</row>
-
<row>
<entry>tabDisabledTextColor</entry>
-
<entry>#8DB7F3</entry>
</row>
-
<row>
<entry>trimColor</entry>
-
<entry>#D6E6FB</entry>
</row>
-
<row>
<entry>tipBackgroundColor</entry>
-
<entry>#FAE6B0</entry>
</row>
-
<row>
<entry>tipBorderColor</entry>
-
<entry>#E5973E</entry>
</row>
-
<row>
<entry>selectControlColor</entry>
-
<entry>#E79A00</entry>
</row>
-
<row>
<entry>generalLinkColor</entry>
-
<entry>#0078D0</entry>
</row>
-
<row>
<entry>hoverLinkColor</entry>
-
<entry>#0090FF</entry>
</row>
-
<row>
<entry>visitedLinkColor</entry>
-
<entry>#0090FF</entry>
</row>
</tbody>
</tgroup>
</table>
-
<table>
<title>Fonts</title>
-
<tgroup cols="2">
<thead>
<row>
<entry>Parameter name</entry>
-
<entry>Default value</entry>
</row>
</thead>
-
<tbody>
<row>
<entry>headerSizeFont</entry>
-
<entry>11px</entry>
</row>
-
<row>
<entry>headerFamilyFont</entry>
-
<entry>Arial, Verdana, sans-serif</entry>
</row>
-
<row>
<entry>tabSizeFont</entry>
-
<entry>11px</entry>
</row>
-
<row>
<entry>tabFamilyFont</entry>
-
<entry>Arial, Verdana, sans-serif</entry>
</row>
-
<row>
<entry>buttonSizeFont</entry>
-
<entry>11px</entry>
</row>
-
<row>
<entry>buttonFamilyFont</entry>
-
<entry>Arial, Verdana, sans-serif</entry>
</row>
-
<row>
<entry>tableBackgroundColor</entry>
-
<entry>#FFFFFF</entry>
</row>
-
<row>
<entry>tableFooterBackgroundColor</entry>
-
<entry>#cccccc</entry>
</row>
-
<row>
<entry>tableSubfooterBackgroundColor</entry>
-
<entry>#f1f1f1</entry>
</row>
-
<row>
<entry>tableBorderColor</entry>
-
<entry>#C0C0C0</entry>
</row>
</tbody>
</tgroup>
</table>
-
<para> Skin "plain" was added from 3.0.2 version. It doesn't have
any parameters.
- It's necessary for embedding RichFaces components into existing projecst
- which have its own styles. </para>
-
+ It's necessary for embedding RichFaces components into existing projecst
which
+ have its own styles. </para>
<para> To get detailed information on particular parameter possibilities, see
the <link
linkend="RichFacesComponentsLibrary"> chapter </link> where each
component has
skin parameters described corresponding to its elements. </para>
</section>
-
<section id="CreatingAndUsingYourOwnSkinFile">
<?dbhtml filename="CreatingAndUsingYourOwnSkinFile.html"?>
<title>Creating and Using Your Own Skin File</title>
-
<para> In order to create your own skin file, do the following: </para>
-
<itemizedlist>
<listitem>
<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:
- <code><name>.skin.properties</code> . As an example of
- such file you can see RichFaces predefined skin parameters (skins): blueSky,
- classic, deepMarine, etc. These files are located in the
+ "Skin Parameters Tables in RichFaces"
+ </link> ). The name of skin file should correspond to the following format:
+ <code><name>.skin.properties</code> . As an example of
such file
+ you can see RichFaces predefined skin parameters (skins): blueSky, classic,
+ deepMarine, etc. These files are located in the
<code>richfaces-impl-xxxxx.jar</code> inside the /META-INF/skins
folder.
</para>
</listitem>
-
<listitem>
- <para> Add a skin definition
<code><contex-param></code> to the
- web.xml of your application. An example is placed below: </para>
+ <para> Add a skin definition
<code><contex-param></code> to the web.xml of
+ your application. An example is placed below: </para>
<para>
<emphasis role="bold">Example:</emphasis>
</para>
@@ -1832,10 +1878,9 @@
...
]]></programlisting>
</listitem>
-
<listitem>
- <para> Put your <code><name>.skin.properties</code>
file in one of
- the following classpath elements: META-INF/skins/ or classpath folder (e.g.
+ <para> Put your <code><name>.skin.properties</code>
file in one of the
+ following classpath elements: META-INF/skins/ or classpath folder (e.g.
WEB-INF/classes). </para>
</listitem>
</itemizedlist>
@@ -1887,14 +1932,14 @@
<itemizedlist>
<listitem>
<para> The file must be named
- <code><skinName>.skin.properties</code> , in this
- case, it would be called <code>newskin.skin.properties</code> .
- </para>
+ <code><skinName>.skin.properties</code> , in this
case, it
+ would be called <code>newskin.skin.properties</code> . </para>
</listitem>
<listitem>
<para> The first line in this file should be <code>
- render.kit=<render-kit-id> </code> in this case,
- it would be called <code>render.kit=NEW_SKIN</code> . </para>
+ render.kit=<render-kit-id>
+ </code> in this case, it would be called
+ <code>render.kit=NEW_SKIN</code> . </para>
</listitem>
</itemizedlist>
</listitem>
@@ -1909,7 +1954,6 @@
</member>
</simplelist>
</section>
-
<section id="StControlsSkinning">
<title>Standard controls skinning</title>
<para> The feature is designed to unify the look and feel of standard HTML
element and
@@ -1917,16 +1961,18 @@
elements' name and attribute type (where applicable). Also this feature
provides a set of CSS styles so that skinning can be applied assigning rich-*
classes to particular elements or to container of elements that nests controls.
</para>
- <para> Standard controls skinning feature provides 2 levels of skinning -
<property>Standard</property> and
- <property>Extended</property> while skinning is based on detecting
browser user agent. If user agent is
- not detected, Advanced level is used. </para>
+ <para> Standard controls skinning feature provides 2 levels of skinning -
<property
+ >Standard</property> and <property>Extended</property> while
skinning is based
+ on detecting browser user agent. If user agent is not detected, Advanced level is
+ used. </para>
<itemizedlist>
<listitem>
<para>
<emphasis>
- <property>Standard</property> level
- </emphasis> provides customization for only basic style properties.
</para>
- <para> To the following browsers <property>Standard</property>
level of skinning is applied: </para>
+ <property>Standard</property> level </emphasis> provides
customization
+ for only basic style properties. </para>
+ <para> To the following browsers <property>Standard</property>
level of skinning
+ is applied: </para>
<itemizedlist>
<listitem>
<para>Internet Explorer 6</para>
@@ -1947,11 +1993,11 @@
<listitem>
<para>
<emphasis>
- <property>Extended</property> level
- </emphasis> extends basic level introducing broader number of style
- properties and is applied to browsers with rich visual styling capability of
- controls </para>
- <para> The following browsers support
<property>Extended</property> level of skinning: </para>
+ <property>Extended</property> level </emphasis> extends basic
level
+ introducing broader number of style properties and is applied to browsers
+ with rich visual styling capability of controls </para>
+ <para> The following browsers support
<property>Extended</property> level of
+ skinning: </para>
<itemizedlist>
<listitem>
<para>Mozilla Firefox</para>
@@ -1961,7 +2007,6 @@
</para>
</listitem>
</itemizedlist>
-
</listitem>
</itemizedlist>
<para> These are the elements that affected by skinning: </para>
@@ -2008,8 +2053,8 @@
</listitem>
<listitem>
<para>
- <property> a (together with a:hover, a:visited
- "pseudo"-elements) </property>
+ <property> a (together with a:hover, a:visited
"pseudo"-elements)
+ </property>
</para>
</listitem>
</itemizedlist>
@@ -2017,20 +2062,19 @@
<itemizedlist>
<listitem>
<para> adding <code>org.richfaces.CONTROL_SKINNING</code> parmeter
to web.xml.
- Values: "enable" and "disable". This way
- implies that skinning style properties are applied to elements by element name
- and attribute type (where applicable). No additional steps required.
- Please find below the table that contains the list of
- elements to which skinning a applicable. </para>
+ Values: "enable" and "disable". This way
implies that
+ skinning style properties are applied to elements by element name and
+ attribute type (where applicable). No additional steps required. Please find
+ below the table that contains the list of elements to which skinning a
+ applicable. </para>
</listitem>
<listitem>
<para> adding <code> org.richfaces.CONTROL_SKINNING_CLASSES
</code> parameter to
- web.xml file. Possible values "enable" and
- "disable". Implementation of this method implies that the
- provision of several style classes for different types of elements. The
- style classes have predefined names. Application developer should manually
- assign classes to controls that needs skinning or assign class to an element
- that contains controls. </para>
+ web.xml file. Possible values "enable" and
"disable".
+ Implementation of this method implies that the provision of several style
+ classes for different types of elements. The style classes have predefined
+ names. Application developer should manually assign classes to controls that
+ needs skinning or assign class to an element that contains controls. </para>
</listitem>
</itemizedlist>
<para> By setting
<code>org.richfaces.CONTROL_SKINNING_CLASSES</code> to
@@ -2050,8 +2094,8 @@
<listitem>
<para> Elements that have class name corresponding to one of the basic
elements
name/type mapped by the following scheme <code>
- rich-<elementName>[-<elementType>] </code> .
- See the example: </para>
+ rich-<elementName>[-<elementType>] </code> . See
the
+ example: </para>
<para>
<emphasis role="bold">Example:</emphasis>
</para>
@@ -2065,11 +2109,10 @@
}
...]]></programlisting>
-
<note>
<title>Note:</title>
- <para> a elements have classes based on "link" and pseudo
- class name, e.g.: rich-link, rich-link-hover, rich-link-visited </para>
+ <para> a elements have classes based on "link" and pseudo
class
+ name, e.g.: rich-link, rich-link-hover, rich-link-visited </para>
</note>
</listitem>
</itemizedlist>
@@ -2346,8 +2389,6 @@
</row>
</thead>
<tbody>
-
-
<row>
<entry>border-width</entry>
<entry>1px</entry>
@@ -2360,31 +2401,21 @@
<entry>border-color</entry>
<entry>panelBorderColor</entry>
</row>
-
<row>
<entry>background-color</entry>
<entry>controlBackgroundColor</entry>
</row>
-
<row>
<entry>background-repeat</entry>
<entry>no-repeat</entry>
</row>
-
<row>
<entry>background-position</entry>
<entry>1px 1px</entry>
</row>
-
-
-
-
</tbody>
</tgroup>
</table>
-
-
-
<table>
<title> Rich Elements Skin Bindings for .rich-field-edit </title>
<tgroup cols="2">
@@ -2395,8 +2426,6 @@
</row>
</thead>
<tbody>
-
-
<row>
<entry>border-width</entry>
<entry>1px</entry>
@@ -2409,20 +2438,13 @@
<entry>border-color</entry>
<entry>panelBorderColor</entry>
</row>
-
-
<row>
<entry>background-color</entry>
<entry>editBackgroundColor</entry>
</row>
-
-
-
</tbody>
</tgroup>
</table>
-
-
<table>
<title> Rich Elements Skin Bindings for .rich-field-error </title>
<tgroup cols="2">
@@ -2433,8 +2455,6 @@
</row>
</thead>
<tbody>
-
-
<row>
<entry>border-width</entry>
<entry>1px</entry>
@@ -2447,39 +2467,25 @@
<entry>border-color</entry>
<entry>panelBorderColor</entry>
</row>
-
-
<row>
<entry>background-color</entry>
<entry>warningBackgroundColor</entry>
</row>
-
<row>
<entry>background-repeat</entry>
<entry>no-repeat</entry>
</row>
-
-
<row>
<entry>background-position</entry>
<entry>center left</entry>
</row>
-
-
<row>
<entry>padding-left</entry>
<entry>7px</entry>
</row>
-
</tbody>
</tgroup>
</table>
-
-
-
-
-
-
<table>
<title> Rich Elements Skin Bindings for .rich-button, .rich-button-disabled,
.rich-button-over </title>
@@ -2491,8 +2497,6 @@
</row>
</thead>
<tbody>
-
-
<row>
<entry>border-width</entry>
<entry>1px</entry>
@@ -2505,25 +2509,18 @@
<entry>border-color</entry>
<entry>panelBorderColor</entry>
</row>
-
-
<row>
<entry>background-color</entry>
<entry>trimColor</entry>
</row>
-
<row>
<entry>padding</entry>
<entry>2px 10px 2px 10px</entry>
</row>
-
-
<row>
<entry>text-align</entry>
<entry>center</entry>
</row>
-
-
<row>
<entry>cursor</entry>
<entry>pointer</entry>
@@ -2536,17 +2533,9 @@
<entry>background-position</entry>
<entry>top left</entry>
</row>
-
-
</tbody>
</tgroup>
</table>
-
-
-
-
-
-
<table>
<title> Rich Elements Skin Bindings for .rich-button-press </title>
<tgroup cols="2">
@@ -2557,21 +2546,13 @@
</row>
</thead>
<tbody>
-
<row>
<entry>background-position</entry>
<entry>bottom left</entry>
</row>
-
</tbody>
</tgroup>
</table>
-
-
-
-
-
-
<table>
<title> Rich Elements Skin Bindings for .rich-container fieldset,
.rich-fieldset </title>
<tgroup cols="2">
@@ -2586,38 +2567,25 @@
<entry>border-color</entry>
<entry>panelBorderColor</entry>
</row>
-
-
<row>
<entry>border-width</entry>
<entry>1px</entry>
</row>
-
-
<row>
<entry>border-style</entry>
<entry>solid</entry>
</row>
-
-
<row>
<entry>padding</entry>
<entry>10px</entry>
</row>
-
-
<row>
<entry>padding</entry>
<entry>10px</entry>
</row>
-
-
</tbody>
</tgroup>
</table>
-
-
-
<table>
<title> Rich Elements Skin Bindings for .rich-legend </title>
<tgroup cols="2">
@@ -2628,7 +2596,6 @@
</row>
</thead>
<tbody>
-
<row>
<entry>font-size</entry>
<entry>generalSizeFont</entry>
@@ -2641,24 +2608,13 @@
<entry>color</entry>
<entry>controlTextColor</entry>
</row>
-
-
<row>
<entry>font-weight</entry>
<entry>bold</entry>
</row>
-
-
-
</tbody>
</tgroup>
</table>
-
-
-
-
-
-
<table>
<title> Rich Elements Skin Bindings for .rich-form </title>
<tgroup cols="2">
@@ -2669,7 +2625,6 @@
</row>
</thead>
<tbody>
-
<row>
<entry>padding</entry>
<entry>0px</entry>
@@ -2678,17 +2633,10 @@
<entry>margin</entry>
<entry>0px</entry>
</row>
-
-
-
-
</tbody>
</tgroup>
</table>
-
</section>
-
-
<section id="AdvancedLevel" role="NotInToc">
<?dbhtml filename="AdvancedLevel.html"?>
<title>Extended level</title>
@@ -2830,16 +2778,14 @@
</table>
<table>
<title> Html Elements Skin Bindings for .rich-button-disabled,
.rich-container
- button[type="button"][disabled],
- .rich-button-button-disabled, .rich-container
- button[type="reset"][disabled],
+ button[type="button"][disabled], .rich-button-button-disabled,
+ .rich-container button[type="reset"][disabled],
.rich-button-reset-disabled, .rich-container
- button[type="submit"][disabled],
- .rich-button-submit-disabled, .rich-container
- input[type="reset"][disabled], .rich-input-reset-disabled,
- .rich-container input[type="submit"][disabled],
- .rich-input-submit-disabled, .rich-container
- input[type="button"][disabled],
+ button[type="submit"][disabled], .rich-button-submit-disabled,
+ .rich-container input[type="reset"][disabled],
+ .rich-input-reset-disabled, .rich-container
+ input[type="submit"][disabled], .rich-input-submit-disabled,
+ .rich-container input[type="button"][disabled],
.rich-input-button-disabled </title>
<tgroup cols="2">
<thead>
@@ -3035,11 +2981,10 @@
</tgroup>
</table>
<note>
- <title>Note:</title>
- <para> Standard skinning level can fail if configuration of
<code>ajaxPortlet</code>
- is as following:
- </para>
- <programlisting role="XML"><![CDATA[...
+ <title>Note:</title>
+ <para> Standard skinning level can fail if configuration of
+ <code>ajaxPortlet</code> is as following: </para>
+ <programlisting role="XML"><![CDATA[...
<portlet>
<portlet-name>ajaxPortlet</portlet-name>
<header-content>
@@ -3049,30 +2994,24 @@
</header-content>
</portlet>
...]]></programlisting>
-</note>
+ </note>
</section>
-
-
</section>
<section>
<title>Client-side script for extended skinning support</title>
-
<para>As it was mentioned earlier in the guide, extended skinning of standard
HTML
controls is applied automatically: the browser type is detected and if a browser
doesn't fully support extended skinning feature, only basic skinning is
applied. </para>
-
- <para> However, if a develop doesn't want to the rich components and
standard
- HTML controls to be skinned automatically and perform the skinnability
- implementation himself, he might encounter with a problem, i.e. standard HTML
- controls in such browsers as Opera and Safari are affected by standard controls
- skinning featured. ( <link
linkend="ScriptsandStylesLoadStrategy">Here</link> you
- can get more details on how to disable skinnability.) </para>
-
+ <para> However, if a develop doesn't want to the rich components and
standard HTML
+ controls to be skinned automatically and perform the skinnability implementation
+ himself, he might encounter with a problem, i.e. standard HTML controls in such
+ browsers as Opera and Safari are affected by standard controls skinning featured. (
+ <link linkend="ScriptsandStylesLoadStrategy">Here</link> you
can get more
+ details on how to disable skinnability.) </para>
<para> In brief, to disable the skinnability mechanism of RichFaces you need to
set the
- "org.richfaces.LoadStyleStrategy" parameter to
- "NONE" in web.xml. </para>
-
+ "org.richfaces.LoadStyleStrategy" parameter to
"NONE" in
+ web.xml. </para>
<programlisting role="XML"><![CDATA[...
<context-param>
<param-name>org.richfaces.LoadStyleStrategy</param-name>
@@ -3080,50 +3019,38 @@
</context-param>
...
]]></programlisting>
-
<para> Additionally, you should include the style sheets that perform skinning
of the
rich component and standard HTML controls. </para>
-
<para> In order to resolve the problem with extended skinning in Opera and
Safari a
client script (skinning.js) is added to the RichFaces library. The script detects
the browser type and enables extended skinning only for those browsers that fully
support it. </para>
-
<para> The script can be activated by inserting this JavaScript code to the
page: </para>
-
<programlisting role="XML"><![CDATA[
<script type="text/javascript">
window.RICH_FACES_EXTENDED_SKINNING_ON = true;
</script>
]]></programlisting>
- <para>
- When NO script loading strategy is used and extended skinning is turned on then
corresponding warning message will appears in the console.
- </para>
-
+ <para> When NO script loading strategy is used and extended skinning is turned
on then
+ corresponding warning message will appears in the console. </para>
<para> You also need to specify <emphasis>
<property>"media"</property>
</emphasis> attribute in the <emphasis role="bold">
<property><link></property>
- </emphasis> tag which includes the "extended_both.xcss"
style
- sheet with "rich-extended-skinning". </para>
+ </emphasis> tag which includes the "extended_both.xcss" style
sheet with
+ "rich-extended-skinning". </para>
<para> This is how you can include the style sheets to the page, in case
automatic
skinnability implementation is disabled. </para>
-
<programlisting role="XML"><![CDATA[
<link
href='/YOUR_PROJECT_NAME/a4j_3_2_2-SNAPSHOTorg/richfaces/renderkit/html/css/basic_both.xcss/DATB/eAF7sqpgb-jyGdIAFrMEaw__.jsf'
type='text/css' rel='stylesheet' class='component' />
<link media='rich-extended-skinning' href='/ YOUR_PROJECT_NAME
/a4j_3_2_2-SNAPSHOTorg/richfaces/renderkit/html/css/extended_both.xcss/DATB/eAF7sqpgb-jyGdIAFrMEaw__.jsf'
type='text/css' rel='stylesheet' class='component' />
<link href='/ YOUR_PROJECT_NAME
/a4j_3_2_2-SNAPSHOT/org/richfaces/skin.xcss/DATB/eAF7sqpgb-jyGdIAFrMEaw__.jsf'
type='text/css' rel='stylesheet' class='component' />
]]></programlisting>
-
<note>
- <para>
- Now necessary to use resources prefix <code>a4j/versionXXX</code>
instead of <code>a4j_versionXXX</code>.
- Base64 encoder changed to use '<code>!</code>' instead
of '<code>.</code>'.
- </para>
+ <para> Now necessary to use resources prefix
<code>a4j/versionXXX</code> instead of
+ <code>a4j_versionXXX</code>. Base64 encoder changed to use
+ '<code>!</code>' instead of
'<code>.</code>'. </para>
</note>
-
-
-
</section>
<section id="XCSSfileformat">
<title>XCSS file format</title>
@@ -3168,7 +3095,8 @@
<property>"name"</property>
</emphasis> attribute of the <emphasis role="bold">
<property><u:style></property>
- </emphasis> tag defines what skin constant is mapped to a CSS property. The
<emphasis>
+ </emphasis> tag defines what skin constant is mapped to a CSS property. The
+ <emphasis>
<property>"value"</property>
</emphasis> attribute of the <emphasis role="bold">
<property><u:style></property>
@@ -3182,32 +3110,21 @@
...
]]></programlisting>
</section>
-
<section id="PlugnSkin" role="new">
<?dbhtml filename="PlugnSkin.html"?>
<title>Plug-n-Skin</title>
-
<para> Plug-n-Skin is a feature that gives a developer an opportunity to easily
create,
customize and plug into a project a custom skin. The skin can be created basing on
parameters of some predefined RichFaces skin. </para>
-
-
<para> The feature also provides an option to unify the appearance of rich
controls with
standard HTML elements. </para>
-
<para> In order to create your own skin using Plug-n-Skin feature, you can
follow these
step by step instructions. </para>
-
-
-
-
<para> First of all, you need to create a template for the new skin. Creation of
the
template can be performed using Maven build and deployment tool. More information on
how to configure Maven for RichFaces <ulink
url="http://wiki.jboss.org/wiki/HowToConfigureMavenForRichFaces"... here
</ulink>
. You can copy and paste these Maven instructions to command line and execute them.
</para>
-
-
<programlisting role="XML"><![CDATA[...
mvn archetype:create
-DarchetypeGroupId=org.richfaces.cdk
@@ -3242,62 +3159,44 @@
</listitem>
</itemizedlist>
<para> After this operation, a folder with the name of your
- <code>"ARTIFACT-ID"</code> appears. The folder
contains a
- template of Maven project. </para>
-
+ <code>"ARTIFACT-ID"</code> appears. The folder
contains a template of
+ Maven project. </para>
<para> Next steps will guide you though creating of the skin itself.
</para>
-
-
-
- <para> In the root folder of Maven project (the one that contains
- "pom.xml" file) you should run the following command in the
- command line: </para>
-
+ <para> In the root folder of Maven project (the one that contains
"pom.xml"
+ file) you should run the following command in the command line: </para>
<programlisting role="XML"><![CDATA[...
mvn cdk:add-skin -Dname=SKIN-NAME -Dpackage=SKIN-PACKAGE
...
]]></programlisting>
-
-
<para>Primary keys for the command:</para>
<itemizedlist>
-
<listitem>
<para>
<code>Dname</code> defines the name of the new skin </para>
</listitem>
-
<listitem>
<para>
<code>Dpackage</code> base package of the skin. By default
"groupId" of the project is used. </para>
</listitem>
</itemizedlist>
-
<para>Additional optional keys for the command:</para>
-
<itemizedlist>
-
<listitem>
-
<para>
<code>DbaseSkin</code> defines the name of the base skin.
</para>
</listitem>
-
<listitem>
<para>
- <code>DcreateExt</code> if set to "true", extended
CSS
- classes are added. For more information, please, see <link
- linkend="StControlsSkinning"> "Standard controls
- skinning" </link>
+ <code>DcreateExt</code> if set to "true", extended
CSS classes are
+ added. For more information, please, see <link
linkend="StControlsSkinning">
+ "Standard controls skinning"
+ </link>
</para>
</listitem>
</itemizedlist>
-
-
<para> As a result of the performed operations the following files and folders
are
created: </para>
-
<itemizedlist>
<listitem>
<para>
@@ -3309,23 +3208,24 @@
<para>
<property>BaseImageTest.java</property> - a test version of a class
that
stores images. Location:
- "\src\test\java\SKIN-PACKAGE\SKIN-NAME\images\" </para>
+ "\src\test\java\SKIN-PACKAGE\SKIN-NAME\images\"
+ </para>
</listitem>
<listitem>
<para>
<property>XCSS files</property> - XCSS files define the new look of
RichFaces components affected by the new skin. Location:
- "\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\" </para>
+ "\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\"
+ </para>
</listitem>
<listitem>
<para>
<property>SKIN-NAME.properties</property> - a XCSS file that contains
properties of the new skin. Location:
- "\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\" </para>
+ "\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\"
+ </para>
<para> The following properties are used to configure the
SKIN-NAME.properties
file: </para>
-
-
<itemizedlist>
<listitem>
<para>
@@ -3345,7 +3245,8 @@
that is used to unify the appearance of RichFaces components and
standard HTML controls. For additional information please read <link
linkend="StControlsSkinning"> "Standard controls
- skinning" </link> chapter. </para>
+ skinning"
+ </link> chapter. </para>
</listitem>
<listitem>
<para>
@@ -3360,7 +3261,8 @@
<para>
<property>SKIN-NAME.xcss</property> - a XCSS file that imports XCSS
files of
the components to be affected by the new skin. Location:
- "src\main\resources\META-INF\skins " </para>
+ "src\main\resources\META-INF\skins "
+ </para>
</listitem>
<listitem>
<para>
@@ -3373,9 +3275,9 @@
<listitem>
<para>
<property>SKIN-NAME-ext.xcss</property> / If the command is executed
with
- the "DcreateExt" key set to "true", the
- configuration SKIN-NAME-ext.xcss file that imports XCSS file defining styles
- for the standard controls will be created. Location:
+ the "DcreateExt" key set to "true", the
configuration
+ SKIN-NAME-ext.xcss file that imports XCSS file defining styles for the
+ standard controls will be created. Location:
"src\main\resources\META-INF\skins ". </para>
</listitem>
<listitem>
@@ -3385,12 +3287,10 @@
"src\main\config\resources ". </para>
</listitem>
</itemizedlist>
-
<para>Now you can start editing the XCSS files located in
- "\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\". New style
- properties can be assigned to the selectors (the selectors listed in the XCSS files)
- in two ways, which are both valid, and it'up to the developer what way to
- choose. </para>
+ "\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\". New style
properties
+ can be assigned to the selectors (the selectors listed in the XCSS files) in two
+ ways, which are both valid, and it'up to the developer what way to choose.
</para>
<itemizedlist>
<listitem>
<para>Applying a standard CSS coding approach, i.e. you can add css
properties
@@ -3398,10 +3298,7 @@
thing, you have to keep in mind is that the selectors must be inside
<code><f:verbatim> <![CDATA[ ...]]>
</f:verbatim></code> tags.</para>
-
-
<para>For example </para>
-
<programlisting role="XML">
<![CDATA[...
.rich-calendar-cell {
@@ -3409,18 +3306,12 @@
}
...
]]></programlisting>
-
-
-
</listitem>
-
-
<listitem>
<para> Using XCSS coding approach, the same way as XCSS files are normally
formed in RichFaces. The XCSS tags have to be placed outside
<code><f:verbatim> <![CDATA[ ...]]>
</f:verbatim></code> tags. </para>
-
<programlisting role="XML">
<![CDATA[...
<u:selector name=".rich-calendar-cell">
@@ -3432,29 +3323,21 @@
</u:selector>
...
]]></programlisting>
-
-
</listitem>
</itemizedlist>
-
-
- <para> </para>
-
+ <para>
+ </para>
<para> Having performed described above steps and edited the XCSS files you can
proceed
to building the new skin and to plugging it into the project. Building the new skin
can be done by executing the given below command in the command line in the root
folder of you skin project (the one that contains pom.xml file). </para>
-
<programlisting role="XML"><![CDATA[...
mvn clean install
...
]]></programlisting>
-
-
<para>In addition Plug-n-Skin has a number of predefined gradients that you can
also use
to make your application look nicer. The given below code snippet shows how a
gradient can be used </para>
-
<programlisting role="XML"><![CDATA[...
<u:selector name=".rich-combobox-item-selected">
<u:style name="border-width" value="1px" />
@@ -3471,25 +3354,19 @@
</u:selector>
...
]]></programlisting>
-
<para> So, as you can see, the <property>background-image</property>
CSS property is
defined with <code> <f:resource
f:key="org.richfaces.renderkit.html.CustomizeableGradient">
</code> that sets the gradient. While the gradient type can be specified in
the
- <property>SKIN-NAME.properties</property> file with
- <property>gradientType</property> property. The
<property>gradientType</property>
+ <property>SKIN-NAME.properties</property> file with <property
+ >gradientType</property> property. The
<property>gradientType</property>
property can be set to one of the possible values glass, plastic, plain. The
- gradient in it's turn can be can be adjusted using baseColor,
- gradientColor, gradientHeight, valign attributes. Their usage is shown in the
- snippet above. </para>
-
-
-
+ gradient in it's turn can be can be adjusted using baseColor,
gradientColor,
+ gradientHeight, valign attributes. Their usage is shown in the snippet above.
</para>
<para> Now, you can use your newly-created and customized skin in your project
by adding
your new skin parameters to web.xml file and placing the jar file with your skin (
- the jar file is located in "target" folder of your skin project)
- to "\WebContent\WEB-INF\lib\". </para>
-
+ the jar file is located in "target" folder of your skin project)
to
+ "\WebContent\WEB-INF\lib\". </para>
<programlisting role="XML"><![CDATA[...
<context-param>
<param-name>org.ajax4jsf.SKIN</param-name>
@@ -3497,25 +3374,19 @@
</context-param>
...
]]></programlisting>
-
-
<section>
<sectioninfo>
<keywordset>
<keyword>Plug-n-Skin</keyword>
</keywordset>
</sectioninfo>
-
<title>Details of Usage</title>
-
<para>This section will cover some practical aspects of Plug-n-Skin
implementation.
- It's assumed that you have read the section of the guide that tells how
- the new skin using Plug-n-Skin prototype can be created. </para>
+ It's assumed that you have read the section of the guide that tells how
the
+ new skin using Plug-n-Skin prototype can be created. </para>
<para>Above all, we need to create a new skin, in order to do that we just have
to
follow the steps described in the previous section.</para>
-
<para>This command will be used to create a template of the new skin project.
</para>
-
<programlisting role="XML"><![CDATA[
mvn archetype:create
-DarchetypeGroupId=org.richfaces.cdk
@@ -3525,26 +3396,19 @@
-DgroupId=GROUPID
-Dversion=1.0.-SNAPSHOT
]]></programlisting>
- <para> Now you can browse the "P-n-S" folder to view what
files
- and folders were created there. </para>
-
+ <para> Now you can browse the "P-n-S" folder to view what
files and
+ folders were created there. </para>
<para> Next, we will use Maven to add all needed files to the skin project.
This
will done by the following command: </para>
-
<programlisting role="XML"><![CDATA[
mvn cdk:add-skin -DbaseSkin=blueSky -DcreateExt=true -Dname=PlugnSkinDemo
-Dpackage=SKINPACKAGE
]]></programlisting>
-
- <para> As you remember from the previous section "-DbaseSkin"
key
- defines what RichFaces built-in skin to be used as a base one,
- "-DcreateExt=true" determines that the new skin will come with
- XCSS files that unify the look of the rich components with standard HTML
- controls. </para>
-
-
+ <para> As you remember from the previous section "-DbaseSkin"
key defines
+ what RichFaces built-in skin to be used as a base one,
+ "-DcreateExt=true" determines that the new skin will come with
XCSS
+ files that unify the look of the rich components with standard HTML controls.
</para>
<para> So, now the files and folder with all needed resources are created and
redefining/editing the new skin can be started. </para>
-
<para> Now we can start editing XCSS files of the rich components. In order to
see
how the Plug-n-Skin feature works we will change some style attributes of
<emphasis role="bold">
@@ -3563,31 +3427,23 @@
<listitem>
<para>Recolor a standard HTML submit button;</para>
</listitem>
-
</itemizedlist>
-
-
<para>In oder to edit the style properties of <emphasis
role="bold">
<property><rich:calendar></property>
- </emphasis> you need to open the "calendar.xcss" file
located
- in "P-n-S\src\main\resources\skinpackage\plugnskindemo\css\".
- Once, you have opened the file, please find ".rich-calendar-today"
selector and
- amend it as follows: <code>background-color: #075ad1;</code>. The
current day's
+ </emphasis> you need to open the "calendar.xcss" file
located in
+ "P-n-S\src\main\resources\skinpackage\plugnskindemo\css\". Once,
you
+ have opened the file, please find ".rich-calendar-today" selector and
amend it
+ as follows: <code>background-color: #075ad1;</code>. The current
day's
background color can be considered recolored.</para>
-
<para>Now we will see how font style of a standard HTML submit button can be
changed. Please, open "extended.xcss" file located in
- "P-n-S\src\main\resources\skinpackage\plugnskindemo\css\" and
- put in <code>font-weight: bold;</code> inside the curly braces of these
coma
+ "P-n-S\src\main\resources\skinpackage\plugnskindemo\css\" and put
in
+ <code>font-weight: bold;</code> inside the curly braces of these coma
separated selectors <code>button[type="button"],
- button[type="reset"],
- button[type="submit"],
- input[type="reset"],
- input[type="submit"],
- input[type="button"]</code>. So, the CSS code should look
- like this. </para>
-
-
+ button[type="reset"], button[type="submit"],
+ input[type="reset"], input[type="submit"],
+ input[type="button"]</code>. So, the CSS code should look
like
+ this. </para>
<programlisting role="XML"><![CDATA[
button[type="button"], button[type="reset"],
button[type="submit"], input[type="reset"],
input[type="submit"], input[type="button"] {
font-weight: bold;
@@ -3596,41 +3452,32 @@
<para>All the changes that were planned to be preformed are done and now you
can
proceed to building the new PlugnSkinDemo skin and import it into the project.
As you read in the previous section, the skin should be built in the
- "P-n-S" folder of the skin project be executing <code>mvn
- clean install</code> command. This procedure results in creating a
- "target" folder that contains a .jar file with a compiled new
- skin, it our case the file is named "P-n-S-1.0.-SNAPSHOT.jar".
- The next step is to import the new PlugnSkinDemo skin into the
project.</para>
+ "P-n-S" folder of the skin project be executing <code>mvn
clean
+ install</code> command. This procedure results in creating a
+ "target" folder that contains a .jar file with a compiled new
skin, it
+ our case the file is named "P-n-S-1.0.-SNAPSHOT.jar". The next
step is
+ to import the new PlugnSkinDemo skin into the project.</para>
<para>What you need to do, in order to have the new skin imported to the
project is
to</para>
<itemizedlist>
-
<listitem>
<para>Copy the "P-n-S-1.0.-SNAPSHOT.jar" file to the
"\WebContent\WEB-INF\lib\" folder.</para>
</listitem>
<listitem>
- <para>Add the new skin's name to the "web.xml"
- file. It is done like this</para>
-
+ <para>Add the new skin's name to the "web.xml"
file. It is
+ done like this</para>
<programlisting role="XML"><![CDATA[
<context-param>
<param-name>org.ajax4jsf.SKIN</param-name>
<param-value>PlugnSkinDemo</param-value>
</context-param>
]]></programlisting>
-
-
-
</listitem>
</itemizedlist>
-
-
<para> Please, do not forget that standard controls skinning has to be enabled
in
- the "web.xml" file, which can be done by adding the following
- code to the "web.xml" file: </para>
-
-
+ the "web.xml" file, which can be done by adding the following code
to
+ the "web.xml" file: </para>
<programlisting role="XML"><![CDATA[
<context-param>
<param-name>org.richfaces.CONTROL_SKINNING</param-name>
@@ -3638,9 +3485,6 @@
</context-param>
]]></programlisting>
<para>The result of both action is displayed on the figure below.</para>
-
-
-
<figure>
<title>Plug-n-Skin feature in action. </title>
<mediaobject>
@@ -3651,7 +3495,6 @@
</figure>
</section>
</section>
-
</section>
<section id="statemanagerapi">
<title>State Manager API</title>
@@ -3661,8 +3504,8 @@
component. But there is no switch mechanism between some logical states of the same
view. For example in <property>Login/Register dialog</property> an
existing user signs
in with his user name and password, but if a new user registers an additional field
- "Confirm" is displayed, buttons labels and methods are changed when
- the user clicks "To register" link: </para>
+ "Confirm" is displayed, buttons labels and methods are changed when
the user
+ clicks "To register" link: </para>
<figure>
<title> Login Dialog </title>
<mediaobject>
@@ -3706,8 +3549,8 @@
steps: </para>
<itemizedlist>
<listitem>
- <para> Register State Manager EL resolver and navigation handler in the
- <property>faces-config.xml</property>: </para>
+ <para> Register State Manager EL resolver and navigation handler in the
<property
+ >faces-config.xml</property>: </para>
<programlisting role="XML"><![CDATA[...
<application>
<navigation-handler>org.richfaces.ui.application.StateNavigationHandler</navigation-handler>
@@ -3716,8 +3559,8 @@
...]]></programlisting>
</listitem>
<listitem>
- <para> Register an additional application factory in the
- <property>faces-config.xml</property>: </para>
+ <para> Register an additional application factory in the <property
+ >faces-config.xml</property>: </para>
<programlisting role="XML"><![CDATA[...
<factory>
<application-factory>org.richfaces.ui.application.StateApplicationFactory</application-factory>
@@ -3743,8 +3586,8 @@
<managed-bean-scope>none</managed-bean-scope>
</managed-bean>
...]]></programlisting>
- <para> One bean ("config") defines and stores states as it
is
- shown in the following example: </para>
+ <para> One bean ("config") defines and stores states as it is
shown in the
+ following example: </para>
<programlisting role="JAVA"><![CDATA[...
public class Config {
@@ -3815,9 +3658,9 @@
}
...]]></programlisting>
<para> The other bean ("state") with the type
- <code>org.richfaces.ui.model.States</code> has the
- "states" managed property that is bound to the
- "config" bean which defines states. </para>
+ <code>org.richfaces.ui.model.States</code> has the
"states"
+ managed property that is bound to the "config" bean which defines
+ states. </para>
</listitem>
<listitem>
<para> Use <property>state</property> bindings on the page. See the
following