Author: cluts Date: 2008-09-01 03:17:16 -0400 (Mon, 01 Sep 2008) New Revision: 10258 Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml Log: RF-4069 - added note box with necessary information Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2008-09-01 07:16:00 UTC (rev 10257) +++ trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2008-09-01 07:17:16 UTC (rev 10258) @@ -15,209 +15,152 @@ <section id="introToBasics"> <?dbhtml filename="introToBasics.html"?> <title>Introduction</title> - <para> - The framework is implemented as a component library which - adds Ajax capability into existing pages, so you don&apos;t - need to write any JavaScript code or to replace existing - components with new Ajax widgets. - <property>RichFaces</property> - enables page-wide Ajax support instead of the traditional - component-wide support. Hence, you can define the event on - the page that invokes an Ajax request and the areas of the - page that should be synchronized with the JSF Component Tree - after the Ajax request changes the data on the server - according to the events fired on the client. - </para> + <para> The framework is implemented as a component library which adds Ajax capability into + existing pages, so you don&apos;t need to write any JavaScript code or to replace + existing components with new Ajax widgets. <property>RichFaces</property> enables + page-wide Ajax support instead of the traditional component-wide support. Hence, you can + define the event on the page that invokes an Ajax request and the areas of the page that + should be synchronized with the JSF Component Tree after the Ajax request changes the + data on the server according to the events fired on the client. </para> <para>Next Figure shows how it works:</para> <figure> <title>Request Processing flow</title> <mediaobject> <imageobject> - <imagedata fileref="images/newpic1.png" - scalefit="1" /> + <imagedata fileref="images/newpic1.png" scalefit="1"/> </imageobject> </mediaobject> </figure> <para> - <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&apos;t change from a &quot;regular&quot; JSF page - and you don&apos;t need to write any JavaScript or - XMLHTTPRequest objects by hands, everything is done - automatically. - </para> + <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&apos;t change from a + &quot;regular&quot; JSF page and you don&apos;t need to write any JavaScript + or XMLHTTPRequest objects by hands, everything is done automatically. </para> </section> <section id="RichFacesArchitectureOverview"> <?dbhtml filename="RichFacesArchitectureOverview.html"?> <title>RichFaces Architecture Overview</title> - <para> - Next figure lists several important elements of the - <property>RichFaces</property> - framework - </para> + <para> Next figure lists several important elements of the <property>RichFaces</property> + framework </para> <figure> <title>Core Ajax component structure</title> <mediaobject> <imageobject> - <imagedata fileref="images/newpic2.png" /> + <imagedata fileref="images/newpic2.png"/> </imageobject> </mediaobject> </figure> <formalpara> <title>Ajax Filter.</title> - <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"> - &quot;Filter configuration&quot; - </link> - section. The sequence diagram on Figure 3 shows the - difference in processing of a &quot;regular&quot; JSF - request and an Ajax request. - </para> + <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"> &quot;Filter configuration&quot; </link> + section. The sequence diagram on Figure 3 shows the difference in processing of a + &quot;regular&quot; 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 &quot;size&quot; 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> + <para> In the first case the whole JSF tree will be encoded, in the second one option it + depends on the &quot;size&quot; 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" /> + <imagedata fileref="images/newpic3.png" scalefit="1"/> </imageobject> </mediaobject> </figure> - <para> - In both cases, the information about required static or - dynamic resources that your application requests is - registered in the ResourseBuilder class. - </para> - <para> - When a request for a resource comes (Figure 4), the - RichFaces filter checks the Resource Cache for this resource - and if it is there, the resource is sent to the client. - Otherwise, the filter searches for the resource among those - that are registered by the ResourceBuilder. If the resource - is registered, the RichFaces filter will send a request to - the ResourceBuilder to create (deliver) the resource. - </para> - <para> - Next Figure shows the ways of resource request processing. - </para> + <para> In both cases, the information about required static or dynamic resources that your + application requests is registered in the ResourseBuilder class. </para> + <para> When a request for a resource comes (Figure 4), the RichFaces filter checks the + Resource Cache for this resource and if it is there, the resource is sent to the client. + Otherwise, the filter searches for the resource among those that are registered by the + ResourceBuilder. If the resource is registered, the RichFaces filter will send a request + to the ResourceBuilder to create (deliver) the resource. </para> + <para> Next Figure shows the ways of resource request processing. </para> <figure> <title>Resource request sequence diagram</title> <mediaobject> <imageobject> - <imagedata fileref="images/newpic4.png" - scalefit="1" /> + <imagedata fileref="images/newpic4.png" scalefit="1"/> </imageobject> </mediaobject> </figure> <formalpara> <title>AJAX Action Components</title> - <para> - There are Ajax Action Components: <emphasis role="bold"><property>&lt;a4j:commandButton&gt;</property></emphasis>, - <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis>, <emphasis role="bold"><property>&lt;a4j:poll&gt;</property></emphasis> and<emphasis role="bold"><property>&lt;a4j:support&gt;</property></emphasis> and etc. You - can use them to send Ajax requests from the client side. + <para> There are Ajax Action Components: <emphasis role="bold"> + <property>&lt;a4j:commandButton&gt;</property> + </emphasis>, <emphasis role="bold"> + <property>&lt;a4j:commandLink&gt;</property> + </emphasis>, <emphasis role="bold"> + <property>&lt;a4j:poll&gt;</property> + </emphasis> and<emphasis role="bold"> + <property>&lt;a4j:support&gt;</property> + </emphasis> and etc. You can use them to send Ajax requests from the client side. </para> </formalpara> <formalpara> <title>AJAX Containers</title> - <para> - AjaxContainer is an interface that describes an area on - your JSF page that should be decoded during an Ajax - request. <code>AjaxViewRoot</code> and <code>AjaxRegion</code> are implementations - of this interface. - </para> + <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> </formalpara> <formalpara> <title>JavaScript Engine</title> <para> - <property>RichFaces</property> - JavaScript Engine runs on the client-side. It knows how - to update different areas on your JSF page based on the - information from the Ajax response. Do not use this - JavaScript code directly, as it is available - automatically. - </para> + <property>RichFaces</property> JavaScript Engine runs on the client-side. It knows + how to update different areas on your JSF page based on the information from the + Ajax response. Do not use this JavaScript code directly, as it is available + automatically. </para> </formalpara> </section> <section id="LimitationsAndRules"> <?dbhtml filename="LimitationAndRules.html"?> <title>Limitations and Rules</title> - <para> - In order to create RichFaces applications properly, keep the - following points in mind: - </para> + <para> In order to create RichFaces applications properly, keep the following points in + mind: </para> <itemizedlist> <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&apos;d like - to append any code to a page, put in a placeholder - for it (any empty element). For the same reason, - it&apos;s recommended to place messages in the - <emphasis role="bold"> + <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&apos;d like to append any code to a page, put + in a placeholder for it (any empty element). For the same reason, it&apos;s + recommended to place messages in the <emphasis role="bold"> <property>&quot;AjaxOutput&quot;</property> - </emphasis> - component (as no messages is also a message). - </para> + </emphasis> component (as no messages is also a message). </para> </listitem> <listitem> - <para> - Don&apos;t use - <emphasis role="bold"> + <para> Don&apos;t use <emphasis role="bold"> <property>&lt;f:verbatim&gt;</property> - </emphasis> - for self-rendered containers, since this component - is transient and not saved in the tree. - </para> + </emphasis> for self-rendered containers, since this component is transient and + not saved in the tree. </para> </listitem> <listitem> - <para> - Ajax requests are made by XMLHTTPRequest functions - in XML format, but this XML bypasses most - validations and the corrections that might be made - in a browser. Thus, create only a strict - standards-compliant code for HTML and XHTML, without - skipping any required elements or attributes. Any - necessary XML corrections are automatically made by - the XML filter on the server, but lot&apos;s of - unexpected effects can be produced by an incorrect - HTML code. + <para> Ajax requests are made by XMLHTTPRequest functions in XML format, but this + XML bypasses most validations and the corrections that might be made in a + browser. Thus, create only a strict standards-compliant code for HTML and XHTML, + without skipping any required elements or attributes. Any necessary XML + corrections are automatically made by the XML filter on the server, but + lot&apos;s of unexpected effects can be produced by an incorrect HTML code. </para> </listitem> <listitem> - <para> - The <property>RichFaces</property> ViewHandler puts itself in front of the Facelets ViewHandlers chain. - </para> + <para> The <property>RichFaces</property> ViewHandler puts itself in front of the + Facelets ViewHandlers chain. </para> </listitem> <listitem> <para> - <property>RichFaces</property> components uses their own renderers. On the Render Response Phase <property>RichFaces</property> - framework makes a traversal of the component tree, calls its own renderer and put the result into the Faces Response. - </para> + <property>RichFaces</property> components uses their own renderers. On the + Render Response Phase <property>RichFaces</property> framework makes a traversal + of the component tree, calls its own renderer and put the result into the Faces + Response. </para> </listitem> </itemizedlist> </section> @@ -228,49 +171,29 @@ <section id="Re-Rendering"> <?dbhtml filename="Re-Rendering.html"?> <title>Re-Rendering</title> - <para> - Ajax attributes are common for Ajax components such as - <emphasis role="bold"> + <para> Ajax attributes are common for Ajax components such as <emphasis role="bold"> <property>&lt;a4j:support&gt;</property> - </emphasis> - , - <emphasis role="bold"> + </emphasis> , <emphasis role="bold"> <property>&lt;a4j:commandButton&gt;</property> - </emphasis> - , - <emphasis role="bold"> + </emphasis> , <emphasis role="bold"> <property>&lt;a4j:jsFunction&gt;</property> - </emphasis> - , - <emphasis role="bold"> + </emphasis> , <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> - </emphasis> - , - <emphasis role="bold"> + </emphasis> , <emphasis role="bold"> <property>&lt;a4j:push&gt;</property> - </emphasis> - and so on. Also, most RichFaces components with built-in - Ajax support have these attributes for a similar - purpose. Ajax components attributes help RichFaces to - expose its features. Most of the attributes have default - values. Thus, you can start working with RichFaces - without knowing the usage of these attribute. However, - their usage allows to tune the required Ajax behavior - very smoothly. - </para> + </emphasis> and so on. Also, most RichFaces components with built-in Ajax support + have these attributes for a similar purpose. Ajax components attributes help + RichFaces to expose its features. Most of the attributes have default values. Thus, + you can start working with RichFaces without knowing the usage of these attribute. + However, their usage allows to tune the required Ajax behavior very smoothly. </para> <para> <emphasis> <property>&quot;reRender&quot;</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> + </emphasis> is a key attribute. The attribute allows to point to area(s) on a page + that should be updated as a response on Ajax interaction. The value of the <emphasis> <property>&quot;reRender&quot;</property> - </emphasis> - attribute is an id of the JSF component or an id list. - </para> + </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[... @@ -282,52 +205,31 @@ ... ]]></programlisting> - <para> - The value of - <emphasis> + <para> The value of <emphasis> <property>&quot;reRender&quot;</property> - </emphasis> - attribute of the - <emphasis role="bold"> + </emphasis> attribute of the <emphasis role="bold"> <property>&lt;a4j:commandButton&gt;</property> - </emphasis> - tag defines which part(s) of your page is (are) to be - updated. In this case, the only part of the page to - update is the - <emphasis role="bold"> + </emphasis> tag defines which part(s) of your page is (are) to be updated. In this + case, the only part of the page to update is the <emphasis role="bold"> <property>&lt;h:panelGrid&gt;</property> - </emphasis> - tag because its ID value matches to the value of - <emphasis> + </emphasis> tag because its ID value matches to the value of <emphasis> <property>&quot;reRender&quot;</property> - </emphasis> - attribute. As you see, it&apos;s not difficult to update - multiple elements on the page, only list their IDs as - the value of - <emphasis> + </emphasis> attribute. As you see, it&apos;s not difficult to update multiple + elements on the page, only list their IDs as the value of <emphasis> <property>&quot;reRender&quot;</property> - </emphasis> - . - </para> + </emphasis> . </para> <para> <emphasis> <property>&quot;reRender&quot;</property> - </emphasis> - uses - <ulink - url="http://java.sun.com/javaee/javaserverfaces/1.2_MR1/docs/api/jav... - UIComponent.findComponent() algorithm - </ulink> - (with some additional exceptions) to find the component - in the component tree. As can you see, the algorithm - presumes several steps. Each other step is used if the - previous step is not successful. Therefore, you can - define how fast the component is found mentioning it - more precisely. The following example shows the - difference in approaches (both buttons will work - successfully): - </para> + </emphasis> uses <ulink + url="http://java.sun.com/javaee/javaserverfaces/1.2_MR1/docs/api/jav... + > UIComponent.findComponent() algorithm </ulink> (with some additional + exceptions) to find the component in the component tree. As can you see, the + algorithm presumes several steps. Each other step is used if the previous step is + not successful. Therefore, you can define how fast the component is found mentioning + it more precisely. The following example shows the difference in approaches (both + buttons will work successfully): </para> <programlisting role="XML"><![CDATA[... <h:form id="form1"> @@ -349,64 +251,39 @@ ... ]]></programlisting> - <para> - It&apos;s also possible to use JSF EL expression as a - value of the reRender attribute. It might be a property - of types Set, Collection, Array or simple String. The EL - for reRender is resolved right before the Render - Response phase. Hence, you can calculate what should be - re-rendered on any previous phase during the Ajax - request processing. - </para> + <para> It&apos;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> + <para> Most common problem with using reRender is pointing it to the component that has + a <emphasis> <property>&quot;rendered&quot;</property> - </emphasis> - attribute. Note, that JSF does not mark the place in the - browser DOM where the outcome of the component should be - placed in case the - <emphasis> + </emphasis> attribute. Note, that JSF does not mark the place in the browser DOM + where the outcome of the component should be placed in case the <emphasis> <property>&quot;rendered&quot;</property> - </emphasis> - condition returns false. Therefore, after the component - becomes rendered during the Ajax request, RichFaces - delivers the rendered code to the client, but does not - update a page, because the place for update is unknown. - You need to point to one of the parent components that - has no - <emphasis> + </emphasis> condition returns false. Therefore, after the component becomes rendered + during the Ajax request, RichFaces delivers the rendered code to the client, but + does not update a page, because the place for update is unknown. You need to point + to one of the parent components that has no <emphasis> <property>&quot;rendered&quot;</property> - </emphasis> - attribute. As an alternative, you can wrap the component - with - <emphasis role="bold"> + </emphasis> attribute. As an alternative, you can wrap the component with <emphasis + role="bold"> <property>&lt;a4j:outputPanel&gt;</property> </emphasis> - <code>layout=&quot;none&quot;</code> - . - </para> + <code>layout=&quot;none&quot;</code> . </para> <para> <emphasis> <property>&quot;ajaxRendered&quot;</property> - </emphasis> - attribute of the - <emphasis role="bold"> + </emphasis> attribute of the <emphasis role="bold"> <property>&lt;a4j:outputPanel&gt;</property> - </emphasis> - set to - &quot;true&quot; - 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 &quot;true&quot; 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 /> @@ -417,24 +294,17 @@ <para> <emphasis> <property>&quot;limitToList&quot;</property> - </emphasis> - attribute allows to dismiss the behavior of the - <emphasis role="bold"> + </emphasis> attribute allows to dismiss the behavior of the <emphasis role="bold"> <property>&lt;a4j:outputPanel&gt;</property> </emphasis> <emphasis> <property>&quot;ajaxRendered&quot;</property> - </emphasis> - attribute. - <code>limitToList = &quot;false&quot;</code> - means to update only the area(s) that mentioned in the - <emphasis> + </emphasis> attribute. <code>limitToList = &quot;false&quot;</code> means to + update only the area(s) that mentioned in the <emphasis> <property>&quot;reRender&quot;</property> - </emphasis> - attribute explicitly. All output panels with - <code>ajaxRendered=&quot;true&quot;</code> - is ignored. An example is placed below: - </para> + </emphasis> attribute explicitly. All output panels with + <code>ajaxRendered=&quot;true&quot;</code> is ignored. An example is + placed below: </para> <programlisting role="XML"><![CDATA[... <h:form> @@ -454,37 +324,22 @@ <para> <emphasis> <property>&quot;eventsQueue&quot;</property> - </emphasis> - attribute defines the name of the queue that will be - used to order upcoming Ajax requests. By default, - RichFaces does not queue Ajax requests. If events are - produced simultaneously, they will come to the server - simultaneously. JSF implementations (especially, the - very first ones) does not guaranty that the request that - comes first will be served or passed into the JSF - lifecycle first. The order how the server side data will - be modified in case of simultaneous request might be - unpredictable. Usage of eventsQueue attribute allows to - avoid possible mess. Define the queue name explicitly, - if you expect intensive Ajax traffic in your - application. - </para> - <para> - The next request posted in the same queue will wait - until the previos one is not processed and Ajax Response - is returned back if the - <emphasis> + </emphasis> attribute defines the name of the queue that will be used to order + upcoming Ajax requests. By default, RichFaces does not queue Ajax requests. If + events are produced simultaneously, they will come to the server simultaneously. JSF + implementations (especially, the very first ones) does not guaranty that the request + that comes first will be served or passed into the JSF lifecycle first. The order + how the server side data will be modified in case of simultaneous request might be + unpredictable. Usage of eventsQueue attribute allows to avoid possible mess. Define + the queue name explicitly, if you expect intensive Ajax traffic in your application. </para> + <para> The next request posted in the same queue will wait until the previos one is not + processed and Ajax Response is returned back if the <emphasis> <property>&quot;eventsQueue&quot;</property> - </emphasis> - attribute is defined. In addition, RichFaces starts to - remove from the queue &quot;similar&quot; requests. - &quot;Similar'&quot;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> + </emphasis> attribute is defined. In addition, RichFaces starts to remove from the + queue &quot;similar&quot; requests. &quot;Similar'&quot;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}"> @@ -496,109 +351,65 @@ <para> <emphasis> <property>&quot;requestDelay&quot;</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 &quot;similar&quot; - request is in a queue already . - </para> + </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 &quot;similar&quot; request is + in a queue already . </para> <para> <emphasis> <property>&quot;ignoreDupResponses&quot;</property> - </emphasis> - attribute orders to ignore the Ajax Response produced by - the request if the newest &quot;similar&quot; request is - in a queue already. - <code>ignoreDupResponses&quot;=&quot;true&quot;</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> + </emphasis> attribute orders to ignore the Ajax Response produced by the request if + the newest &quot;similar&quot; request is in a queue already. + <code>ignoreDupResponses&quot;=&quot;true&quot;</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>&quot;eventsQueue&quot;</property> - </emphasis> - along with - <emphasis> + </emphasis> along with <emphasis> <property>&quot;requestDelay&quot;</property> - </emphasis> - allows to protect against unnecessary traffic flood and - synchronizes Ajax requests order. If you have several - sources of Ajax requests, you can define the same queue - name there. This might be very helpful if you have Ajax - components that invoke request asynchronously from the - ones produced by events from users. For example, - <emphasis role="bold"> + </emphasis> allows to protect against unnecessary traffic flood and synchronizes + Ajax requests order. If you have several sources of Ajax requests, you can define + the same queue name there. This might be very helpful if you have Ajax components + that invoke request asynchronously from the ones produced by events from users. For + example, <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> - </emphasis> - or - <emphasis role="bold"> + </emphasis> or <emphasis role="bold"> <property>&lt;a4j:push&gt;</property> - </emphasis> - . In case the requests from such components modify the - same data, the synchronization might be very helpful. - </para> + </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&amp;op=viewtopic&... - RichFaces Users Forum - </ulink> - . - </para> + <para> More information can be found on the <ulink + url="http://jboss.com/index.html?module=bb&amp;op=viewtopic&... + > RichFaces Users Forum </ulink> . </para> <para> <emphasis> <property>&quot;timeout&quot;</property> - </emphasis> - attribute is used for setting response waiting time on a - particular request. If a response is not received during - this time, the request is aborted. + </emphasis> attribute is used for setting response waiting time on a particular + request. If a response is not received during this time, the request is aborted. </para> </section> <section id="DataProcessingOptions"> <?dbhtml filename="DataProcessingOptions.html"?> <title>Data Processing Options</title> - <para> - RichFaces uses form based approach for Ajax request - sending. This means each time, when you click an Ajax - button or - <emphasis role="bold"> + <para> RichFaces uses form based approach for Ajax request sending. This means each + time, when you click an Ajax button or <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> - </emphasis> - produces an asynchronous request, the data from the - closest JSF form is submitted with the XMLHTTPRequest - object. The form data contains the values from the form - input element and auxiliary information such as state - saving data. - </para> - <para> - When - <emphasis> + </emphasis> produces an asynchronous request, the data from the closest JSF form is + submitted with the XMLHTTPRequest object. The form data contains the values from the + form input element and auxiliary information such as state saving data. </para> + <para> When <emphasis> <property>&quot;ajaxSingle&quot;</property> - </emphasis> - attribute value is - &quot;true&quot; - , it orders to include only a value of the current - component (along with - <emphasis role="bold"> + </emphasis> attribute value is &quot;true&quot; , it orders to include only + a value of the current component (along with <emphasis role="bold"> <property>&lt;f:param&gt;</property> - </emphasis> - or - <emphasis role="bold"> + </emphasis> or <emphasis role="bold"> <property>&lt;a4j:action&gt;</property> - </emphasis> - param values if any) to the request map. In case of - <emphasis role="bold"> + </emphasis> param values if any) to the request map. In case of <emphasis + role="bold"> <property>&lt;a4j:support&gt;</property> - </emphasis> - , it is a value of the parent component. An example is - placed below: - </para> + </emphasis> , it is a value of the parent component. An example is placed below: </para> <programlisting role="XML"><![CDATA[... <h:form> @@ -609,207 +420,125 @@ </form> ... ]]></programlisting> - <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=&quot;true&quot;</code> - usage. - </para> - <para> - Note, that - <code>ajaxSingle=&quot;true&quot;</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> 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=&quot;true&quot;</code> usage. </para> + <para> Note, that <code>ajaxSingle=&quot;true&quot;</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>&lt;h:selectOneMenu&gt;</property> - </emphasis> - do recognize the missing data in the request map value - as a null value and try to pass the validation process - with a failed result. Thus, use - <emphasis role="bold"> + </emphasis> do recognize the missing data in the request map value as a null value + and try to pass the validation process with a failed result. Thus, use <emphasis + role="bold"> <property>&lt;a4j:region&gt;</property> - </emphasis> - to limit a part of the component tree that will be - processed on the server side when it is required. - </para> + </emphasis> to limit a part of the component tree that will be processed on the + server side when it is required. </para> <para> <emphasis> <property>&quot;immediate&quot;</property> - </emphasis> - attribute has the same purpose as any other non-JSF - component. The default - <emphasis> + </emphasis> attribute has the same purpose as any other non-JSF component. The + default <emphasis> <property>&quot;ActionListener&quot;</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=&quot;true&quot;</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"> + </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=&quot;true&quot;</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>&lt;h:dataTable&gt;</property> - </emphasis> - like components where using - <emphasis role="bold"> + </emphasis> like components where using <emphasis role="bold"> <property>&lt;a4j:region&gt;</property> - </emphasis> - is impossible due to the - <emphasis role="bold"> + </emphasis> is impossible due to the <emphasis role="bold"> <property>&lt;h:dataTable&gt;</property> - </emphasis> - component architecture. - </para> + </emphasis> component architecture. </para> <para> <emphasis> <property>&quot;bypassUpdates&quot;</property> - </emphasis> - attribute allows to bypass the Update Model phase. It - might be useful if you need to check your input against - the available validator, but not to update the model - with those data. Note, that an action will be invoked at - the end of the Validation phase only if the Validation - phase is passed successfully. The listeners of the - Application phase will not be invoked in any case. - </para> + </emphasis> attribute allows to bypass the Update Model phase. It might be useful if + you need to check your input against the available validator, but not to update the + model with those data. Note, that an action will be invoked at the end of the + Validation phase only if the Validation phase is passed successfully. The listeners + of the Application phase will not be invoked in any case. </para> </section> <section id="ActionandNavigation"> <?dbhtml filename="ActionandNavigation.html"?> <title>Action and Navigation</title> - <para> - Ajax component is similar to any other non-Ajax JSF - component like - <emphasis role="bold"> + <para> Ajax component is similar to any other non-Ajax JSF component like <emphasis + role="bold"> <property>&lt;h:commandButton&gt;</property> - </emphasis> - . It allows to submit the form. You can use - <emphasis> + </emphasis> . It allows to submit the form. You can use <emphasis> <property>&quot;action&quot;</property> - </emphasis> - and - <emphasis> + </emphasis> and <emphasis> <property>&quot;actionListener&quot;</property> - </emphasis> - attributes to invoke the action method and define the - action event. - </para> + </emphasis> attributes to invoke the action method and define the action event. </para> <para> <emphasis> <property>&quot;action&quot;</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>&quot;Ajax request generates Non-Ajax - Response&quot;</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>&quot;Ajax request generates Non-Ajax - Response&quot;</code> mode. This mode might be helpful in two major - cases: - </para> + </emphasis> method must return null if you want to have an Ajax Response with a + partual page update. This is regular mode called <code>&quot;Ajax request + generates Non-Ajax Response&quot;</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>&quot;Ajax request generates Non-Ajax Response&quot;</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>&lt;a4j:include&gt;</property> - </emphasis> - component. This is a typical scenario for Wizard - like behavior. The new content is rendered - inside the - <emphasis role="bold"> + </emphasis> component. This is a typical scenario for Wizard like behavior. + The new content is rendered inside the <emphasis role="bold"> <property>&lt;a4j:include&gt;</property> - </emphasis> - area. The content is taken from the navigation - rule of the faces configuration file (usually, - the faces-config.xml). Note, that the content of - the "wizard" is not isolated from the rest of - the page. The included page should not have own - <emphasis role="bold"> + </emphasis> area. The content is taken from the navigation rule of the faces + configuration file (usually, the faces-config.xml). Note, that the content + of the "wizard" is not isolated from the rest of the page. The included page + should not have own <emphasis role="bold"> <property>&lt;f:view&gt;</property> - </emphasis> - (it does not matter if you use facelets). You - need to have an Ajax component inside the - <emphasis role="bold"> + </emphasis> (it does not matter if you use facelets). You need to have an + Ajax component inside the <emphasis role="bold"> <property>&lt;a4j:include&gt;</property> - </emphasis> - to navigate between the wizard pages. Otherwize, - the whole page update will be performed. - </para> + </emphasis> to navigate between the wizard pages. Otherwize, the whole page + update will be performed. </para> </listitem> <listitem> - <para> - If you want to involve the server side - validators and navigate to the next page only if - the Validation phase is passed successfully, you - can replace - <emphasis role="bold"> + <para> If you want to involve the server side validators and navigate to the + next page only if the Validation phase is passed successfully, you can + replace <emphasis role="bold"> <property>&lt;h:commandButton&gt;</property> - </emphasis> - with - <emphasis role="bold"> - <property> - &lt;a4j:commandButton&gt; - </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. Make sure, you define - <emphasis role="bold"><property>&lt;redirect/&gt;</property></emphasis> - option for the navigation rule to avoid memory leaks. - </para> + </emphasis> with <emphasis role="bold"> + <property> &lt;a4j:commandButton&gt; </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. + Make sure, you define <emphasis role="bold"> + <property>&lt;redirect/&gt;</property> + </emphasis> option for the navigation rule to avoid memory leaks. </para> </listitem> </itemizedlist> - <para></para> + <para/> </section> <section id="JavascriptInteractions"> <?dbhtml filename="JavascriptInteractions.html"?> <title>JavaScript Interactions</title> + <para> RichFaces allows writing Ajax-enabled JSF application without writing any + Javascript code. However, you can still invoke the JavaScript code if you need. + There are several ajax attributes that helps to do it. </para> <para> - RichFaces allows writing Ajax-enabled JSF application - without writing any Javascript code. However, you can - still invoke the JavaScript code if you need. There are - several ajax attributes that helps to do it. - </para> - <para> <emphasis> <property>&quot;onsubmit&quot;</property> - </emphasis> - attribute allows to invoke JavaScript code before an - Ajax request is sent. If - <emphasis> + </emphasis> attribute allows to invoke JavaScript code before an Ajax request is + sent. If <emphasis> <property>&quot;onsubmit&quot;</property> - </emphasis> - returns - &quot;false&quot; - , the Ajax request is canceled. The code of - <emphasis> + </emphasis> returns &quot;false&quot; , the Ajax request is canceled. The + code of <emphasis> <property>&quot;onsubmit&quot;</property> - </emphasis> - is inserted before the RichFaces Ajax call. Hence, the - <emphasis> + </emphasis> is inserted before the RichFaces Ajax call. Hence, the <emphasis> <property>&quot;onsubmit&quot;</property> - </emphasis> - should not has a &quot;return&quot; statement if you - want the Ajax request to be sent. If you are going to - invoke a JavaScript function that returns - &quot;true&quot; - or - &quot;false&quot; - , use the conditional statement to return something only - when you need to cancel the request. For example: - </para> + </emphasis> should not has a &quot;return&quot; statement if you want the + Ajax request to be sent. If you are going to invoke a JavaScript function that + returns &quot;true&quot; or &quot;false&quot; , 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}" ... @@ -818,116 +547,78 @@ <para> <emphasis> <property>&quot;onclick&quot;</property> - </emphasis> - attribute is similar to the - <emphasis> + </emphasis> attribute is similar to the <emphasis> <property>&quot;onsubmit&quot;</property> - </emphasis> - , but for clickable components such as - <emphasis role="bold"> + </emphasis> , but for clickable components such as <emphasis role="bold"> <property>&lt;a4j:commandLink&gt;</property> - </emphasis> - and - <emphasis role="bold"> + </emphasis> and <emphasis role="bold"> <property>&lt;a4j:commandButton&gt;</property> - </emphasis> - . If it returns - &quot;false&quot; - , the Ajax request is canceled also. - </para> + </emphasis> . If it returns &quot;false&quot; , the Ajax request is canceled + also. </para> <para> <emphasis> <property>&quot;oncomplete&quot;</property> - </emphasis> - attribute allows to invoke the JavaScript code right - after the Ajax Response is returned back and the DOM - tree of the browser is updated. RichFaces registers the - code for further invocation of XMLHTTP request object - before an Ajax request is sent. This means the code will - not be changed during processing of the request on the - server if you use JSF EL value binding. Also, you cannot - use &quot;this'&quot; inside the code, because it will - not point the component where Ajax request was - initiated. - </para> + </emphasis> attribute allows to invoke the JavaScript code right after the Ajax + Response is returned back and the DOM tree of the browser is updated. RichFaces + registers the code for further invocation of XMLHTTP request object before an Ajax + request is sent. This means the code will not be changed during processing of the + request on the server if you use JSF EL value binding. Also, you cannot use + &quot;this'&quot; inside the code, because it will not point the component + where Ajax request was initiated. </para> <para> <emphasis> <property>&quot;onbeforedomupdate&quot;</property> - </emphasis> - attribute defines JavaScript code for call after Ajax - response receiving and before updating DOM on a client - side. - </para> + </emphasis> attribute defines JavaScript code for call after Ajax response receiving + and before updating DOM on a client side. </para> <para> <emphasis> <property>&quot;data&quot;</property> - </emphasis> - attribute allows to get the additional data from the - server during an Ajax call. You can use JSF EL to point - the property of the managed bean and its value will be - serialized in JSON format and be available on the client - side. You can refer to it using the - <emphasis> + </emphasis> attribute allows to get the additional data from the server during an + Ajax call. You can use JSF EL to point the property of the managed bean and its + value will be serialized in JSON format and be available on the client side. You can + refer to it using the <emphasis> <property>&quot;data&quot;</property> - </emphasis> - variable. For example: - </para> + </emphasis> variable. For example: </para> <programlisting role="XML"><![CDATA[... <a4j:commandButton value="Update" data="#{userBean.name}" oncomplete="showTheName(data.name)" /> ... ]]></programlisting> - <para> - RichFaces allows to serialize not only primitive types - into JSON format, but also complex types including - arrays and collections. The beans should be serializable - to be refered with - <emphasis> + <para> RichFaces allows to serialize not only primitive types into JSON format, but also + complex types including arrays and collections. The beans should be serializable to + be refered with <emphasis> <property>&quot;data&quot;</property> - </emphasis> - . - </para> - <para> - There is a number of useful functions which can be used - in JavaScript: - </para> + </emphasis> . </para> + <para> There is a number of useful functions which can be used in JavaScript: </para> <itemizedlist> <listitem> <para> - <code>rich:clientId('id')</code> - - returns client id by short id or null if the - component with the id specified hasn't been - found - </para> + <code>rich:clientId('id')</code> - returns client id by short id or null if + the component with the id specified hasn't been found </para> </listitem> <listitem> <para> - <code>rich:element('id')</code> - - is a shortcut for - <code> - document.getElementById(#{rich:clientId('id')}) - </code> + <code>rich:element('id')</code> - is a shortcut for <code> + document.getElementById(#{rich:clientId('id')}) </code> </para> </listitem> <listitem> <para> - <code>rich:component('id')</code> - - is a shortcut for - <code>#{rich:clientId('id')}.component</code> + <code>rich:component('id')</code> - is a shortcut for + <code>#{rich:clientId('id')}.component</code> </para> </listitem> <listitem> <para> - <code>rich:findComponent('id')</code> - - returns an instance of UIComponent taking the short ID of the component as a parameter. - </para> + <code>rich:findComponent('id')</code> - returns an instance of UIComponent + taking the short ID of the component as a parameter. </para> <programlisting role="XML"><![CDATA[... <h:inputText id="myInput"> <a4j:support event="onkeyup" reRender="outtext"/> </h:inputText> -<h:outputText id="outtext" value="#{rich:findComponent('myInput').value}" /> +<h:outputText id="outtext" value="#{rich:findComponent('myInput').value}" /> ...]]></programlisting> </listitem> </itemizedlist> @@ -939,21 +630,19 @@ <para> <emphasis> <property>&quot;ajaxKeys&quot;</property> - </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> + </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> <tbody> <a4j:repeat value="#{bean.props}" var="detail" ajaxKeys="#{repeater.ajaxedRowsSet}"> - <tr> + <tr> <td> <h:outputText value="detail.someProperty" id="text"/> - </td> + </td> </tr> </a4j:repeat> </tbody> @@ -970,26 +659,16 @@ <para> <emphasis> <property>&quot;status&quot;</property> - </emphasis> - attribute for Ajax components (such as - <emphasis role="bold"> + </emphasis> attribute for Ajax components (such as <emphasis role="bold"> <property>&lt;a4j:commandButton&gt;</property> - </emphasis> - , - <emphasis role="bold"> + </emphasis> , <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> - </emphasis> - , etc.) points to an ID of - <emphasis role="bold"> + </emphasis> , etc.) points to an ID of <emphasis role="bold"> <property>&lt;a4j:status&gt;</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>&lt;a4j:status&gt;</property> - </emphasis> - component between different Ajax components from - different regions. The following example shows it. - </para> + </emphasis> component between different Ajax components from different regions. The + following example shows it. </para> <programlisting role="XML"><![CDATA[... <a4j:region id="extr"> @@ -1022,48 +701,26 @@ ... ]]></programlisting> - <para> - In the example - <emphasis role="bold"> + <para> In the example <emphasis role="bold"> <property>&lt;a4j:support&gt;</property> - </emphasis> - and - <emphasis role="bold"> + </emphasis> and <emphasis role="bold"> <property>&lt;a4j:commandButton&gt;</property> - </emphasis> - are defined in different regions. Values of - <emphasis> + </emphasis> are defined in different regions. Values of <emphasis> <property>&quot;status&quot;</property> - </emphasis> - attribute for these components points to an ID of - <emphasis role="bold"> + </emphasis> attribute for these components points to an ID of <emphasis role="bold"> <property>&lt;a4j:support&gt;</property> - </emphasis> - .Thus, the - <emphasis role="bold"> + </emphasis> .Thus, the <emphasis role="bold"> <property>&lt;a4j:support&gt;</property> - </emphasis> - component is shared between two components from - different regions. - </para> + </emphasis> component is shared between two components from different regions. </para> - <para> - More information could be found - <ulink + <para> More information could be found <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/status.jsf?... - here - </ulink> - . - </para> + here </ulink> . </para> - <para> - Other useful attribute is - <emphasis> + <para> Other useful attribute is <emphasis> <property>&quot;focus&quot;</property> - </emphasis> - . It points to an ID of a component where focus will be - set after an Ajax request. - </para> + </emphasis> . It points to an ID of a component where focus will be set after an + Ajax request. </para> </section> @@ -1075,110 +732,89 @@ <section id="SendAnAJAXRequest"> <?dbhtml filename="SendAnAJAXRequest.html"?> <title>Send an Ajax request</title> - <para> - There are different ways to send Ajax requests from your - JSF page. For example you can use - <emphasis role="bold"> + <para> There are different ways to send Ajax requests from your JSF page. For example + you can use <emphasis role="bold"> <property>&lt;a4j:commandButton&gt;</property> - </emphasis> - , - <emphasis role="bold"> - <property>&lt;a4j:commandLink&gt;</property> - , - <emphasis role="bold"> + </emphasis> , <emphasis role="bold"> + <property>&lt;a4j:commandLink&gt;</property> , <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> </emphasis> - </emphasis> - or - <emphasis role="bold"> + </emphasis> or <emphasis role="bold"> <property>&lt;a4j:support&gt;</property> - </emphasis> - tags or any other. - </para> + </emphasis> tags or any other. </para> + <para> All these tags hide the usual JavaScript activities that are required for an + XMHTTPRequest object building and an Ajax request sending. Also, they allow you to + decide which components of your JSF page are to be re-rendered as a result of the + Ajax response (you can list the IDs of these components in the <emphasis> + <property>&quot;reRender&quot;</property> + </emphasis> attribute). </para> <para> - All these tags hide the usual JavaScript activities that - are required for an XMHTTPRequest object building and an - Ajax request sending. Also, they allow you to decide - which components of your JSF page are to be re-rendered - as a result of the Ajax response (you can list the IDs - of these components in the <emphasis><property>&quot;reRender&quot;</property></emphasis> - attribute). - </para> - <para> <emphasis role="bold"> <property>&lt;a4j:commandButton&gt;</property> - </emphasis> - and - <emphasis role="bold"> + </emphasis> and <emphasis role="bold"> <property>&lt;a4j:commandLink&gt;</property> - </emphasis> - tags are used to send an Ajax request on - <emphasis><property>&quot;onclick&quot;</property></emphasis> JavaScript event. - </para> + </emphasis> tags are used to send an Ajax request on <emphasis> + <property>&quot;onclick&quot;</property> + </emphasis> JavaScript event. </para> <para> <emphasis role="bold"> <property>&lt;a4j:poll&gt;</property> - </emphasis> - tag is used to send an Ajax request periodically using a - timer. - </para> - <para> - The - <emphasis role="bold"> + </emphasis> tag is used to send an Ajax request periodically using a timer. </para> + <para> The <emphasis role="bold"> <property>&lt;a4j:support&gt;</property> - </emphasis> - tag allows you to add Ajax functionality to standard JSF - components and send Ajax request onto a chosen - JavaScript event: <emphasis><property>&quot;onkeyup&quot;</property></emphasis>, - <emphasis><property>&quot;onmouseover&quot;</property></emphasis>, etc. - </para> - <!--para>Most important attributes of components that provide Ajax request calling features are:</para> - <itemizedlist> - <listitem> - <emphasis> - <property>&quot;reRender&quot;</property> - </emphasis>attribute as it was mentioned <link linkend="SendAnAJAXRequest">before</link> - specifies components to be reRendered after Ajax response. The attribute can be specified - using EL expression and formed dynamicaly on the server side (see <ulink - url="index.html#FAQ">FAQ chapter</ulink>). </listitem> - <listitem> - <emphasis> - <property>&quot;RequestDelay&quot;</property> - </emphasis> attribute is used for a requests frequency regulation. </listitem> - </itemizedlist> - <programlisting role="XML"><![CDATA[<h:inputText size="50" value="#{bean.text}"> - <a4j:support event="onkeyup" RequestDelay="3"/> - </h:inputText>]]></programlisting> - <para>So every next request from the frequent keyboard events will be delayed on 3 ms to - reduce the number of requests. </para> - <itemizedlist> - <listitem> - <emphasis> - <property>&quot;EventsQueue&quot;</property> - </emphasis> is a queue that stores the next request. </listitem> - <listitem> - <emphasis> - <property>&quot;LimitToList&quot;</property> - </emphasis> attribute is used to regulate updatable regions. Setting it to true limits the - updatable areas only to ones specified in a reRender list, in other case all Output Panels - of the region are updated. </listitem> - <listitem> - <emphasis> - <property>&quot;ajaxSingle&quot;</property> - </emphasis> attributes specify regions to be sent with a request, if - &quot;false&quot; it is a full region, in other case it&apos;s is only a - control caused event. </listitem> - - <listitem> - <emphasis> - <property>&quot;timeout&quot;</property> - </emphasis>attribute is used for response waiting time on a particular request. If a - response is not received during this time, the request is aborted. </listitem> - - <listitem> - <emphasis> - <property>&quot;ignoreDupResponses&quot;</property> - </emphasis> is used to abort unfinished request on new event. </listitem> + </emphasis> tag allows you to add Ajax functionality to standard JSF components and + send Ajax request onto a chosen JavaScript event: <emphasis> + <property>&quot;onkeyup&quot;</property> + </emphasis>, <emphasis> + <property>&quot;onmouseover&quot;</property> + </emphasis>, etc. </para> + <!--para>Most important attributes of components that provide Ajax request calling features are:</para> + <itemizedlist> + <listitem> + <emphasis> + <property>&quot;reRender&quot;</property> + </emphasis>attribute as it was mentioned <link linkend="SendAnAJAXRequest">before</link> + specifies components to be reRendered after Ajax response. The attribute can be specified + using EL expression and formed dynamicaly on the server side (see <ulink + url="index.html#FAQ">FAQ chapter</ulink>). </listitem> + <listitem> + <emphasis> + <property>&quot;RequestDelay&quot;</property> + </emphasis> attribute is used for a requests frequency regulation. </listitem> + </itemizedlist> + <programlisting role="XML"><![CDATA[<h:inputText size="50" value="#{bean.text}"> + <a4j:support event="onkeyup" RequestDelay="3"/> + </h:inputText>]]></programlisting> + <para>So every next request from the frequent keyboard events will be delayed on 3 ms to + reduce the number of requests. </para> + <itemizedlist> + <listitem> + <emphasis> + <property>&quot;EventsQueue&quot;</property> + </emphasis> is a queue that stores the next request. </listitem> + <listitem> + <emphasis> + <property>&quot;LimitToList&quot;</property> + </emphasis> attribute is used to regulate updatable regions. Setting it to true limits the + updatable areas only to ones specified in a reRender list, in other case all Output Panels + of the region are updated. </listitem> + <listitem> + <emphasis> + <property>&quot;ajaxSingle&quot;</property> + </emphasis> attributes specify regions to be sent with a request, if + &quot;false&quot; it is a full region, in other case it&apos;s is only a + control caused event. </listitem> + + <listitem> + <emphasis> + <property>&quot;timeout&quot;</property> + </emphasis>attribute is used for response waiting time on a particular request. If a + response is not received during this time, the request is aborted. </listitem> + + <listitem> + <emphasis> + <property>&quot;ignoreDupResponses&quot;</property> + </emphasis> is used to abort unfinished request on new event. </listitem> </itemizedlist--> @@ -1189,123 +825,85 @@ <section id="DecideWhatToSend"> <?dbhtml filename="DecideWhatToSend.html"?> <title>Decide What to Send</title> - <para> - You may describe a region on the page you wish to send - to the server, in this way you can control what part of - the JSF View is decoded on the server side when you send - an Ajax request. - </para> - <para> - The easiest way to describe an Ajax region on your JSF - page is to do nothing, because the content between the - <emphasis role="bold"> + <para> You may describe a region on the page you wish to send to the server, in this way + you can control what part of the JSF View is decoded on the server side when you + send an Ajax request. </para> + <para> The easiest way to describe an Ajax region on your JSF page is to do nothing, + because the content between the <emphasis role="bold"> <property>&lt;f:view&gt;</property> - </emphasis> - and - <emphasis role="bold"> + </emphasis> and <emphasis role="bold"> <property>&lt;/f:view&gt;</property> - </emphasis> - tags is considered the default Ajax region. - </para> - <para> - You may define multiple Ajax regions on the JSF page - (they can even be nested) by using the - <emphasis role="bold"> + </emphasis> tags is considered the default Ajax region. </para> + <para> You may define multiple Ajax regions on the JSF page (they can even be nested) by + using the <emphasis role="bold"> <property>&lt;a4j:region&gt;</property> - </emphasis> - tag. - </para> - <para> - If you wish to render the content of an Ajax response - outside of the active region then the value of the - <emphasis><property>&quot;renderRegionOnly&quot;</property></emphasis> attribute should be set to - &quot;false&quot; (&quot;false&quot; is default value). - Otherwise, your Ajax updates are limited to elements of - the active region. - </para> + </emphasis> tag. </para> + <para> If you wish to render the content of an Ajax response outside of the active + region then the value of the <emphasis> + <property>&quot;renderRegionOnly&quot;</property> + </emphasis> attribute should be set to &quot;false&quot; + (&quot;false&quot; 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>&quot;reRender&quot;</property></emphasis> attribute to - define <code>&quot;AJAX zones&quot;</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"> + <para> Using IDs in the <emphasis> + <property>&quot;reRender&quot;</property> + </emphasis> attribute to define <code>&quot;AJAX zones&quot;</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>&lt;f:verbatim&gt;</property> - </emphasis> - tag and you wish to update its content on an Ajax - response. - </para> - <para> - The problem with the - <emphasis role="bold"> + </emphasis> tag and you wish to update its content on an Ajax response. </para> + <para> The problem with the <emphasis role="bold"> <property>&lt;f:verbatim/&gt;</property> - </emphasis> - tag as described above is related to the value of the - transientFlag of JSF components. If the value of this - flag is true, the component must not participate in - state saving or restoring of process. - </para> - <para> - In order to provide a solution to this kind of problems, - RichFaces uses the concept of an output panel that is - defined by the - <emphasis role="bold"> + </emphasis> tag as described above is related to the value of the transientFlag of + JSF components. If the value of this flag is true, the component must not + participate in state saving or restoring of process. </para> + <para> In order to provide a solution to this kind of problems, RichFaces uses the + concept of an output panel that is defined by the <emphasis role="bold"> <property>&lt;a4j:outputPanel&gt;</property> - </emphasis> - tag. If you put a - <emphasis role="bold"> + </emphasis> tag. If you put a <emphasis role="bold"> <property>&lt;f:verbatim&gt;</property> - </emphasis> - tag inside of the output panel, then the content of the - <emphasis role="bold"> + </emphasis> tag inside of the output panel, then the content of the <emphasis + role="bold"> <property>&lt;f:verbatim/&gt;</property> - </emphasis> - tag and content of other panel&apos;s child tags could - be updated on Ajax response. There are two ways to - control this: - <itemizedlist> + </emphasis> tag and content of other panel&apos;s child tags could be updated on + Ajax response. There are two ways to control this: <itemizedlist> <listitem> - <para> - By setting the <emphasis><property>&quot;ajaxRendered&quot;</property></emphasis> - attribute value to &quot;true&quot;. - </para> + <para> By setting the <emphasis> + <property>&quot;ajaxRendered&quot;</property> + </emphasis> attribute value to &quot;true&quot;. </para> </listitem> <listitem> - <para> - By setting the <emphasis><property>&quot;reRender&quot;</property></emphasis> - attribute value of an Action Component to - the output panel ID. - </para> + <para> By setting the <emphasis> + <property>&quot;reRender&quot;</property> + </emphasis> attribute value of an Action Component to the output panel + ID. </para> </listitem> </itemizedlist> </para> </section> <section id="process" role="updated"> <title>Decide what to process</title> - <para> - The <emphasis><property>&quot;process&quot;</property></emphasis> attribute allows to - define the ids of components to be processed together with the component which is marked as <property>ajaxSingle</property> or wrapped to region. - </para> - <para> - You could make use of the <emphasis><property>&quot;process&quot;</property></emphasis> attribute when you need to process only two - components in the different parts of view. - </para> - <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>&lt;a4j:support&gt;</property></emphasis> component - with <code>ajaxSingle=&quot;true&quot;</code> nested the second input will not be processed. - </para> - <para> - Here is a simple solution: - </para> + <para> The <emphasis> + <property>&quot;process&quot;</property> + </emphasis> attribute allows to define the ids of components to be processed + together with the component which is marked as <property>ajaxSingle</property> or + wrapped to region. </para> + <para> You could make use of the <emphasis> + <property>&quot;process&quot;</property> + </emphasis> attribute when you need to process only two components in the different + parts of view. </para> + <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>&lt;a4j:support&gt;</property> + </emphasis> component with <code>ajaxSingle=&quot;true&quot;</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"> <a4j:support ajaxSingle="true" process="email" event="onblur" reRender="someOut"/> @@ -1315,80 +913,81 @@ <a4j:support ajaxSingle="true" process="name" event="onblur" reRender="someOut"/> </h:inputText> ...]]></programlisting> - <para> - In the example above when the input field with the <code>id=&quot;name&quot;</code> looses focus, an AJAX request is sent. - So only two input fields (with <code>id=&quot;name&quot;</code> and additionally with <code>id=&quot;email&quot;</code>) - are processed: decoding, conversion/validation, value applying phases are executed. - The input field with the <code>id=&quot;email&quot;</code> is handled the same way on blur event. - </para> - <!--para> - The - <emphasis> - <property>&quot;process&quot;</property> - </emphasis> - attribute has two limitations: - </para> - <itemizedlist> - <listitem> - <para> - it works only if - <emphasis> - <property>&quot;ajaxSingle&quot;</property> - </emphasis> - equals to "true" for given command component - </para> - </listitem> - <listitem> - <para> - you do not have to point this attribute to one - of the own parent components to avoid processing - of command component twice - </para> - </listitem> - </itemizedlist> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<h:form> - <h:inputText id="oneA" value="#{bean.width}"/> - <br/> - <h:inputText id="oneB" value="#{bean.text}"/> - <br/> - <a4j:commandButton value="Submit2" process="oneB" ajaxSingle="true" reRender=":three1, :three2"/> -</h:form> -<h:outputText id="three1" value="#{bean.width}"/> - <br/> -<h:outputText id="three2" value="#{bean.text}"/> -...]]></programlisting> - <para> - In the example above after you click on the - <emphasis role="bold"> - <property>&lt;a4j:commandButton&gt;</property> - </emphasis> - <property>only</property> - <emphasis role="bold"> - <property>&lt;h:inputText&gt;</property> - </emphasis> - with - <code>"oneB"</code> - id is processed and entered data appears into the - <emphasis role="bold"> - <property>&lt;h:outputText&gt;</property> - </emphasis> - with - <code>"three2"</code> - id. If you doesn't use this attribute - <property>both</property> - <emphasis role="bold"> - <property>&lt;h:inputText&gt;</property> - </emphasis> - is processed and entered data appears into the - <property>both</property> - <emphasis role="bold"> - <property>&lt;h:outputText&gt;</property> - </emphasis> - . + <para> In the example above when the input field with the + <code>id=&quot;name&quot;</code> looses focus, an AJAX request is sent. + So only two input fields (with <code>id=&quot;name&quot;</code> and + additionally with <code>id=&quot;email&quot;</code>) are processed: + decoding, conversion/validation, value applying phases are executed. The input field + with the <code>id=&quot;email&quot;</code> is handled the same way on blur + event. </para> + <!--para> + The + <emphasis> + <property>&quot;process&quot;</property> + </emphasis> + attribute has two limitations: + </para> + <itemizedlist> + <listitem> + <para> + it works only if + <emphasis> + <property>&quot;ajaxSingle&quot;</property> + </emphasis> + equals to "true" for given command component + </para> + </listitem> + <listitem> + <para> + you do not have to point this attribute to one + of the own parent components to avoid processing + of command component twice + </para> + </listitem> + </itemizedlist> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[... +<h:form> + <h:inputText id="oneA" value="#{bean.width}"/> + <br/> + <h:inputText id="oneB" value="#{bean.text}"/> + <br/> + <a4j:commandButton value="Submit2" process="oneB" ajaxSingle="true" reRender=":three1, :three2"/> +</h:form> +<h:outputText id="three1" value="#{bean.width}"/> + <br/> +<h:outputText id="three2" value="#{bean.text}"/> +...]]></programlisting> + <para> + In the example above after you click on the + <emphasis role="bold"> + <property>&lt;a4j:commandButton&gt;</property> + </emphasis> + <property>only</property> + <emphasis role="bold"> + <property>&lt;h:inputText&gt;</property> + </emphasis> + with + <code>"oneB"</code> + id is processed and entered data appears into the + <emphasis role="bold"> + <property>&lt;h:outputText&gt;</property> + </emphasis> + with + <code>"three2"</code> + id. If you doesn't use this attribute + <property>both</property> + <emphasis role="bold"> + <property>&lt;h:inputText&gt;</property> + </emphasis> + is processed and entered data appears into the + <property>both</property> + <emphasis role="bold"> + <property>&lt;h:outputText&gt;</property> + </emphasis> + . </para--> </section> </section> @@ -1397,20 +996,14 @@ <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 &quot;regular&quot; JSF - request a browser makes correction independently. In case of - Ajax request in order to prevent layout destruction - it&apos;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> RichFaces uses a filter for a correction of code received on an Ajax request. In case + of a &quot;regular&quot; JSF request a browser makes correction independently. + In case of Ajax request in order to prevent layout destruction it&apos;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> 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> @@ -1427,21 +1020,14 @@ <note> <title>Note:</title> - <para> - Fast Filter is deprecated and available only for - backward compatibility with previous RichFaces versions. - Fast Filter usage isn&apos;t recomended, because there - is another way to use its functionality by means of - <link linkend="Neko">Neko filter type</link> - . - </para> + <para> Fast Filter is deprecated and available only for backward compatibility with + previous RichFaces versions. Fast Filter usage isn&apos;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&apos;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&apos;s possible + to configure different filters for different sets of pages for the same application. </para> <para>The possible filter types are:</para> @@ -1451,12 +1037,9 @@ </listitem> </itemizedlist> - <para> - &quot;TIDY&quot; 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> &quot;TIDY&quot; 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> @@ -1464,16 +1047,12 @@ </listitem> </itemizedlist> - <para> - &quot;NEKO&quot; filter type corresponds to the former - &quot;Fast Filter&quot; and it&apos;s based on the Neko - parser. In case of using this filter code isn&apos;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&apos;s of errors and corrupt a - layout as a result. This filter considerably accelerates all - Ajax requests processing. - </para> + <para> &quot;NEKO&quot; filter type corresponds to the former &quot;Fast + Filter&quot; and it&apos;s based on the Neko parser. In case of using this + filter code isn&apos;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&apos;s of errors and corrupt a layout as a result. This filter considerably + accelerates all Ajax requests processing. </para> <itemizedlist> <listitem> @@ -1493,7 +1072,7 @@ <param-name>org.ajax4jsf.xmlparser.ORDER</param-name> <param-value>NONE,NEKO,TIDY</param-value> </context-param> - + <context-param> <param-name>org.ajax4jsf.xmlparser.NONE</param-name> <param-value>/pages/performance\.xhtml,/pages/default.*\.xhtml</param-value> @@ -1503,117 +1082,87 @@ <param-name>org.ajax4jsf.xmlparser.NEKO</param-name> <param-value>/pages/repeat\.xhtml</param-value> </context-param> - - <filter> - <display-name>RichFaces Filter</display-name> - <filter-name>richfaces</filter-name> - <filter-class>org.ajax4jsf.Filter</filter-class> + + <filter> + <display-name>RichFaces Filter</display-name> + <filter-name>richfaces</filter-name> + <filter-class>org.ajax4jsf.Filter</filter-class> </filter> - - <filter-mapping> - <filter-name>richfaces</filter-name> + + <filter-mapping> + <filter-name>richfaces</filter-name> <servlet-name>Faces Servlet</servlet-name> - <dispatcher>FORWARD</dispatcher> + <dispatcher>FORWARD</dispatcher> <dispatcher>REQUEST</dispatcher> - <dispatcher>INCLUDE</dispatcher> + <dispatcher>INCLUDE</dispatcher> </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 &quot;NONE&quot; 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> + <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 &quot;NONE&quot; 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&apos;s not corrected, because filter type for this page - is defined as &quot;NONE&quot;. If a page is not from the - first set, then &quot;NEKO&quot; type is set. - </para> - <para> - If a page relates to the second set that is defined in the - following way: - </para> + <para> it&apos;s not corrected, because filter type for this page is defined as + &quot;NONE&quot;. If a page is not from the first set, then + &quot;NEKO&quot; 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 &quot;NEKO&quot; filter type is used for correction. If - it&apos;s not related to the second set, &quot;TIDY&quot; - type is set for the filter (&quot;TIDY&quot; filter type is - used for code correction). - </para> + <para> then &quot;NEKO&quot; filter type is used for correction. If it&apos;s + not related to the second set, &quot;TIDY&quot; type is set for the filter + (&quot;TIDY&quot; filter type is used for code correction). </para> </section> <section id="ScriptsandStylesLoadStrategy" role="updated"> <?dbhtml filename="ScriptsandStylesLoadStrategy" ?> <title>Scripts and Styles Load Strategy</title> + <para> Before the version 3.1.3, RichFaces loaded styles and script on demand. I.e. files + are loaded only if they are required on a particular page. Since RichFaces 3.1.3, + it&apos;s possible to manage how the RichFaces script and style files are loaded to + application. </para> <para> - Before the version 3.1.3, RichFaces loaded styles and script - on demand. I.e. files are loaded only if they are required - on a particular page. Since RichFaces 3.1.3, it&apos;s - possible to manage how the RichFaces script and style files - are loaded to application. - </para> - <para> <emphasis role="bold">org.richfaces.LoadScriptStrategy</emphasis> </para> - <para> - The following declaration in your web.xml allows loading the - integrated script files. - </para> + <para> The following declaration in your web.xml allows loading the integrated script files. </para> <programlisting role="XML"><![CDATA[... <context-param> <param-name>org.richfaces.LoadScriptStrategy</param-name> <param-value>ALL</param-value> - </context-param> + </context-param> ... ]]></programlisting> - <para> - If you do not declare the - <code>org.richfaces.LoadScriptStrategy</code> - in the web.xml, it equals to: - </para> + <para> If you do not declare the <code>org.richfaces.LoadScriptStrategy</code> in the + web.xml, it equals to: </para> <programlisting role="XML"><![CDATA[... <context-param> <param-name>org.richfaces.LoadScriptStrategy</param-name> <param-value>DEFAULT</param-value> - </context-param> + </context-param> ... ]]></programlisting> - <para> - The third possible value is &quot;NONE&quot;. 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 &quot;NONE&quot;. 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 JavaScript files - compression turns off! - </para> - <!--programlisting role="XML"><![CDATA[... - <context-param> - <param-name>org.ajax4jsf.COMPRESS_SCRIPT</param-name> - <param-value>false</param-value> - </context-param> - ... + <para> If you use <property>ALL</property> value of Scripts Load Strategy, the + JavaScript files compression turns off! </para> + <!--programlisting role="XML"><![CDATA[... + <context-param> + <param-name>org.ajax4jsf.COMPRESS_SCRIPT</param-name> + <param-value>false</param-value> + </context-param> + ... ]]></programlisting--> </note> @@ -1621,10 +1170,7 @@ <emphasis role="bold">org.richfaces.LoadStyleStrategy</emphasis> </para> - <para> - The following declaration allows to load only one integrated - style sheet file. - </para> + <para> The following declaration allows to load only one integrated style sheet file. </para> <programlisting role="XML"><![CDATA[... <context-param> <param-name>org.richfaces.LoadStyleStrategy</param-name> @@ -1632,103 +1178,66 @@ </context-param> ... ]]></programlisting> - <para> - The integrated style sheet contains style for all shipped - components. The skinnability feature still works. - </para> - <para> - The &quot;DEFAULT&quot; value is a classical on-demand - variant. - </para> - <para> - The &quot;NONE&quot; stops loading the styles at all. The - earlier introduced plain skin resets all color and font - parameters to null. The &quot;NONE&quot; 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&amp;op=viewtopic&... - RichFaces User Forum - </ulink> - . - </para> + <para> The integrated style sheet contains style for all shipped components. The + skinnability feature still works. </para> + <para> The &quot;DEFAULT&quot; value is a classical on-demand variant. </para> + <para> The &quot;NONE&quot; stops loading the styles at all. The earlier introduced + plain skin resets all color and font parameters to null. The &quot;NONE&quot; + 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&amp;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> 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> <section id="RequestErrorsHandling"> <?dbhtml filename="RequestErrorsHandling.html"?> <title>Request Errors Handling</title> - <para> - To execute your own code on the client in case of an - error during Ajax request, it&apos;s necessary to - redefine the standard - <code>&quot;A4J.AJAX.onError&quot;</code> - method: - </para> - <programlisting role="JAVA"><![CDATA[A4J.AJAX.onError = function(req,status,message) { - // Custom Developer Code + <para> To execute your own code on the client in case of an error during Ajax request, + it&apos;s necessary to redefine the standard + <code>&quot;A4J.AJAX.onError&quot;</code> method: </para> + <programlisting role="JAVA"><![CDATA[A4J.AJAX.onError = function(req,status,message) { + // Custom Developer Code };]]></programlisting> - <para> - The function defined this way accepts as parameters: - </para> + <para> The function defined this way accepts as parameters: </para> <itemizedlist> <listitem> <para> - <code>req</code> - - a params string of a request that calls an - error - </para> + <code>req</code> - a params string of a request that calls an error </para> </listitem> <listitem> <para> - <code>status</code> - - the number of an error returned by the server - </para> + <code>status</code> - the number of an error returned by the server </para> </listitem> <listitem> <para> - <code>message</code> - - a default message for the given error - </para> + <code>message</code> - a default message for the given error </para> </listitem> </itemizedlist> - <para> - Thus, it&apos;s possible to create your own handler that - is called on timeouts, inner server errors, and etc. - </para> + <para> Thus, it&apos;s possible to create your own handler that is called on + timeouts, inner server errors, and etc. </para> </section> <section id="SessionExpiredHandling"> <?dbhtml filename="SessionExpiredHandling.html"?> <title>Session Expired Handling</title> - <para> - It&apos;s possible to redefine also the - <emphasis> + <para> It&apos;s possible to redefine also the <emphasis> <property>&quot;onExpired&quot;</property> - </emphasis> - framework method that is called on the - <emphasis> + </emphasis> framework method that is called on the <emphasis> <property>&quot;Session Expiration&quot;</property> - </emphasis> - event. - </para> + </emphasis> event. </para> <para> <emphasis role="bold">Example:</emphasis> </para> - <programlisting role="JAVA"><![CDATA[A4J.AJAX.onExpired = function(loc,expiredMsg){ - // Custom Developer Code + <programlisting role="JAVA"><![CDATA[A4J.AJAX.onExpired = function(loc,expiredMsg){ + // Custom Developer Code }; ]]></programlisting> @@ -1736,31 +1245,21 @@ <itemizedlist> <listitem> <para> - <code> - loc - </code> - URL of the current page (on demand can be - updated) + <code> loc </code> - URL of the current page (on demand can be updated) </para> </listitem> <listitem> <para> - <code> - expiredMsg - </code>- a default message on - <emphasis> - <property> - &quot;Session Expiration&quot; - </property> - </emphasis> - event. - </para> + <code> expiredMsg </code>- a default message on <emphasis> + <property> &quot;Session Expiration&quot; </property> + </emphasis> event. </para> </listitem> </itemizedlist> - <!--note> - <title>Note:</title> - Until the version 1.0.5 the method can&apos;t be redefined on <emphasis > - <property>&quot;Session Expiration&quot;</property>, - </emphasis> a confirmation dialog with a request for view reloading was always called. + <!--note> + <title>Note:</title> + Until the version 1.0.5 the method can&apos;t be redefined on <emphasis > + <property>&quot;Session Expiration&quot;</property>, + </emphasis> a confirmation dialog with a request for view reloading was always called. </note--> </section> </section> @@ -1775,79 +1274,49 @@ <?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&apos;re working on - now, you&apos;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> If you have a look at a CSS file in an enterprise application, for example, the + one you&apos;re working on now, you&apos;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&apos;t necessarily have much knowledge of user - interface design. - </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&apos;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> 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> 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&apos;t completely replace standard CSS and - certainly doesn&apos;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> + <para> The <property>skinnability</property> feature can&apos;t completely replace + standard CSS and certainly doesn&apos;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> + <para> RichFaces <property>skinnability</property> is designed for mixed usage with: </para> <itemizedlist> <listitem> - <para> - Skin parameters defined in the RichFaces - framework - </para> + <para> Skin parameters defined in the RichFaces framework </para> </listitem> <listitem> @@ -1859,51 +1328,35 @@ </listitem> </itemizedlist> - <para> - The color scheme of the component can be applied to its - elements using any of three style classes: - </para> + <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> 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> + <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> + <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&apos;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&apos;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> @@ -1917,99 +1370,76 @@ <para> <emphasis role="bold">Example:</emphasis> </para> - <programlisting role="XML"> - &lt;rich:panel&gt; ... &lt;/rich:panel&gt; + <programlisting role="XML"> + &lt;rich:panel&gt; ... &lt;/rich:panel&gt; </programlisting> - <para> - The code generates a panel component on a page, which - consists of two elements: a wrapper - <emphasis role="bold"> + <para> The code generates a panel component on a page, which consists of two elements: a + wrapper <emphasis role="bold"> <property>&lt;div&gt;</property> - </emphasis> - element and a - <emphasis role="bold"> + </emphasis> element and a <emphasis role="bold"> <property>&lt;div&gt;</property> - </emphasis> - element for the panel body with the particular style - properties. The wrapper - <emphasis role="bold"> + </emphasis> element for the panel body with the particular style properties. The + wrapper <emphasis role="bold"> <property>&lt;div&gt;</property> - </emphasis> - element looks like: - </para> + </emphasis> element looks like: </para> <para> <emphasis role="bold">Example:</emphasis> </para> - <programlisting role="XML"> - &lt;div class="dr-pnl rich-panel"&gt; ... &lt;/div&gt; + <programlisting role="XML"> + &lt;div class="dr-pnl rich-panel"&gt; ... &lt;/div&gt; </programlisting> - <para> - dr-pnl is a CSS class specified in the framework via - skin parameters: - </para> + <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>border-color</property> is defined with <property>panelBorderColor</property> </para> </listitem> </itemizedlist> - <para> - It&apos;s possible to change all colors for all panels - on all pages by changing these skin parameters. - </para> + <para> It&apos;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"> + <para> However, if a <emphasis role="bold"> <property>&lt;rich:panel&gt;</property> - </emphasis> - class is specified somewhere on the page, its parameters - are also acquired by all panels on this page. - </para> + </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> A developer may also change the style properties for a particular panel. The + following definition: </para> <para> <emphasis role="bold">Example:</emphasis> </para> - <programlisting role="XML"> - &lt;rich:panel styleClass="customClass"&gt; ... - &lt;/rich:panel&gt; + <programlisting role="XML"> + &lt;rich:panel styleClass="customClass"&gt; ... + &lt;/rich:panel&gt; </programlisting> - <para> - Could add some style properties from customClass to one - particular panel, as a result we get three styles: - </para> + <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> - <programlisting role="XML"> - &lt;div class="dr_pnl rich-panel customClass"&gt; ... - &lt;/div&gt; + <programlisting role="XML"> + &lt;div class="dr_pnl rich-panel customClass"&gt; ... + &lt;/div&gt; </programlisting> </section> @@ -2018,10 +1448,8 @@ <title>Skin Parameters Tables in RichFaces</title> - <para> - RichFaces provides eight predefined skin parameters - (skins) at the simplest level of common customization: - </para> + <para> RichFaces provides eight predefined skin parameters (skins) at the simplest level + of common customization: </para> <itemizedlist> <listitem> @@ -2061,19 +1489,11 @@ </listitem> </itemizedlist> - <para> - To plug one in, it&apos;s necessary to specify a skin - name in the - <code>org.richfaces.SKIN</code> - context-param. - </para> + <para> To plug one in, it&apos;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>&quot;blueSky&quot;</property> - . - </para> + <para> Here is an example of a table with values for one of the main skins, + <property>&quot;blueSky&quot;</property> . </para> <table> <title>Colors</title> @@ -2311,178 +1731,116 @@ </tgroup> </table> - <para> - Skin "plain" was added from 3.0.2 version. It doesn't - have any parameters. It&apos;s necessary for embedding - RichFaces components into existing projecst which have - its own styles. - </para> + <para> Skin "plain" was added from 3.0.2 version. It doesn't have any parameters. + It&apos;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> + <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> + <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"> - &quot;Skin Parameters Tables in - RichFaces&quot; - </link> - ). The name of skin file should correspond to - the following format: - <code>&lt;name&gt;.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> Create a file and define in it skin constants which are used by style + classes (see section <link linkend="SkinParametersTablesInRichFaces"> + &quot;Skin Parameters Tables in RichFaces&quot; </link> ). The + name of skin file should correspond to the following format: + <code>&lt;name&gt;.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>&lt;contex-param&gt;</code> to the + web.xml of your application. An example is placed below: </para> <para> - Add a skin definition <code>&lt;contex-param&gt;</code> to - the web.xml of your application. An example is - placed below: - </para> - <para> <emphasis role="bold">Example:</emphasis> </para> <programlisting role="XML"><![CDATA[... - <context-param> - <param-name>org.richfaces.SKIN</param-name> - <param-value>name</param-value> + <context-param> + <param-name>org.richfaces.SKIN</param-name> + <param-value>name</param-value> </context-param> ... ]]></programlisting> </listitem> <listitem> - <para> - Put your - <code>&lt;name&gt;.skin.properties</code> - file in one of the following classpath elements: - META-INF/skins/ or classpath folder (e.g. - WEB-INF/classes). - </para> + <para> Put your <code>&lt;name&gt;.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> </section> <section id="BiuldInSkinnability"> <title>Built-in skinnability in RichFaces</title> - <para> - RichFaces gives an opportunity to incorporate - <property>skinnability</property> - into UI design. With this framework you can easily use - named skin parameters in properties files to control the - appearance of the skins that are applied consistently to - a whole set of components. You can look at examples of - predefined skins at: - </para> + <para> RichFaces gives an opportunity to incorporate <property>skinnability</property> + into UI design. With this framework you can easily use named skin parameters in + properties files to control the appearance of the skins that are applied + consistently to a whole set of components. You can look at examples of predefined + skins at: </para> <simplelist> <member> - <ulink - url="http://livedemo.exadel.com/richfaces-demo/"> - http://livedemo.exadel.com/richfaces-demo/ - </ulink> + <ulink url="http://livedemo.exadel.com/richfaces-demo/"> + http://livedemo.exadel.com/richfaces-demo/ </ulink> </member> </simplelist> - <para> - You may simply control the look-and-feel of your - application by using the - <property>skinnability</property> - service of the RichFaces framework. With the means of - this service you can define the same style for rendering - standard JSF components and custom JSF components built - with the help of RichFaces. - </para> - <para> - To find out more on - <property>skinnability</property> - possibilities, follow these steps: - </para> + <para> You may simply control the look-and-feel of your application by using the + <property>skinnability</property> service of the RichFaces framework. With the + means of this service you can define the same style for rendering standard JSF + components and custom JSF components built with the help of RichFaces. </para> + <para> To find out more on <property>skinnability</property> possibilities, follow these + steps: </para> <itemizedlist> <listitem> - <para> - Create a custom render kit and register it in - the faces-config.xml like this: - </para> + <para> Create a custom render kit and register it in the faces-config.xml like + this: </para> <programlisting role="XML"><![CDATA[<render-kit> <render-kit-id>NEW_SKIN</render-kit-id> - <render-kit-class> + <render-kit-class> org.ajax4jsf.framework.renderer.ChameleonRenderKitImpl </render-kit-class> </render-kit>]]></programlisting> </listitem> <listitem> - <para> - Then you need to create and register custom - renderers for the component based on the - look-and-feel predefined variables: - </para> + <para> Then you need to create and register custom renderers for the component + based on the look-and-feel predefined variables: </para> <programlisting role="XML"><![CDATA[<renderer> - <component-family>javax.faces.Command</component-family> - <renderer-type>javax.faces.Link</renderer-type> + <component-family>javax.faces.Command</component-family> + <renderer-type>javax.faces.Link</renderer-type> <renderer-class> newskin.HtmlCommandLinkRenderer - </renderer-class> + </renderer-class> </renderer>]]></programlisting> </listitem> <listitem> - <para> - Finally, you need to place a properties file - with skin parameters into the class path root. - There are two requirements for the properties - file: - </para> + <para> Finally, you need to place a properties file with skin parameters into + the class path root. There are two requirements for the properties file: </para> <itemizedlist> <listitem> - <para> - The file must be named - <code>&lt;skinName&gt;.skin.properties</code> - , in this case, it would be called - <code>newskin.skin.properties</code> - . + <para> The file must be named + <code>&lt;skinName&gt;.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=&lt;render-kit-id&gt; - </code> - in this case, it would be called - <code>render.kit=NEW_SKIN</code> - . - </para> + <para> The first line in this file should be <code> + render.kit=&lt;render-kit-id&gt; </code> in this case, + it would be called <code>render.kit=NEW_SKIN</code> . </para> </listitem> </itemizedlist> </listitem> </itemizedlist> - <para> - Extra information on custom renderers creation can be - found at: - </para> + <para> Extra information on custom renderers creation can be found at: </para> <simplelist> <member> <ulink @@ -2495,49 +1853,29 @@ <section id="StControlsSkinning"> <title>Standard controls skinning</title> - <para> - The feature is designed to unify the look and feel of - standard HTML element and RichFaces components. Skinning - can be applied to all controls on a page basing on - elements&apos; 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 - standard and extended, while skinning is - based on detecting browser user agent. If user agent is - not detected, Advanced level is used. - </para> + <para> The feature is designed to unify the look and feel of standard HTML element and + RichFaces components. Skinning can be applied to all controls on a page basing on + elements&apos; 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 - standard and + extended, 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> - </emphasis> - provides customization only basic style - properties. - </para> - <para> - To the following browsers Basic level of - skinning is applied: - </para> + </emphasis> provides customization only basic style properties. </para> + <para> To the following browsers Basic level of skinning is applied: </para> <itemizedlist> <listitem> <para>Internet Explorer 6</para> </listitem> <listitem> - <para> - Internet Explorer 7 in BackCompat mode - (see - <ulink - url="http://msdn2.microsoft.com/en-us/library/ms533687(VS.85).aspx&q... - document.compatMode property in MSDN - </ulink> - ) - </para> + <para> Internet Explorer 7 in BackCompat mode (see <ulink + url="http://msdn2.microsoft.com/en-us/library/ms533687(VS.85).aspx&q... + > document.compatMode property in MSDN </ulink> ) </para> </listitem> <listitem> <para>Opera</para> @@ -2551,33 +1889,23 @@ <para> <emphasis> <property>Extended</property> - </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 Advanced level of - skinning: - </para> + </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 Advanced level of skinning: </para> <itemizedlist> <listitem> <para>Mozilla Firefox</para> </listitem> <listitem> - <para> - Internet Explorer 7 in - Standards-compliant mode (CSS1Compat - mode) + <para> Internet Explorer 7 in Standards-compliant mode (CSS1Compat mode) </para> </listitem> </itemizedlist> </listitem> </itemizedlist> - <para> - These are the elements that affected by skinning: - </para> + <para> These are the elements that affected by skinning: </para> <itemizedlist> <listitem> <para> @@ -2621,60 +1949,37 @@ </listitem> <listitem> <para> - <property> - a (together with a:hover, a:visited - &quot;pseudo&quot;-elements) - </property> + <property> a (together with a:hover, a:visited + &quot;pseudo&quot;-elements) </property> </para> </listitem> </itemizedlist> <para>Skinning can be initialized in two ways:</para> <itemizedlist> <listitem> - <para> - adding - <code>org.richfaces.CONTROL_SKINNING</code> - parmeter to web.xml. Values: &quot;enable&quot; - and &quot;disable&quot;. This way implies that - skinning style classes are applied to elements - by element name and type attribute (where - applicable). No additional steps required from - an application developer. Please find below the - table that contains the list of element to which - skinning a applicable. - </para> + <para> adding <code>org.richfaces.CONTROL_SKINNING</code> parmeter to web.xml. + Values: &quot;enable&quot; and &quot;disable&quot;. This way + implies that skinning style classes are applied to elements by element name + and type attribute (where applicable). No additional steps required from an + application developer. Please find below the table that contains the list of + element to which skinning a applicable. </para> </listitem> <listitem> - <para> - adding - <code> - org.richfaces.CONTROL_SKINNING_CLASSES - </code> - parameter to web.xml file. Possible values - &quot;enable&quot; and &quot;disable&quot;. - Implementation of this method implies 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> + <para> adding <code> org.richfaces.CONTROL_SKINNING_CLASSES </code> parameter to + web.xml file. Possible values &quot;enable&quot; and + &quot;disable&quot;. Implementation of this method implies 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 &quot;enable&quot; you are provided with style - classes applicable to: - </para> + <para> By setting <code>org.richfaces.CONTROL_SKINNING_CLASSES</code> to + &quot;enable&quot; you are provided with style classes applicable to: </para> <itemizedlist> <listitem> + <para> Basic elements nested inside element having rich-container class, e.g.: </para> <para> - Basic elements nested inside element having - rich-container class, e.g.: - </para> - <para> <emphasis role="bold">Example:</emphasis> </para> <programlisting role="CSS"><![CDATA[... @@ -2684,16 +1989,11 @@ ...]]></programlisting> </listitem> <listitem> + <para> Elements that have class name corresponding to one of the basic elements + name/type mapped by the following scheme <code> + rich-&lt;elementName&gt;[-&lt;elementType&gt;] </code> . + See the example: </para> <para> - Elements that have class name corresponding to - one of the basic elements name/type mapped by - the following scheme - <code> - rich-&lt;elementName&gt;[-&lt;elementType&gt;] - </code> - . See the example: - </para> - <para> <emphasis role="bold">Example:</emphasis> </para> <programlisting role="CSS"><![CDATA[... @@ -2709,24 +2009,15 @@ <note> <title>Note:</title> - <para> - a elements have classes based on - &quot;link&quot; and pseudo class name, - e.g.: rich-link, rich-link-hover, - rich-link-visited - </para> + <para> a elements have classes based on &quot;link&quot; and pseudo + class name, e.g.: rich-link, rich-link-hover, rich-link-visited </para> </note> </listitem> </itemizedlist> - <para> - Additionally, the predefined rich CSS classes that we - provide can be used not only as classes for basic HTML - elements but also as classes for creation of complex - elements . - </para> - <para> - There is a snippet with some of them for example: - </para> + <para> Additionally, the predefined rich CSS classes that we provide can be used not + only as classes for basic HTML elements but also as classes for creation of complex + elements . </para> + <para> There is a snippet with some of them for example: </para> <programlisting role="XML"><![CDATA[... <u:selector name=".rich-box-bgcolor-header"> <u:style name="background-color" skin="headerBackgroundColor" /> @@ -2752,19 +2043,13 @@ <u:style name="background-repeat" value="repeat-x" /> </u:selector> ...]]></programlisting> - <para> - To get a better idea of standard component skinning we - recommend to explore CSS files located in - ui/core/src/main/resources/org/richfaces/ folder of - RichFaces svn. - </para> + <para> To get a better idea of standard component skinning we recommend to explore CSS + files located in ui/core/src/main/resources/org/richfaces/ folder of RichFaces svn. </para> <section id="Standard" role="NotInToc"> <title>Standard level</title> <table> - <title> - Html Elements Skin Bindings for input, select, - textarea, button, keygen, isindex, legend - </title> + <title> Html Elements Skin Bindings for input, select, textarea, button, keygen, + isindex, legend </title> <tgroup cols="2"> <thead> <row> @@ -2789,9 +2074,7 @@ </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for fieldset - </title> + <title> Html Elements Skin Bindings for fieldset </title> <tgroup cols="2"> <thead> <row> @@ -2842,9 +2125,7 @@ </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for a:hover - </title> + <title> Html Elements Skin Bindings for a:hover </title> <tgroup cols="2"> <thead> <row> @@ -2855,17 +2136,13 @@ <tbody> <row> <entry>color</entry> - <entry> - hoverLinkColorgeneralLinkColor - </entry> + <entry> hoverLinkColorgeneralLinkColor </entry> </row> </tbody> </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for a:visited - </title> + <title> Html Elements Skin Bindings for a:visited </title> <tgroup cols="2"> <thead> <row> @@ -2882,12 +2159,8 @@ </tgroup> </table> <table> - <title> - Rich Elements Skin Bindings for .rich-input, - .rich-select, .rich-textarea, - .rich-keygen, .rich-isindex, - .rich-link - </title> + <title> Rich Elements Skin Bindings for .rich-input, .rich-select, + .rich-textarea, .rich-keygen, .rich-isindex, .rich-link </title> <tgroup cols="2"> <thead> <row> @@ -2912,9 +2185,7 @@ </tgroup> </table> <table> - <title> - Rich Elements Skin Bindings for .rich-fieldset - </title> + <title> Rich Elements Skin Bindings for .rich-fieldset </title> <tgroup cols="2"> <thead> <row> @@ -2931,9 +2202,7 @@ </tgroup> </table> <table> - <title> - Rich Elements Skin Bindings for .rich-hr - </title> + <title> Rich Elements Skin Bindings for .rich-hr </title> <tgroup cols="2"> <thead> <row> @@ -2958,9 +2227,7 @@ </tgroup> </table> <table> - <title> - Rich Elements Skin Bindings for .rich-link - </title> + <title> Rich Elements Skin Bindings for .rich-link </title> <tgroup cols="2"> <thead> <row> @@ -2977,9 +2244,7 @@ </tgroup> </table> <table> - <title> - Rich Elements Skin Bindings for .rich-link:hover - </title> + <title> Rich Elements Skin Bindings for .rich-link:hover </title> <tgroup cols="2"> <thead> <row> @@ -2996,10 +2261,7 @@ </tgroup> </table> <table> - <title> - Rich Elements Skin Bindings for - .rich-link:visited - </title> + <title> Rich Elements Skin Bindings for .rich-link:visited </title> <tgroup cols="2"> <thead> <row> @@ -3016,10 +2278,7 @@ </tgroup> </table> <table> - <title> - Rich Elements Skin Bindings for - .rich-field - </title> + <title> Rich Elements Skin Bindings for .rich-field </title> <tgroup cols="2"> <thead> <row> @@ -3028,8 +2287,8 @@ </row> </thead> <tbody> - - + + <row> <entry>border-width</entry> <entry>1px</entry> @@ -3042,36 +2301,33 @@ <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> + <title> Rich Elements Skin Bindings for .rich-field-edit </title> <tgroup cols="2"> <thead> <row> @@ -3080,8 +2336,8 @@ </row> </thead> <tbody> - - + + <row> <entry>border-width</entry> <entry>1px</entry> @@ -3094,25 +2350,22 @@ <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> + <title> Rich Elements Skin Bindings for .rich-field-error </title> <tgroup cols="2"> <thead> <row> @@ -3121,8 +2374,8 @@ </row> </thead> <tbody> - - + + <row> <entry>border-width</entry> <entry>1px</entry> @@ -3135,44 +2388,42 @@ <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> + <title> Rich Elements Skin Bindings for .rich-button, .rich-button-disabled, + .rich-button-over </title> <tgroup cols="2"> <thead> <row> @@ -3181,8 +2432,8 @@ </row> </thead> <tbody> - - + + <row> <entry>border-width</entry> <entry>1px</entry> @@ -3195,25 +2446,25 @@ <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> @@ -3221,26 +2472,24 @@ <row> <entry>background-repeat</entry> <entry>repeat-x</entry> - </row> <row> + </row> + <row> <entry>background-position</entry> <entry>top left</entry> - </row> - - + </row> + + </tbody> </tgroup> </table> - - - - - - + + + + + + <table> - <title> - Rich Elements Skin Bindings for - .rich-button-press - </title> + <title> Rich Elements Skin Bindings for .rich-button-press </title> <tgroup cols="2"> <thead> <row> @@ -3249,26 +2498,23 @@ </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> + <title> Rich Elements Skin Bindings for .rich-container fieldset, .rich-fieldset </title> <tgroup cols="2"> <thead> <row> @@ -3281,43 +2527,40 @@ <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> + <title> Rich Elements Skin Bindings for .rich-legend </title> <tgroup cols="2"> <thead> <row> @@ -3326,7 +2569,7 @@ </row> </thead> <tbody> - + <row> <entry>font-size</entry> <entry>generalSizeFont</entry> @@ -3339,29 +2582,26 @@ <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> + <title> Rich Elements Skin Bindings for .rich-form </title> <tgroup cols="2"> <thead> <row> @@ -3370,7 +2610,7 @@ </row> </thead> <tbody> - + <row> <entry>padding</entry> <entry>0px</entry> @@ -3379,10 +2619,10 @@ <entry>margin</entry> <entry>0px</entry> </row> - - - - + + + + </tbody> </tgroup> </table> @@ -3394,10 +2634,8 @@ <?dbhtml filename="AdvancedLevel.html"?> <title>Extended level</title> <table> - <title> - Html Elements Skin Bindings for input, select, - textarea, button, keygen, isindex - </title> + <title> Html Elements Skin Bindings for input, select, textarea, button, keygen, + isindex </title> <tgroup cols="2"> <thead> <row> @@ -3422,9 +2660,7 @@ </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for *|button - </title> + <title> Html Elements Skin Bindings for *|button </title> <tgroup cols="2"> <thead> <row> @@ -3455,20 +2691,16 @@ </row> <row> <entry>background-image</entry> - <entry> - org.richfaces.renderkit.html.images.ButtonBackgroundImage + <entry> org.richfaces.renderkit.html.images.ButtonBackgroundImage </entry> </row> </tbody> </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for - button[type=button], button[type=reset], - button[type=submit], input[type=reset], - input[type=submit], input[type=button] - </title> + <title> Html Elements Skin Bindings for button[type=button], button[type=reset], + button[type=submit], input[type=reset], input[type=submit], + input[type=button] </title> <tgroup cols="2"> <thead> <row> @@ -3499,19 +2731,15 @@ </row> <row> <entry>background-image</entry> - <entry> - org.richfaces.renderkit.html.images.ButtonBackgroundImage + <entry> org.richfaces.renderkit.html.images.ButtonBackgroundImage </entry> </row> </tbody> </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for - *|button[disabled], .rich-container - *|button[disabled], .rich-button-disabled - </title> + <title> Html Elements Skin Bindings for *|button[disabled], .rich-container + *|button[disabled], .rich-button-disabled </title> <tgroup cols="2"> <thead> <row> @@ -3526,15 +2754,11 @@ </row> <row> <entry>border-color</entry> - <entry> - tableFooterBackgroundColor - </entry> + <entry> tableFooterBackgroundColor </entry> </row> <row> <entry>background-color</entry> - <entry> - tableFooterBackgroundColor - </entry> + <entry> tableFooterBackgroundColor </entry> </row> <row> <entry>background-image</entry> @@ -3546,22 +2770,18 @@ </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for - .rich-button-disabled, .rich-container + <title> Html Elements Skin Bindings for .rich-button-disabled, .rich-container button[type=&quot;button&quot;][disabled], .rich-button-button-disabled, .rich-container button[type=&quot;reset&quot;][disabled], .rich-button-reset-disabled, .rich-container button[type=&quot;submit&quot;][disabled], .rich-button-submit-disabled, .rich-container - input[type=&quot;reset&quot;][disabled], - .rich-input-reset-disabled, .rich-container - input[type=&quot;submit&quot;][disabled], + input[type=&quot;reset&quot;][disabled], .rich-input-reset-disabled, + .rich-container input[type=&quot;submit&quot;][disabled], .rich-input-submit-disabled, .rich-container input[type=&quot;button&quot;][disabled], - .rich-input-button-disabled - </title> + .rich-input-button-disabled </title> <tgroup cols="2"> <thead> <row> @@ -3576,15 +2796,11 @@ </row> <row> <entry>background-color</entry> - <entry> - tableFooterBackgroundColor - </entry> + <entry> tableFooterBackgroundColor </entry> </row> <row> <entry>border-color</entry> - <entry> - tableFooterBackgroundColor - </entry> + <entry> tableFooterBackgroundColor </entry> </row> <row> <entry>background-image</entry> @@ -3596,15 +2812,13 @@ </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for + <title> Html Elements Skin Bindings for *button[type=&quot;button&quot;][disabled], button[type=&quot;reset&quot;][disabled], button[type=&quot;submit&quot;][disabled], input[type=&quot;reset&quot;][disabled], input[type=&quot;submit&quot;][disabled], - input[type=&quot;button&quot;][disabled] - </title> + input[type=&quot;button&quot;][disabled] </title> <tgroup cols="2"> <thead> <row> @@ -3619,23 +2833,17 @@ </row> <row> <entry>border-color</entry> - <entry> - tableFooterBackgroundColor - </entry> + <entry> tableFooterBackgroundColor </entry> </row> <row> <entry>background-color</entry> - <entry> - tableFooterBackgroundColor - </entry> + <entry> tableFooterBackgroundColor </entry> </row> </tbody> </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for *|textarea - </title> + <title> Html Elements Skin Bindings for *|textarea </title> <tgroup cols="2"> <thead> <row> @@ -3666,19 +2874,15 @@ </row> <row> <entry>background-image</entry> - <entry> - org.richfaces.renderkit.html.images.InputBackgroundImage + <entry> org.richfaces.renderkit.html.images.InputBackgroundImage </entry> </row> </tbody> </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for - textarea[type=textarea], input[type=text], - input[type=password], select - </title> + <title> Html Elements Skin Bindings for textarea[type=textarea], + input[type=text], input[type=password], select </title> <tgroup cols="2"> <thead> <row> @@ -3709,19 +2913,15 @@ </row> <row> <entry>background-image</entry> - <entry> - org.richfaces.renderkit.html.images.InputBackgroundImage + <entry> org.richfaces.renderkit.html.images.InputBackgroundImage </entry> </row> </tbody> </tgroup> </table> <table> - <title> - Html Elements Skin Bindings for - *|textarea[disabled], .rich-container - *|textarea[disabled] - </title> + <title> Html Elements Skin Bindings for *|textarea[disabled], .rich-container + *|textarea[disabled] </title> <tgroup cols="2"> <thead> <row> @@ -3738,11 +2938,9 @@ </tgroup> </table> <table> - <title> - textarea[type=&quot;textarea&quot;][disabled], + <title> textarea[type=&quot;textarea&quot;][disabled], input[type=&quot;text&quot;][disabled], - input[type=&quot;password&quot;][disabled] - </title> + input[type=&quot;password&quot;][disabled] </title> <tgroup cols="2"> <thead> <row> @@ -3759,11 +2957,9 @@ </tgroup> </table> <table> - <title> - textarea[type=&quot;textarea&quot;][disabled], + <title> textarea[type=&quot;textarea&quot;][disabled], input[type=&quot;text&quot;][disabled], - input[type=&quot;password&quot;][disabled] - </title> + input[type=&quot;password&quot;][disabled] </title> <tgroup cols="2"> <thead> <row> @@ -3785,30 +2981,23 @@ </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&apos;t fully support - extended skinning feature, only basic skinning is applied. - </para> - - <para> - However, if a develop doesn&apos;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 &quot;org.richfaces.LoadStyleStrategy&quot; parameter to &quot;NONE&quot; in web.xml. - - </para> - + + <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&apos;t fully support extended skinning feature, only basic skinning is + applied. </para> + + <para> However, if a develop doesn&apos;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 + &quot;org.richfaces.LoadStyleStrategy&quot; parameter to + &quot;NONE&quot; in web.xml. </para> + <programlisting role="XML"><![CDATA[... <context-param> <param-name>org.richfaces.LoadStyleStrategy</param-name> @@ -3816,75 +3005,62 @@ </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> - + + <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> - You also need to specify &quot;media&quot; attribute in the - &lt;link&gt; tag which includes the &quot;extended_both.xcss&quot; style sheet with &quot;rich-extended-skinning&quot;. - - </para> - <para> - This is how you can include the style sheets to the page, - in case automatic skinnability implementation is disabled. - - </para> - + + + <para> You also need to specify <emphasis> + <property>&quot;media&quot;</property> + </emphasis> attribute in the <emphasis role="bold"> + <property>&lt;link&gt;</property> + </emphasis> tag which includes the &quot;extended_both.xcss&quot; style + sheet with &quot;rich-extended-skinning&quot;. </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/version</code> + instead of <code>a4j_version</code>. </para> + </note> + + + </section> <section id="XCSSfileformat"> <title>XCSS file format</title> - <para> - XCSS files are the core of RichFaces components - skinnability. - </para> - <para> - XCSS is an XML formatted CSS that adds extra - functionality to the skinning process - </para> - <para> - XCSS extends skinning possibilities by parsing the XCSS - file that contains all look-and-feel parameters of a - particular component into a standard CSS file that a web - browser can recognize. - </para> - <para> - XCSS file contains CSS properties and skin parameters - mappings. Mapping of a CSS selector to a skin parameter - is performed using - <emphasis role="bold"><property>&lt; u:selector &gt;</property></emphasis> - and - <emphasis role="bold"><property>&lt; u:style&gt;</property></emphasis> - XML tags that form the mapping structure. Please study - the example below. - </para> + <para> XCSS files are the core of RichFaces components skinnability. </para> + <para> XCSS is an XML formatted CSS that adds extra functionality to the skinning + process </para> + <para> XCSS extends skinning possibilities by parsing the XCSS file that contains all + look-and-feel parameters of a particular component into a standard CSS file that a + web browser can recognize. </para> + <para> XCSS file contains CSS properties and skin parameters mappings. Mapping of a CSS + selector to a skin parameter is performed using <emphasis role="bold"> + <property>&lt; u:selector &gt;</property> + </emphasis> and <emphasis role="bold"> + <property>&lt; u:style&gt;</property> + </emphasis> XML tags that form the mapping structure. Please study the example + below. </para> <programlisting role="XML"><![CDATA[... <u:selector name=".rich-component-name"> <u:style name="background-color" skin="additionalBackgroundColor" /> @@ -3894,10 +3070,8 @@ </u:selector> ... ]]></programlisting> - <para> - During processing the code in the shown example will be - parsed into a standard CSS format. - </para> + <para> During processing the code in the shown example will be parsed into a standard + CSS format. </para> <programlisting role="CSS"><![CDATA[... .rich-component-name { background-color: additionalBackgroundColor; /*the value of the constant defined by your skin*/ @@ -3907,26 +3081,21 @@ } ... ]]></programlisting> - <para> - The - <emphasis><property>&quot;name&quot;</property></emphasis> - attribute of <emphasis role="bold"><property>&lt;u:selector&gt;</property></emphasis> tag defines the CSS - selector, while - <emphasis><property>&quot;name&quot;</property></emphasis> - attribute of the - <emphasis role="bold"><property>&lt;u:style&gt;</property></emphasis> - tag defines what skin constant is mapped to a CSS - property. The - <emphasis><property>&quot;value&quot;</property></emphasis> - attribute of the - <emphasis role="bold"><property>&lt;u:style&gt;</property></emphasis> - tag can also be used to assign a value to a CSS - property. - </para> - <para> - CSS selectors with identical skinning properties can be - set as a comma separated list. - </para> + <para> The <emphasis> + <property>&quot;name&quot;</property> + </emphasis> attribute of <emphasis role="bold"> + <property>&lt;u:selector&gt;</property> + </emphasis> tag defines the CSS selector, while <emphasis> + <property>&quot;name&quot;</property> + </emphasis> attribute of the <emphasis role="bold"> + <property>&lt;u:style&gt;</property> + </emphasis> tag defines what skin constant is mapped to a CSS property. The <emphasis> + <property>&quot;value&quot;</property> + </emphasis> attribute of the <emphasis role="bold"> + <property>&lt;u:style&gt;</property> + </emphasis> tag can also be used to assign a value to a CSS property. </para> + <para> CSS selectors with identical skinning properties can be set as a comma separated + list. </para> <programlisting role="XML"><![CDATA[... <u:selector name=".rich-ordering-control-disabled, .rich-ordering-control-top, .rich-ordering-control-bottom, .rich-ordering-control-up, .rich-ordering-control-down"> <u:style name="border-color" skin="tableBorderColor" /> @@ -3936,51 +3105,37 @@ </section> <section id="PlugnSkin" role="new"> - <?dbhtml filename="PlugnSkin.html"?> + <?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> 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> + <para> The feature also provides an option to unify the appearance of rich controls with + standard HTML elements. </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> 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> + <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 --DarchetypeArtifactId=maven-archetype-plug-n-skin +mvn archetype:create +-DarchetypeGroupId=org.richfaces.cdk +-DarchetypeArtifactId=maven-archetype-plug-n-skin -DarchetypeVersion=RF-VERSION -DartifactId=ARTIFACT-ID --DgroupId=GROUP-ID +-DgroupId=GROUP-ID -Dversion=VERSION ... ]]></programlisting> @@ -3988,49 +3143,36 @@ <itemizedlist> <listitem> <para> - <code>DarchetypeVersion</code> - indicates the RichFaces version. For example, - <code>&quot;3.2.2-SNAPSHOT&quot;</code> + <code>DarchetypeVersion</code> indicates the RichFaces version. For example, + <code>&quot;3.2.2-SNAPSHOT&quot;</code> </para> </listitem> <listitem> <para> - <code>DartifactId</code> - artifact id of the project - </para> + <code>DartifactId</code> artifact id of the project </para> </listitem> <listitem> <para> - <code>DgroupId</code> - group id of the project - </para> + <code>DgroupId</code> group id of the project </para> </listitem> <listitem> <para> - <code>Dversion</code> - the version of the project you create, by - default it is <code>&quot;1.0.-SNAPSHOT&quot;</code> + <code>Dversion</code> the version of the project you create, by default it + is <code>&quot;1.0.-SNAPSHOT&quot;</code> </para> </listitem> </itemizedlist> - <para> - After this operation, a folder with the name of your - <code>&quot;ARTIFACT-ID&quot;</code> appears. The folder contains a - template of Maven project. - </para> + <para> After this operation, a folder with the name of your + <code>&quot;ARTIFACT-ID&quot;</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> Next steps will guide you though creating of the skin itself. </para> - <para> - In the root folder of Maven project (the one that - contains &quot;pom.xml&quot; file) you should run the - following command in the command line: - </para> + <para> In the root folder of Maven project (the one that contains + &quot;pom.xml&quot; 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 @@ -4043,17 +3185,13 @@ <listitem> <para> - <code>Dname</code> - defines the name of the new skin - </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 - &quot;groupId&quot; of the project is used. - </para> + <code>Dpackage</code> base package of the skin. By default + &quot;groupId&quot; of the project is used. </para> </listitem> </itemizedlist> @@ -4064,186 +3202,147 @@ <listitem> <para> - <code>DbaseSkin</code> - defines the name of the base skin. - </para> + <code>DbaseSkin</code> defines the name of the base skin. </para> </listitem> <listitem> <para> - <code>DcreateExt</code> - if set to &quot;true&quot;, extended CSS classes - are added. For more information, please, see - <link linkend="StControlsSkinning"> - &quot;Standard controls skinning&quot; - </link> + <code>DcreateExt</code> if set to &quot;true&quot;, extended CSS + classes are added. For more information, please, see <link + linkend="StControlsSkinning"> &quot;Standard controls + skinning&quot; </link> </para> </listitem> </itemizedlist> - <para> - As a result of the performed operations the following - files and folders are created: - </para> + <para> As a result of the performed operations the following files and folders are + created: </para> <itemizedlist> <listitem> <para> - <property>BaseImage.java</property> - - the base class to store images. Location: - &quot;\src\main\java\SKIN-PACKAGE\SKIN-NAME\images\&quot; + <property>BaseImage.java</property> - the base class to store images. + Location: &quot;\src\main\java\SKIN-PACKAGE\SKIN-NAME\images\&quot; </para> </listitem> <listitem> <para> - <property>BaseImageTest.java</property> - - a test version of a class that stores images. - Location: - &quot;\src\test\java\SKIN-PACKAGE\SKIN-NAME\images\&quot; - </para> + <property>BaseImageTest.java</property> - a test version of a class that + stores images. Location: + &quot;\src\test\java\SKIN-PACKAGE\SKIN-NAME\images\&quot; </para> </listitem> <listitem> <para> - <property>XCSS files</property> - - XCSS files define the new look of RichFaces - components affected by the new skin. Location: - &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot; - </para> + <property>XCSS files</property> - XCSS files define the new look of + RichFaces components affected by the new skin. Location: + &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot; </para> </listitem> <listitem> <para> - <property>SKIN-NAME.properties</property> - - a XCSS file that contains properties of the - new skin. Location: - &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot; - </para> - <para> - The following properties are used to configure - the SKIN-NAME.properties file: - </para> + <property>SKIN-NAME.properties</property> - a XCSS file that contains + properties of the new skin. Location: + &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot; </para> + <para> The following properties are used to configure the SKIN-NAME.properties + file: </para> <itemizedlist> <listitem> <para> - <property>baseSkin</property> - – the name of the base skin to be used - as basis. The look of the skin you - define will be affected by new style - properties. - </para> + <property>baseSkin</property> – the name of the base skin to be used + as basis. The look of the skin you define will be affected by new + style properties. </para> </listitem> <listitem> <para> - <property>generalStyleSheet</property> - - a path to the style sheet - (SKIN-NAME.xcss) that imports style - sheets of the components to be affected - by the new skin. - </para> + <property>generalStyleSheet</property> - a path to the style sheet + (SKIN-NAME.xcss) that imports style sheets of the components to be + affected by the new skin. </para> </listitem> <listitem> <para> - <property>extendedStyleSheet</property> - - a path to a style sheet that is used - to unify the appearance of RichFaces - components and standard HTML controls. - For additional information please read - <link linkend="StControlsSkinning"> - &quot;Standard controls - skinning&quot; - </link> - chapter. - </para> + <property>extendedStyleSheet</property> - a path to a style sheet + that is used to unify the appearance of RichFaces components and + standard HTML controls. For additional information please read <link + linkend="StControlsSkinning"> &quot;Standard controls + skinning&quot; </link> chapter. </para> </listitem> <listitem> <para> - <property>gradientType</property> - is a predefined property to set the type - of gradient applied to the new skin. - Possible values are glass, plastic, - plain. More information on gradient - implementation you can find further in - this chapter. - </para> + <property>gradientType</property> is a predefined property to set + the type of gradient applied to the new skin. Possible values are + glass, plastic, plain. More information on gradient implementation + you can find further in this chapter. </para> </listitem> </itemizedlist> </listitem> <listitem> <para> - <property>SKIN-NAME.xcss</property> - - a XCSS file that imports XCSS files of the - components to be affected by the new skin. - Location: - &quot;src\main\resources\META-INF\skins &quot; - </para> + <property>SKIN-NAME.xcss</property> - a XCSS file that imports XCSS files of + the components to be affected by the new skin. Location: + &quot;src\main\resources\META-INF\skins &quot; </para> </listitem> <listitem> <para> - <property>XCSS files</property> - If the command is executed with the - &quot;DcreateExt&quot; key set to - &quot;true&quot;, the XCSS (extended_classes.xcss and extended.xcss) files that define style - for standard controls will be created. Location: - &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot;. - </para> + <property>XCSS files</property> If the command is executed with the + &quot;DcreateExt&quot; key set to &quot;true&quot;, the XCSS + (extended_classes.xcss and extended.xcss) files that define style for + standard controls will be created. Location: + &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot;. </para> </listitem> <listitem> <para> - <property>SKIN-NAME-ext.xcss</property> / - - If the command is executed with the - &quot;DcreateExt&quot; key set to - &quot;true&quot;, the configuration - SKIN-NAME-ext.xcss file that imports XCSS file - defining styles for the standard controls will - be created. Location: - &quot;src\main\resources\META-INF\skins &quot;. - </para> + <property>SKIN-NAME-ext.xcss</property> / If the command is executed with + the &quot;DcreateExt&quot; key set to &quot;true&quot;, the + configuration SKIN-NAME-ext.xcss file that imports XCSS file defining styles + for the standard controls will be created. Location: + &quot;src\main\resources\META-INF\skins &quot;. </para> </listitem> <listitem> <para> - <property>SKIN-NAME-resources.xml</property> - - the file contains the description of all - listed above files. Location: - &quot;src\main\config\resources &quot;. - </para> + <property>SKIN-NAME-resources.xml</property> - the file contains the + description of all listed above files. Location: + &quot;src\main\config\resources &quot;. </para> </listitem> </itemizedlist> - <para>Now you can start editing the XCSS files - located in &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot;. - 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&apos;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 to the given selectors are you normally do while doing CSS coding. - The only thing, you have to keep in mind is that the selectors must be inside - <code>&lt;f:verbatim&gt; &lt;![CDATA[ ...]]&gt; &lt;/f:verbatim&gt;</code> tags.</para> - - - <para>For example </para> - - <programlisting role="XML"> + <para>Now you can start editing the XCSS files located in + &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot;. 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&apos;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 + to the given selectors are you normally do while doing CSS coding. The only + thing, you have to keep in mind is that the selectors must be inside + <code>&lt;f:verbatim&gt; &lt;![CDATA[ ...]]&gt; + &lt;/f:verbatim&gt;</code> tags.</para> + + + <para>For example </para> + + <programlisting role="XML"> <![CDATA[... .rich-calendar-cell { background: #537df8; } ... ]]></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>&lt;f:verbatim&gt; &lt;![CDATA[ ...]]&gt; &lt;/f:verbatim&gt;</code> tags. - - </para> - - <programlisting role="XML"> + + + + </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>&lt;f:verbatim&gt; &lt;![CDATA[ ...]]&gt; + &lt;/f:verbatim&gt;</code> tags. </para> + + <programlisting role="XML"> <![CDATA[... <u:selector name=".rich-calendar-cell"> <u:style name="border-bottom-color" skin="panelBorderColor"/> @@ -4254,39 +3353,30 @@ </u:selector> ... ]]></programlisting> - - - </listitem> -</itemizedlist> -<para> - - - - -</para> + </listitem> + </itemizedlist> - <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[... + <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[... + <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" /> <u:style name="border-style" value="solid" /> @@ -4298,38 +3388,29 @@ <f:attribute name="gradientHeight" value="17px" /> <f:attribute name="baseColor" skin="headerBackgroundColor" /> </f:resource> - </u:style> + </u:style> </u:selector> ... ]]></programlisting> - - <para> - So, as you can see, the <property>background-image</property> CSS property is defined with - <code> - &lt;f:resource - f:key=&quot;org.richfaces.renderkit.html.CustomizeableGradient&quot;&gt; - </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 can be set to one of the possible values glass, plastic, plain. - The gradient in it&apos;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 &quot;target&quot; folder of your skin project) - to &quot;\WebContent\WEB-INF\lib\&quot;. - </para> - + + <para> So, as you can see, the <property>background-image</property> CSS property is + defined with <code> &lt;f:resource + f:key=&quot;org.richfaces.renderkit.html.CustomizeableGradient&quot;&gt; + </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 can be set to one of the possible values glass, plastic, plain. The + gradient in it&apos;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 &quot;target&quot; folder of your skin project) + to &quot;\WebContent\WEB-INF\lib\&quot;. </para> + <programlisting role="XML"><![CDATA[... <context-param> <param-name>org.ajax4jsf.SKIN</param-name> @@ -4339,148 +3420,172 @@ ]]></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&apos;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 --DarchetypeArtifactId=maven-archetype-plug-n-skin --DarchetypeVersion=3.2.2-SNAPSHOT --DartifactId=P-n-S --DgroupId=GROUPID + <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&apos;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 +-DarchetypeArtifactId=maven-archetype-plug-n-skin +-DarchetypeVersion=3.2.2-SNAPSHOT +-DartifactId=P-n-S +-DgroupId=GROUPID -Dversion=1.0.-SNAPSHOT ]]></programlisting> - <para> - Now you can browse the &quot;P-n-S&quot; 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 + <para> Now you can browse the &quot;P-n-S&quot; 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 &quot;-DbaseSkin&quot; key defines what RichFaces built-in skin to be used as a base one, - &quot;-DcreateExt=true&quot; 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"> - <property>&lt;rich:calendar&gt;</property></emphasis> and some basic HTML controls to see how they are affected by standard controls skinning. - - </para> - <para>Thus, it will be demonstrated how to: </para> - <itemizedlist> - <listitem><para>Recolor the current day&apos;s cell background of the <emphasis role="bold"> - <property>&lt;rich:calendar&gt;</property></emphasis> to see how the new skin created with the help of Plug-n-Skin feature affects the style of the component;</para></listitem> - <listitem><para>Recolor a standard HTML submit button;</para></listitem> - - </itemizedlist> - - - <para>In oder to edit the style properties of <emphasis role="bold"> - <property>&lt;rich:calendar&gt;</property></emphasis> you - need to open the &quot;calendar.xcss&quot; file located in &quot;P-n-S\src\main\resources\skinpackage\plugnskindemo\css\&quot;. 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 &quot;extended.xcss&quot; file located in &quot;P-n-S\src\main\resources\skinpackage\plugnskindemo\css\&quot; and put in <code>font-weight: bold;</code> inside the curly braces of these coma separated selectors - <code>button[type=&quot;button&quot;], button[type=&quot;reset&quot;], button[type=&quot;submit&quot;], input[type=&quot;reset&quot;], input[type=&quot;submit&quot;], input[type=&quot;button&quot;]</code>. So, the CSS code should look like this. </para> + <para> As you remember from the previous section &quot;-DbaseSkin&quot; key + defines what RichFaces built-in skin to be used as a base one, + &quot;-DcreateExt=true&quot; determines that the new skin will come with + XCSS files that unify the look of the rich components with standard HTML + controls. </para> - <programlisting role="XML"><![CDATA[ + + <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"> + <property>&lt;rich:calendar&gt;</property> + </emphasis> and some basic HTML controls to see how they are affected by + standard controls skinning. </para> + <para>Thus, it will be demonstrated how to: </para> + <itemizedlist> + <listitem> + <para>Recolor the current day&apos;s cell background of the <emphasis + role="bold"> + <property>&lt;rich:calendar&gt;</property> + </emphasis> to see how the new skin created with the help of Plug-n-Skin + feature affects the style of the component;</para> + </listitem> + <listitem> + <para>Recolor a standard HTML submit button;</para> + </listitem> + + </itemizedlist> + + + <para>In oder to edit the style properties of <emphasis role="bold"> + <property>&lt;rich:calendar&gt;</property> + </emphasis> you need to open the &quot;calendar.xcss&quot; file located + in &quot;P-n-S\src\main\resources\skinpackage\plugnskindemo\css\&quot;. + 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 &quot;extended.xcss&quot; file located in + &quot;P-n-S\src\main\resources\skinpackage\plugnskindemo\css\&quot; and + put in <code>font-weight: bold;</code> inside the curly braces of these coma + separated selectors <code>button[type=&quot;button&quot;], + button[type=&quot;reset&quot;], + button[type=&quot;submit&quot;], + input[type=&quot;reset&quot;], + input[type=&quot;submit&quot;], + input[type=&quot;button&quot;]</code>. So, the CSS code should look + like this. </para> + + + <programlisting role="XML"><![CDATA[ button[type=&quot;button&quot;], button[type=&quot;reset&quot;], button[type=&quot;submit&quot;], input[type=&quot;reset&quot;], input[type=&quot;submit&quot;], input[type=&quot;button&quot;] { font-weight: bold; } ]]></programlisting> - <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 &quot;P-n-S&quot; folder of the skin project be executing <code>mvn clean install</code> command. This procedure results in creating a &quot;target&quot; folder that contains a .jar file with a compiled new skin, it our case the file is named &quot;P-n-S-1.0.-SNAPSHOT.jar&quot;. - 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 &quot;P-n-S-1.0.-SNAPSHOT.jar&quot; file to the &quot;\WebContent\WEB-INF\lib\&quot; folder.</para></listitem> - <listitem><para>Add the new skin&apos;s name to the &quot;web.xml&quot; file. It is done like this</para> - -<programlisting role="XML"><![CDATA[ + <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 + &quot;P-n-S&quot; folder of the skin project be executing <code>mvn + clean install</code> command. This procedure results in creating a + &quot;target&quot; folder that contains a .jar file with a compiled new + skin, it our case the file is named &quot;P-n-S-1.0.-SNAPSHOT.jar&quot;. + 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 &quot;P-n-S-1.0.-SNAPSHOT.jar&quot; file to the + &quot;\WebContent\WEB-INF\lib\&quot; folder.</para> + </listitem> + <listitem> + <para>Add the new skin&apos;s name to the &quot;web.xml&quot; + 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 &quot;web.xml&quot; file, which can be done by adding the following code to the &quot;web.xml&quot; file: - </para> - - - <programlisting role="XML"><![CDATA[ + + + + </listitem> + </itemizedlist> + + + <para> Please, do not forget that standard controls skinning has to be enabled in + the &quot;web.xml&quot; file, which can be done by adding the following + code to the &quot;web.xml&quot; file: </para> + + + <programlisting role="XML"><![CDATA[ <context-param> <param-name>org.richfaces.CONTROL_SKINNING</param-name> <param-value>enable</param-value> </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> - <imageobject> - <imagedata fileref="images/PlugnSkinDemo.png"/> - </imageobject> - </mediaobject> - </figure> -</section> + <para>The result of both action is displayed on the figure below.</para> + + + + <figure> + <title>Plug-n-Skin feature in action. </title> + <mediaobject> + <imageobject> + <imagedata fileref="images/PlugnSkinDemo.png"/> + </imageobject> + </mediaobject> + </figure> + </section> </section> </section> <section id="statemanagerapi"> <title>State Manager API</title> - <para> - JSF has an advanced navigation mechanism that allows you to define navigation from view to view. - Navigation happens in a Web Application when a user tries to switch from one page to another page - either by clicking a button, a hyperlink, or another command 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 &quot;Confirm&quot; is displayed, - buttons labels and methods are changed when the user clicks &quot;To register&quot; link: - </para> + <para> JSF has an advanced navigation mechanism that allows you to define navigation from + view to view. Navigation happens in a Web Application when a user tries to switch from + one page to another page either by clicking a button, a hyperlink, or another command + 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 + &quot;Confirm&quot; is displayed, buttons labels and methods are changed when + the user clicks &quot;To register&quot; link: </para> <figure> - <title> - Login Dialog - </title> + <title> Login Dialog </title> <mediaobject> <imageobject> <imagedata fileref="images/stateapi1.png"/> @@ -4488,9 +3593,7 @@ </mediaobject> </figure> <figure> - <title> - Register Dialog - </title> + <title> Register Dialog </title> <mediaobject> <imageobject> <imagedata fileref="images/stateapi2.png"/> @@ -4498,41 +3601,34 @@ </mediaobject> </figure> <para> - <property>RichFaces State API</property> allows easily to define some set of states for the pages and any properties for this states. - </para> - <para> - Actually States is a <property>map</property> where the entry key is a name of the State and the value is a State map. - Particular State map has entries with some names as keys and any objects as values that are used after the state activation. - Thus, in the State map you could define any values, method bindings, or just some simple state variables (constants) - which have different values for every State. - </para> + <property>RichFaces State API</property> allows easily to define some set of states for + the pages and any properties for this states. </para> + <para> Actually States is a <property>map</property> where the entry key is a name of the + State and the value is a State map. Particular State map has entries with some names as + keys and any objects as values that are used after the state activation. Thus, in the + State map you could define any values, method bindings, or just some simple state + variables (constants) which have different values for every State. </para> <figure> - <title> - RichFaces State API - </title> + <title> RichFaces State API </title> <mediaobject> <imageobject> <imagedata fileref="images/stateapi3.png"/> </imageobject> </mediaobject> </figure> - <para> - One of the most convenience features of the <property>RichFaces State API</property> is a navigation between states. - The <property>RichFaces State API</property> implements states change as the standard JSF navigation. - Action component just returns outcome and the RichFaces State API - <property>extension for the JSF navigation handler</property> - checks whether this outcome is registered as a <property>state change outcome</property> or not. - If the <property>state change outcome</property> is found the corresponding state is activated. - Otherwise the standard navigation handling is called. - </para> - <para> - In order to use <property>RichFaces State API</property> you should follow the next steps: - </para> + <para> One of the most convenience features of the <property>RichFaces State API</property> + is a navigation between states. The <property>RichFaces State API</property> implements + states change as the standard JSF navigation. Action component just returns outcome and + the RichFaces State API <property>extension for the JSF navigation handler</property> + checks whether this outcome is registered as a <property>state change outcome</property> + or not. If the <property>state change outcome</property> is found the corresponding + state is activated. Otherwise the standard navigation handling is called. </para> + <para> In order to use <property>RichFaces State API</property> you should follow the next + 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> @@ -4541,9 +3637,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> @@ -4551,9 +3646,7 @@ ...]]></programlisting> </listitem> <listitem> - <para> - Register two managed beans in the <property>faces-config.xml</property>: - </para> + <para> Register two managed beans in the <property>faces-config.xml</property>: </para> <programlisting role="XML"><![CDATA[... <managed-bean> <managed-bean-name>state</managed-bean-name> @@ -4571,9 +3664,8 @@ <managed-bean-scope>none</managed-bean-scope> </managed-bean> ...]]></programlisting> - <para> - One bean (&quot;config&quot;) defines and stores states as it is shown in the following example: - </para> + <para> One bean (&quot;config&quot;) defines and stores states as it is + shown in the following example: </para> <programlisting role="JAVA"><![CDATA[... public class Config { @@ -4642,17 +3734,16 @@ return states; } } -...]]></programlisting> - <para> - The other bean (&quot;state&quot;) with the type <code>org.richfaces.ui.model.States</code> has - the &quot;states&quot; managed property that is bound to the &quot;config&quot; bean which defines states. - </para> +...]]></programlisting> + <para> The other bean (&quot;state&quot;) with the type + <code>org.richfaces.ui.model.States</code> has the + &quot;states&quot; managed property that is bound to the + &quot;config&quot; bean which defines states. </para> </listitem> <listitem> - <para> - Use <property>state</property> bindings on the page. See the following example: - </para> - <programlisting role="XML"><![CDATA[... + <para> Use <property>state</property> bindings on the page. See the following + example: </para> + <programlisting role="XML"><![CDATA[... <h:panelGrid columns="3"> <h:outputText value="username" /> <h:inputText value="#{state.bean.name}" id="name" required="true" /> @@ -4665,9 +3756,8 @@ ...]]></programlisting> </listitem> </itemizedlist> - <para> - To get full <property>Login/Register dialog</property> example, please, - click <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/stateAPI.js...;. - </para> + <para> To get full <property>Login/Register dialog</property> example, please, click <ulink + url="http://livedemo.exadel.com/richfaces-demo/richfaces/stateAPI.js... + >here</ulink>. </para> </section> </chapter>