Author: SeanRogers Date: 2011-03-21 02:45:02 -0400 (Mon, 21 Mar 2011) New Revision: 22277 Added: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Using_skins-Panel_styles.xml_sample modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Using_skins-Rendered_panel.xml_sample Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Advanced_features.xml modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Basic_concepts.xml modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Introduction.xml modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-RichFaces_overview.xml modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Skinning_and_theming.xml Log: Updated according to review RFPL-1350 Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Advanced_features.xml =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Advanced_features.xml 2011-03-20 21:51:14 UTC (rev 22276) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Advanced_features.xml 2011-03-21 06:45:02 UTC (rev 22277) @@ -1,32 +1,31 @@ <?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> + +<!-- +Many sections in this document have been commented-out and marked as TODO as they refer to features not yet included. Some of these features may eventually function differently than described. +--> + <chapter id="chap-Developer_Guide-Advanced_features"> <title>Advanced features</title> - <!-- In development notification --> - <important> - <title>Documentation in development</title> - <para> - Some concepts covered in this chapter may refer to the previous version of <productname>Richfaces</productname>, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date. - </para> - </important> <para> Read this chapter for details on some of the advanced features and configuration possibilities for the RichFaces framework. </para> <section id="sect-Developer_Guide-Advanced_features-JSF2_integration"> - <title>JSF2 integration</title> + <title>JSF 2 integration</title> <para> - JavaServer Faces (<acronym>JSF</acronym>) is the Java-based web application framework upon which the RichFaces framework has been built. RichFaces is now integrated with JSF2, which features several improvements to the framework. + JavaServer Faces (<acronym>JSF</acronym>) is the Java-based web application framework upon which the RichFaces framework has been built. RichFaces is now integrated with JSF 2, which features several improvements to the framework. </para> <itemizedlist> <listitem> <para> - The standard display technology used by JSF1 was JavaServer Pages (<acronym>JSP</acronym>). With JSP2, the standard display technology has been changed to Facelets, which is a more powerful and more efficient View Declaration Language (<acronym>VLD</acronym>) than JSP. + The standard display technology used by JSF 1 was JavaServer Pages (<acronym>JSP</acronym>). With JSF 2, the standard display technology has been changed to Facelets, which is a more powerful and more efficient View Declaration Language (<acronym>VLD</acronym>) than JSP. </para> </listitem> </itemizedlist> </section> - + + <!-- TODO <section id="sect-Developer_Guide-Advanced_features-Performance_optimization"> <title>Performance optimization</title> <para> @@ -36,28 +35,9 @@ For further details on optimizing the performance of RichFaces applications, refer to the <citetitle pubwork="chapter">Resources</citetitle> and <citetitle pubwork="chapter">Processing management</citetitle> chapters in the <citetitle>Component Reference Guide</citetitle>. </para> </section> + --> - <section id="sect-Developer_Guide-Advanced_features-Traffic_control_and_queues"> - <title>Traffic control and queues</title> - <para> - The RichFaces framework allows for queues to manage traffic from Ajax requests, events, and page updates. Controlling the message processing with a queue can make applications more efficient and avoid problems with data corruption. Basic queuing is available with all RichFaces components, and the <sgmltag>&lt;a4j:queue&gt;</sgmltag> component adds advanced queuing to standard JSF components. - </para> - <para> - For further details on RichFaces queue management, refer to the queuing details in the <citetitle pubwork="chapter">Common Ajax attributes</citetitle> chapter and the <citetitle pubwork="chapter">Processing management</citetitle> chapter in the <citetitle>Component Reference Guide</citetitle>. - </para> - </section> - - <section id="sect-Developer_Guide-Advanced_features-Validation"> - <title>Validation</title> - <para> - The RichFaces framework features several validation components. These components can validate Ajax actions, or validate data against model-based constraints defined using <application>Hibernate Validator</application>. - </para> - <para> - For further details on RichFaces validation components, refer to the <citetitle pubwork="chapter">Validation</citetitle> chapter of the <citetitle>Component Reference Guide</citetitle>. - </para> - </section> - - <!-- + <!-- TODO <section id="sect-Developer_Guide-Advanced_features-Filters"> <title>Filters</title> <para> @@ -133,7 +113,8 @@ </para> </section> --> - + + <!-- TODO <section id="sect-Developer_Guide-Advanced_features-Script_and_style_loading"> <title>Script and style loading</title> <para> @@ -186,7 +167,9 @@ </variablelist> </para> </section> - + --> + + <!-- TODO <section id="sect-Developer_Guide-Script_and_style_loading-org.richfaces.LoadStyleStrategy"> <title><code>org.richfaces.LoadStyleStrategy</code></title> <para> @@ -230,111 +213,46 @@ </section> </section> + --> <section id="sect-Developer_Guide-Advanced_features-Error_handling"> <title>Error handling</title> <para> RichFaces allows standard handlers to be defined for processing different application exceptions. Custom JavaScript can be executed when these exceptions occur. </para> - <para> - To define handlers for application exceptions, add the following code to your <filename>web.xml</filename> file: - </para> - -<programlisting language="XML" role="XML">&lt;context-param&gt; - &lt;param-name&gt;org.ajax4jsf.handleViewExpiredOnClient&lt;/param-name&gt; - &lt;param-value&gt;true&lt;/param-value&gt; -&lt;/context-param&gt; -</programlisting> - <note> - <title>MyFaces compatibility</title> + + <section id="sect-Developer_Guide-Advanced_features-Client-side_errors"> + <title>Client-side errors</title> <para> - Custom error handlers for the <methodname>onError</methodname> and <methodname>onExpire</methodname> events do not work under MyFaces. MyFaces handles exceptions through its internal debug page. Use the following code in the <filename>web.xml</filename> file to prevent this behavior in MyFaces: + JSF provides a global <code>onError</code> handler on the client. The handler provides the relevant error code and other associated data. The RichFaces Ajax components provide the <varname>error</varname> attribute if extra functionality needs to be defined. </para> - -<programlisting language="XML" role="XML">&lt;context-param&gt; - &lt;param-name&gt;org.apache.myfaces.ERROR_HANDLING&lt;/param-name&gt; - &lt;param-value&gt;false&lt;/param-value&gt; -&lt;/context-param&gt; -</programlisting> - </note> - <section id="sect-Developer_Guide-Error_handling-Handling_request_errors"> - <title>Handling request errors</title> <para> - To execute custom JavaScript code on the client when an error occurs during an Ajax request, redefine the standard <methodname>A4J.AJAX.onError</methodname> method, as shown in <xref linkend="exam-Developer_Guide-Handling_request_errors-Example_request_error" />. + Additional processing is available through a number of components, such as the following: </para> - <example id="exam-Developer_Guide-Handling_request_errors-Example_request_error"> - <title>Example request error</title> - -<programlisting language="Java" role="JAVA"><xi:include href="extras/exam-Developer_Guide-Advanced_features-Example_request_error.js" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - </example> - <para> - The function accepts three parameters: - <variablelist> - <varlistentry> - <term><parameter>req</parameter></term> - <listitem> - <para> - A string of parameters from the request that caused the error. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>status</parameter></term> - <listitem> - <para> - The error number returned by the server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter></term> - <listitem> - <para> - A default message for the error. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> + <itemizedlist> + <listitem> + <para> + The <sgmltag>&lt;a4j:status&gt;</sgmltag> component has an additional error state. + </para> + </listitem> + <listitem> + <para> + The <sgmltag>&lt;a4j:queue&gt;</sgmltag> component can be used to process errors. + </para> + </listitem> + </itemizedlist> </section> - - <section id="sect-Developer_Guide-Error_handling-Handling_session_expiration_errors"> - <title>Handling session expiration errors</title> + + <section id="sect-Developer_Guide-Advanced_features-Server-side_errors"> + <title>Server-side errors</title> <para> - Redefine the <methodname>A4J.AJAX.onExpired</methodname> method to handle the expiration of a user's session, as shown in <xref linkend="exam-Developer_Guide-Handling_session_expiration_errors-Example_session_expiration_error" />. + Use the JSF 2 <classname>ExceptionHandler</classname> class to handle server-side errors such as session expiration. </para> - <example id="exam-Developer_Guide-Handling_session_expiration_errors-Example_session_expiration_error"> - <title>Example session expiration error</title> - -<programlisting language="Java" role="JAVA"><xi:include href="extras/exam-Developer_Guide-Advanced_features-Example_session_expiration_error.js" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - </example> - <para> - The function accepts two parameters: - <variablelist> - <varlistentry> - <term><parameter>loc</parameter></term> - <listitem> - <para> - The URL of the current page, which can be updated on demand. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>expiredMsg</parameter></term> - <listitem> - <para> - A default message for the session expiration error. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> </section> </section> - + + <!-- TODO <section id="sect-Developer_Guide-Advanced_features-Managing_states" status="draft"> <title>Managing states</title> <para> @@ -344,45 +262,13 @@ Actually States is a map 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> </section> + --> - <section id="sect-Developer_Guide-Advanced_features-User_roles"> - <title>User roles</title> + <section id="sect-Developer_Guide-Advanced_features-Other_functions"> + <title>Other functions</title> <para> - To check whether the logged-in user belongs to a certain user role, use the <function>rich:isUserInRole(Object)</function> function in RichFaces. The example demonstrates the function's use to render controls only for users with administrator privileges. + RichFaces provides a number of advanced functions, such as managing user roles and identifying elements. Refer to the <citetitle pubwork="chapter">Functions</citetitle> chapter in the <citetitle pubwork="book">RichFaces Component Reference</citetitle> for further details. </para> - <example id="exam-Developer_Guide-User_roles-User_role_example"> - <title>User role example</title> - <para> - Certain controls only need to be rendered for administrators. - </para> - <procedure> - <step id="step-Developer_Guide-User_role_example-Create_admin_role"> - <title>Create <literal>admin</literal> role</title> - <para> - Create the <literal>admin</literal> role in the <filename>web.xml</filename> file: - </para> - -<programlisting language="XML" role="XML"><xi:include href="extras/exam-Developer_Guide-Advanced_features-User_role_example-0.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - </step> - <step id="step-Developer_Guide-User_role_example-Implement_authorization_for_users"> - <title>Implement authorization for users</title> - <para> - Assign the <literal>admin</literal> role to users when they log in to the application as administrators. - </para> - </step> - <step id="step-Developer_Guide-User_role_example-Use_the_richisUserInRoleObject_function"> - <title>Use the <function>rich:isUserInRole(Object)</function> function</title> - <para> - The <function>rich:isUserInRole(Object)</function> function can be used with the <varname>rendered</varname> attribute of any component: - </para> - -<programlisting language="XML" role="XML"><xi:include href="extras/exam-Developer_Guide-Advanced_features-User_role_example-1.xml_sample" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</programlisting> - </step> - </procedure> - - </example> </section> </chapter> Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Basic_concepts.xml =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Basic_concepts.xml 2011-03-20 21:51:14 UTC (rev 22276) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Basic_concepts.xml 2011-03-21 06:45:02 UTC (rev 22277) @@ -3,20 +3,13 @@ ]> <chapter id="chap-Developer_Guide-Basic_concepts"> <title>Basic concepts</title> - <!-- In development notification --> - <important> - <title>Documentation in development</title> - <para> - Some concepts covered in this chapter may refer to the previous version of <productname>Richfaces</productname>, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date. - </para> - </important> <para> Read this chapter for the basic concepts of using RichFaces in conjunction with Ajax and JavaServer Faces. </para> <section id="sect-Developer_Guide-Basic_concepts-Sending_an_Ajax_request"> <title>Sending an Ajax request</title> <para> - Many of the tags in the <classname>a4j</classname> and <classname>rich</classname> tag libraries are capable of sending Ajax requests from a JavaServer Faces (JSF) page. RichFaces tags hide the usual JavaScript activities that are required for an XMHTTPRequest object building and an Ajax request sending. Additionally the tags can determine which components of a JSF page are to be re-rendered as a result of the Ajax response; refer to <xref linkend="sect-Developer_Guide-Receiving_events_and_updates-Partial_page_updates" /> for details. + Many of the tags in the <classname>a4j</classname> and <classname>rich</classname> tag libraries are capable of sending Ajax requests from a JavaServer Faces (JSF) page. </para> <itemizedlist> <listitem> @@ -42,19 +35,13 @@ </itemizedlist> </section> + <!-- <section id="sect-Developer_Guide-Basic_concepts-Receiving_events_and_updates"> <title>Receiving events and client-side updates</title> <para> Updates are made only to those regions specified using the <varname>execute</varname>. If no specific regions are declared, the whole page is updated when an Ajax response is received. </para> - <!-- - <note> - <title>Rendering outside the active region</title> - <para> - If the content of an Ajax response needs to be rendered outside the active region, then the value of the <varname>renderRegionOnly</varname> attribute should be set to <literal>false</literal>. Otherwise, your Ajax updates are limited to elements of the active region. If not defined, the default setting is <code>renderRegionOnly="false"</code>. - </para> - </note> - --> + <section id="sect-Developer_Guide-Receiving_events_and_updates-Partial_page_updates"> <title>Partial page updates</title> <para> @@ -72,6 +59,120 @@ </section> </section> + --> + + <section id="sect-Developer_Guide-Basic_concepts-Partial_tree_processing"> + <title>Partial tree processing</title> + <para> + Use the <varname>execute</varname> attribute to specify which parts of the JSF tree to process during an Ajax request. The <varname>execute</varname> attribute can point to an <varname>id</varname> identifier of a specific component to process. Components can also be identified through the use of Expression Language (<acronym>EL</acronym>). + </para> + <para> + Alternatively, the <varname>execute</varname> attribute accepts the following keywords: + </para> + <variablelist> + <varlistentry> + <term><code>@all</code></term> + <listitem> + <para> + Every component is processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@none</code></term> + <listitem> + <para> + No components are processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@this</code></term> + <listitem> + <para> + The requesting component with the <varname>execute</varname> attribute is processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@form</code></term> + <listitem> + <para> + The form that contains the requesting component is processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@region</code></term> + <listitem> + <para> + The region that contains the requesting component is processed. Use the <sgmltag>&lt;a4j:region&gt;</sgmltag> component as a wrapper element to specify regions. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Some components make use of additional keywords. These are detailed under the relevant component entry in the <citetitle>RichFaces Component Reference</citetitle>. + </para> + </section> + + <section id="sect-Developer_Guide-Basic_concepts-Partial_view_updates"> + <title>Partial view updates</title> + <para> + Use the <varname>render</varname> attribute to specify which components to render for an Ajax update. The <varname>render</varname> attribute can point to an <varname>id</varname> identifier of a specific component to update. Components can also be identified through the use of Expression Language (<acronym>EL</acronym>). + </para> + <para> + Alternatively, the <varname>render</varname> attribute accepts the following keywords: + </para> + <variablelist> + <varlistentry> + <term><code>@all</code></term> + <listitem> + <para> + Every component is updated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@none</code></term> + <listitem> + <para> + No components are updated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@this</code></term> + <listitem> + <para> + The requesting component with the <varname>execute</varname> attribute is updated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@form</code></term> + <listitem> + <para> + The form that contains the requesting component is updated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><code>@region</code></term> + <listitem> + <para> + The region that contains the requesting component is updated. Use the <sgmltag>&lt;a4j:region&gt;</sgmltag> component as a wrapper element to specify regions. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Some components make use of additional keywords. These are detailed under the relevant component entry in the <citetitle>RichFaces Component Reference</citetitle>. + </para> + <para> + Use the <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> component with the <code>ajaxRendered="true"</code> setting to always update a section irrespective of the requesting component's <varname>render</varname> attribute. The <sgmltag>&lt;rich:message&gt;</sgmltag> and <sgmltag>&lt;rich:messages&gt;</sgmltag> components are based on the <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> component, and as such will also always be updated. To override this behavior, use the <code>limitRender="true"</code> setting on the requesting component. + </para> + </section> <!-- <section id="sect-Developer_Guide-Basic_concepts-Processing_data_on_the_server"> Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml 2011-03-20 21:51:14 UTC (rev 22276) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml 2011-03-21 06:45:02 UTC (rev 22277) @@ -4,11 +4,12 @@ <chapter id="chap-Developer_Guide-Getting_started_with_RichFaces"> <title>Getting started with RichFaces</title> <para> - Follow the instructions in this chapter to configure the RichFaces framework and get started with application development. RichFaces applications can be developed using <productname>JBoss Tools</productname>, as described in <xref linkend="sect-Developer_Guide-Getting_started_with_RichFaces-Creating_a_project_with_JBoss_Tools" />; or using <productname>Maven</productname>, as described in <xref linkend="sect-Developer_Guide-Getting_started_with_RichFaces-Creating_a_project_with_Maven" />. + Follow the instructions in this chapter to configure the RichFaces framework and get started with application development. </para> <para> If you have existing projects that use a previous version of RichFaces, refer to the <citetitle>RichFaces Migration Guide</citetitle>. </para> + <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Technical_Requirements"> <title>Technical Requirements</title> <para> @@ -22,29 +23,43 @@ </listitem> <listitem> <para> - <productname>JBoss Tools 3.1</productname> + An application server compliant with Java Platform, Enterprise Edition 5 (<acronym>JEE5</acronym>), such as <productname>JBoss Application Server 6</productname> or <productname>Apache Tomcat 6</productname>. </para> </listitem> <listitem> <para> - A <productname>JavaServer Faces 2</productname> (<acronym>JSF 2</acronym>) implementation + A compliant web browser, such as <productname>Firefox 3.5</productname> or <productname>Internet Explorer 7</productname> </para> </listitem> + </itemizedlist> + <!-- + <para> + RichFaces supports additional products not listed here. Refer to <xref linkend="sect-Component_Reference-RichFaces_overview-Full_technical_requirements" /> for a full list of technical requirements and supported envrionments, browsers, and tools. + </para> + --> + + </section> + + <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Development_environments"> + <title>Development environments</title> + <para> + RichFaces applications can be developed using a range of tools, including integrated development environments (<acronym>IDE</acronym>s). This chapter covers only two such environments in detail: + </para> + <itemizedlist> <listitem> <para> - An application server, such as <productname>JBoss Application Server 6</productname> or <productname>Apache Tomcat 6</productname>. + <productname>JBoss Tools</productname>, as described in <xref linkend="sect-Developer_Guide-Getting_started_with_RichFaces-Creating_a_project_with_JBoss_Tools" />. </para> </listitem> <listitem> <para> - A web browser, such as <productname>Firefox 3.5</productname> or <productname>Internet Explorer 7</productname> + <productname>Maven</productname>, as described in <xref linkend="sect-Developer_Guide-Getting_started_with_RichFaces-Creating_a_project_with_Maven" />. </para> </listitem> </itemizedlist> <para> - RichFaces supports additional products not listed here. Refer to <xref linkend="sect-Component_Reference-RichFaces_overview-Full_technical_requirements" /> for a full list of technical requirements and supported envrionments, browsers, and tools. + Other environments, such as <productname>Idea</productname> or <productname>NetBeans</productname>, could also be used for RichFaces development, but are not detailed in this book. </para> - </section> <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Setting_up_RichFaces"> @@ -56,13 +71,50 @@ <step> <title>Download RichFaces archive</title> <para> - Download RichFaces from the JBoss RichFaces Downloads area at <ulink url="http://www.jboss.org/richfaces/download.html">http://ww...;. The binary files (available in <filename class="extension">.bin.zip</filename> or <filename class="extension">.bin.tar.gz</filename> archives) contain a compiled, ready-to-use version of RichFaces with a set of basic skins. + Download RichFaces from the JBoss RichFaces Downloads area at <ulink url="http://www.jboss.org/richfaces/download.html">http://ww...;. The binary files (available in <filename class="extension">.bin.zip</filename> or <filename class="extension">.bin.tar.gz</filename> archives) contain the following: </para> + <itemizedlist> + <listitem> + <para> + compiled, ready-to-use Java Archives (<acronym>JAR</acronym> files) of the RichFaces libraries + </para> + </listitem> + <listitem> + <para> + library source JAR files + </para> + </listitem> + <listitem> + <para> + documentation, including Java documentation and JavaScript documentation + </para> + </listitem> + <listitem> + <para> + archetypes + </para> + </listitem> + <listitem> + <para> + example source code + </para> + </listitem> + </itemizedlist> + <!-- TODO not in Final <stepalternatives> <step> + <title>Using the Component Development Kit (<acronym>CDK</acronym>) distribution</title> + <para> + Instead of using the standard distribution, you could download the distribution that includes the Component Development Kit (<acronym>CDK</acronym>). This distribution provides a tool for creating and developing new components using the RichFaces framework. + </para> + </step> + </stepalternatives> + --> + <stepalternatives> + <step> <title>Compiling from source</title> <para> - Instead of downloading the pre-compiled binaries, you can download the source files and compile them yourself. Refer to <xref linkend="sect-Component_Reference-RichFaces_overview-Compiling_from_source_code" /> for further instructions. + Instead of using the pre-compiled binaries, you can compile the source files yourself. Refer to <xref linkend="sect-Component_Reference-RichFaces_overview-Compiling_from_source_code" /> for further instructions. </para> </step> </stepalternatives> @@ -80,67 +132,32 @@ <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Creating_a_project_with_JBoss_Tools"> <title>Creating a project with <productname>JBoss Tools</productname></title> <para> - Follow the procedure in this section to create a new RichFaces application with <productname>JBoss Tools</productname>. + Follow the procedure in this section to create a new RichFaces application with <productname>JBoss Tools</productname> Ensure you are using the latest version of <productname>JBoss Tools</productname>. </para> <procedure> <step id="step-Developer_Guide-Creating_a_project-Create_a_new_project"> <title>Create a new project</title> <para> - Create a new project based on the JSF 2 environment. In <productname>JBoss Tools</productname>, select <menuchoice><guimenu>File</guimenu><guimenu>New</guimenu><guimenuitem>JSF Project</guimenuitem></menuchoice> from the menu. Name the project, select <guilabel>JSF 2</guilabel> from the <guilabel>JSF Environment</guilabel> drop-down box, and click the <guibutton>Finish</guibutton> button to create the project. + Create a new project based on the JSF 2 environment using the RichFaces 4 template. In <productname>JBoss Tools</productname>, select <menuchoice><guimenu>File</guimenu><guimenu>New</guimenu><guimenuitem>JSF Project</guimenuitem></menuchoice> from the menu. Name the project, select <guilabel>JSF 2 + RichFaces 4</guilabel> from the <guilabel>JSF Environment</guilabel> drop-down box, and click the <guibutton>Finish</guibutton> button to create the project. </para> + <para> + If necessary, update the JSF 2 JAR files to the latest versions. + </para> </step> <step id="step-Developer_Guide-Creating_a_project-Add_the_RichFaces_libraries_to_the_project"> <title>Add the RichFaces libraries to the project</title> <para> Add <filename>core-ui.jar</filename>, <filename>richfaces-api.jar</filename>, and <filename>richfaces-impl.jar</filename> into your project by copying them from the location where you unzipped the RichFaces archive to the <filename>WebContent/WEB-INF/lib/</filename> directory of your project in <application>JBoss Tools</application>. </para> - <!-- - <note> - <title>Other required libraries</title> - <para> - RichFaces also requires the following libraries to be referenced in your project. Typically they are already included when creating a JSF project in <application>JBoss Tools</application>. - </para> - <itemizedlist> - <listitem> - <para> - <filename>commons-beanutils.jar</filename> - </para> - </listitem> - <listitem> - <para> - <filename>commons-collections.jar</filename> - </para> - </listitem> - <listitem> - <para> - <filename>commons-digester.jar</filename> - </para> - </listitem> - <listitem> - <para> - <filename>commons-logging.jar</filename> - </para> - </listitem> - <listitem> - <para> - <filename>jhighlight.jar</filename> - </para> - </listitem> - </itemizedlist> - </note> - --> </step> <step id="step-Developer_Guide-Creating_a_project-Reference_the_tag_libraries"> <title>Reference the tag libraries</title> <para> The RichFaces tag libraries need to be referenced on each XHTML page in your project: </para> - -<programlisting language="XML" role="XML">&lt;ui:composition xmlns="http://www.w3.org/1999/xhtml" - xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:a4j="http://richfaces.org/a4j" +<programlisting language="XML" role="XML">&lt;ui:composition xmlns:a4j="http://richfaces.org/a4j" xmlns:rich="http://richfaces.org/rich"&gt; - ... + ... &lt;/ui:composition&gt; </programlisting> </step> @@ -172,7 +189,7 @@ <section id="sect-Component_Using_RichFaces_with_Maven-Setting_up_Maven"> <title>Setting up <productname>Maven</productname></title> <para> - <productname>Maven</productname> can be downloaded and installed from Apache's website at <ulink url="http://maven.apache.org/download.html">http://maven.apa...;. Version 2.2.1 is recommended. + <productname>Maven</productname> can be downloaded and installed from Apache's website at <ulink url="http://maven.apache.org/download.html">http://maven.apa...;. Due to the use of dependency importing, <productname>Maven</productname> version 2.0.9 or above is required. </para> <para> Once <productname>Maven</productname> has been installed, no further configuration is required to begin building Maven projects. @@ -184,7 +201,7 @@ A Maven archetype is a template for creating projects. <productname>Maven</productname> uses an archetype to generate a directory structure and files for a particular project, as well as creating <filename>pom.xml</filename> files that contain build instructions. </para> <para> - The RichFaces Component Development Kit includes a Maven archetype named <filename>richfaces-archetype-simpleapp</filename> for generating the basic structure and requirements for a RichFaces application project. Maven can obtain the archetype from the JBoss repository at <filename>https://repository.jboss.org/nexus/content/groups/public/<...;. The archetype is also included with the RichFaces source code. Follow the procedure in this section to generate a new Maven-based RichFaces project using the archetype. + The RichFaces Component Development Kit includes a Maven archetype named <filename>richfaces-archetype-simpleapp</filename> for generating the basic structure and requirements for a RichFaces application project. Maven can obtain the archetype from the JBoss repository at <filename>https://repository.jboss.org/nexus/content/groups/public/<...;. The archetype is also included with the RichFaces source code in the <filename>archetypes</filename> directory. Follow the procedure in this section to generate a new Maven-based RichFaces project using the archetype. </para> <procedure> <step id="step-Developer_Guide-Using_RichFaces_with_Maven-Add_required_repositories"> @@ -197,10 +214,12 @@ <para> The profile then needs to be activated in the <sgmltag>&lt;activeProfiles&gt;</sgmltag> element: </para> - <programlisting language="XML" role="XML">&lt;activeProfiles&gt; &lt;activeProfile&gt;jboss-public-repository&lt;/activeProfile&gt; &lt;/activeProfiles&gt;</programlisting> + <para> + For further details, refer to the <citetitle>JBoss RichFaces Wiki</citetitle>. + </para> </step> <step id="step-Developer_Guide-Using_RichFaces_with_Maven-Generate_the_project_from_the_archetype"> <title>Generate the project from the archetype</title> @@ -254,31 +273,14 @@ │ └── <filename>template.xhtml</filename> └── <filename>WEB-INF</filename> ├── <filename>faces-config.xml</filename> - └── <filename>web.xml</filename><!-- - └── <filename>test</filename> - └── <filename>java</filename> - └── <filename>org</filename> - └── <filename>docs</filename> - └── <filename>richfaces</filename> - └── <filename>BeanTest.java</filename>--></screen> + └── <filename>web.xml</filename></screen> </step> <step id="step-Developer_Guide-Using_RichFaces_with_Maven-Add_dependencies"> - <!-- Remove this step for Enterprise documentation --> <title>Add test dependencies (optional)</title> <para> - Your root directory of your project contains a project descriptor file, <filename>pom.xml</filename>. -<!-- - To add RichFaces libraries to your project, edit the project descriptor to add dependencies to the <sgmltag>&lt;dependencies&gt;</sgmltag> element as follows: + Your root directory of your project contains a project descriptor file, <filename>pom.xml</filename>. If you wish to include modules for test-driven JSF development, add any dependencies for the tests to the <filename>pom.xml</filename> file. For full details on how to use the <productname>jsf-test</productname> project, refer to <ulink url="http://community.jboss.org/docs/DOC-13155">http://commu...;. </para> - - <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/prog-Developer_Guide-Using_RichFaces_with_Maven-Add_dependencies.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - - <para> ---> - If you wish to include modules for test-driven JSF development, add any dependencies for the tests to the <filename>pom.xml</filename> file. For full details on how to use the <productname>jsf-test</productname> project, refer to <ulink url="http://community.jboss.org/docs/DOC-13155">http://commu...;. - </para> </step> <!-- @@ -320,30 +322,21 @@ <para> To install the plug-in, choose <menuchoice><guimenu>Help</guimenu><guimenuitem>Install New Software</guimenuitem></menuchoice> from the menu. Type <literal>Maven</literal> to locate the <guilabel>Maven Integration for Eclipse Update Site</guilabel> entry, then type <literal>Maven</literal> in the filter to show the available plug-ins. Follow the prompts to install the <guilabel>Maven Integration for Eclipse</guilabel> plug-in. </para> - <!-- + <para> + With the plug-in installed, open the importing wizard by choosing <menuchoice><guimenu>File</guimenu><guimenuitem>Import</guimenuitem></menuchoice> from the menu. Select <menuchoice><guimenu>Maven</guimenu><guimenuitem>Existing Maven Projects</guimenuitem></menuchoice> as the import source and choose the <filename>pom.xml</filename> file for your project. + </para> <stepalternatives> <step> <title>Using <application>Maven</application> to prepare the project for <application>Eclipse</application></title> <para> - Enter the following command in the root directory of the project: + Alternatively, the project can be prepared using Maven then imported normally. Enter the following command in the root directory of the project: </para> <screen>mvn eclipse:eclipse -DdownloadSources=true -Dwtpversion=2.0</screen> <para> The command generates the required <application>Eclipse</application> project files. You can then import the project into <application>Eclipse</application> and <application>JBoss Tools</application> through the importing wizard by choosing <menuchoice><guimenu>File</guimenu><guimenuitem>Import</guimenuitem></menuchoice> from the menu. Select <menuchoice><guimenu>General</guimenu><guimenuitem>Existing Projects into Workspace</guimenuitem></menuchoice> as the import source and choose the root directory for your project. </para> </step> - <step> - <title>Using the <productname>M2Eclipse</productname> plug-in</title> - <para> - Alternatively, you can import a <application>Maven</application> project into <application>Eclipse</application> and <application>JBoss Tools</application> using the <productname>M2Eclipse</productname> plug-in. ---> - <para> - With the plug-in installed, open the importing wizard by choosing <menuchoice><guimenu>File</guimenu><guimenuitem>Import</guimenuitem></menuchoice> from the menu. Select <menuchoice><guimenu>Maven</guimenu><guimenuitem>Existing Maven Projects</guimenuitem></menuchoice> as the import source and choose the <filename>pom.xml</filename> file for your project. - </para> -<!-- - </step> </stepalternatives> ---> </step> <!-- <step id="step-Developer_Guide-Using_RichFaces_with_Maven-Add_tag_library_references"> @@ -363,10 +356,17 @@ </section> <section id="sect-Developer_Guide-Getting_started_with_RichFaces-Using_RichFaces_in_existing_JSF2_projects"> - <title>Using RichFaces in existing JSF2 projects</title> + <title>Using RichFaces in existing JSF 2 projects</title> <para> - RichFaces can be added to existing JSF2 projects by adding references to the new RichFaces libraries. Refer to <xref linkend="step-Developer_Guide-Creating_a_project-Add_the_RichFaces_libraries_to_the_project" /> and <xref linkend="step-Developer_Guide-Creating_a_project-Reference_the_tag_libraries" /> in <xref linkend="sect-Developer_Guide-Getting_started_with_RichFaces-Creating_a_project_with_JBoss_Tools" /> for details. + RichFaces can be added to existing JSF 2 projects by adding the new RichFaces libraries. Refer to <xref linkend="step-Developer_Guide-Creating_a_project-Add_the_RichFaces_libraries_to_the_project" /> and <xref linkend="step-Developer_Guide-Creating_a_project-Reference_the_tag_libraries" /> in <xref linkend="sect-Developer_Guide-Getting_started_with_RichFaces-Creating_a_project_with_JBoss_Tools" /> for details. </para> + + <note> + <title>Application-level settings</title> + <para> + In RichFaces 4, it is not necessary to add any extra settings to the <filename>web.xml</filename> or <filename>config.xml</filename> settings files to use the framework. + </para> + </note> </section> </chapter> Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Introduction.xml =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Introduction.xml 2011-03-20 21:51:14 UTC (rev 22276) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Introduction.xml 2011-03-21 06:45:02 UTC (rev 22277) @@ -4,26 +4,16 @@ <chapter id="chap-Developer_Guide-Introduction"> <title>Introduction</title> <para> - The RichFaces framework is a rich component library for JavaServer Faces (<acronym>JSF</acronym>). It allows integration of Ajax capabilities into enterprise web application development without needing to use JavaScript. + The RichFaces framework is a rich component library for JavaServer Faces (<acronym>JSF</acronym>). The framework extends the JSF framework's Ajax capabilities with advanced features for enterprise web application development. </para> <para> - RichFaces leverages several parts of the JSF2 framework including lifecycle, validation, conversion facilities, and management of static and dynamic resources. The RichFaces framework includes components with built-in Ajax support and a customizable look-and-feel that can be incorporated into JSF applications. + RichFaces leverages several parts of the JSF 2 framework including lifecycle, validation, conversion facilities, and management of static and dynamic resources. The RichFaces framework includes components with built-in Ajax support and a customizable look-and-feel that can be incorporated into JSF applications. </para> <para> RichFaces provides a number of advantages for enterprise web application development: <itemizedlist> <listitem> <para> - Build on the benefits of JavaServer Faces with support for Ajax. RichFaces is fully integrated into the JSF lifecycle: it uses the action and value change listeners, and invokes server-side validators and converters during the Ajax request-response cycle. - </para> - </listitem> - <listitem> - <para> - Extend Ajax capability in existing JSF applications. The core Ajax library (<classname>a4j</classname>) adds extra Ajax functionality into existing pages, such that additional JavaScript code is unnecessary and existing components do not need to be replaced with Ajax ones. RichFaces enables page-wide Ajax support instead of the traditional component-wide support, and events can be defined on the page for invoking an Ajax requests and JSF Component Tree synchronization. - </para> - </listitem> - <listitem> - <para> Create complex application views using out-of-the-box components. The RichFaces user interface (<acronym>UI</acronym>) library (<classname>rich</classname>) contains components for adding rich interactive features to JSF applications. It extends the RichFaces framework to include a large set of Ajax-enabled components that come with extensive skinning support. Additionally, the RichFaces framework is designed to be used seamlessly with other 3d-party libraries on the same page, so you have more options for developing applications. </para> </listitem> @@ -34,19 +24,14 @@ </listitem> <listitem> <para> - Package dynamic resources with application Java classes. Ajax functionality in RichFaces extends support for the management of different resources, such as pictures, JavaScript code, and CSS stylesheets. The resource framework makes it possible to pack dynamic resources along with the code for any custom components. + Generate binary resources on the fly. Extensions to JSF 2 resource handlind facilities can generate images, sounds, <application>Microsoft Excel</application> spreadsheets, and more during run-time. </para> </listitem> <listitem> <para> - Generate binary resources on the fly. The resource framework can generate images, sounds, <application>Microsoft Excel</application> spreadsheets, and more during run-time. + Create a modern rich user-interface with skinning technology. RichFaces provides a skinning feature that allows you to define and manage different color schemes and other parameters of the look and feel. It is possible to access the skin parameters from page code during run-time. RichFaces comes packaged with a number of skins to get you started, but you can also easily create your own customized skins too. </para> </listitem> - <listitem> - <para> - Create a modern rich user-interface with skinning technology. RichFaces provides a skinning feature that allows you to define and manage different color schemes and other parameters of the look and feel. It is possible to access the skin parameters from JSP code and Java code during run-time. RichFaces comes packaged with a number of skins to get you started, but you can also easily create your own customized skins too. - </para> - </listitem> </itemizedlist> </para> </chapter> Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-RichFaces_overview.xml =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-RichFaces_overview.xml 2011-03-20 21:51:14 UTC (rev 22276) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-RichFaces_overview.xml 2011-03-21 06:45:02 UTC (rev 22277) @@ -3,17 +3,14 @@ ]> <chapter id="chap-Developer_Guide-RichFaces_overview"> <title>RichFaces overview</title> - <!-- In development notification --> - <important> - <title>Documentation in development</title> - <para> - Some concepts covered in this chapter may refer to the previous version of <productname>Richfaces</productname>, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date. - </para> - </important> <para> - The RichFaces framework is a component library which enhances JSF Ajax capabilities, such that you don't need to write any extra JavaScript code or replace any existing components with new Ajax widgets. RichFaces also enables page-wide Ajax support instead of the traditional component-wide support. Events can be defined on pages that invoke Ajax requests. After an Ajax request, the areas of a page that are synchronized with the JSF Component Tree can themselves change data on the server according to events fired on the client. + Read this chapter for technical details on the RichFaces framework. </para> + <!-- <para> + The RichFaces framework is a component library which enhances JSF Ajax capabilities. RichFaces also enables page-wide Ajax support instead of the traditional component-wide support. Events can be defined on pages that invoke Ajax requests. After an Ajax request, the areas of a page that are synchronized with the JSF Component Tree can themselves change data on the server according to events fired on the client. + </para> + <para> <xref linkend="figu-Developer_Guide-RichFaces_overview-Request_processing_flow" /> illustrates how requests are processed in the RichFaces framework. </para> <figure id="figu-Developer_Guide-RichFaces_overview-Request_processing_flow"> @@ -35,6 +32,7 @@ <para> Using JSF tags, RichFaces allows different parts of a JSF page to be updated with an Ajax request. JSF pages using RichFaces do not change from "regular" JSF pages, and additional JavaScript code is not required. </para> + --> <section id="sect-Component_Reference-RichFaces_overview-Full_technical_requirements"> <title>Full technical requirements</title> <para> @@ -43,49 +41,19 @@ <section id="sect-Component_Reference-RichFaces_overview-Server_requirements"> <title>Server requirements</title> <para> - A Java application server or servlet container is required for running RichFaces applications. RichFaces supports the following servers: + RichFaces 4 requires either of the following server technologies: </para> <itemizedlist> <listitem> <para> - Apache Tomcat 6.0 and higher + An application server compliant with Java Platform, Enterprise Edition 5 or 6 (<acronym>JEE5</acronym> or <acronym>JEE6</acronym>), such as <productname>JBoss Application Server 6</productname>. </para> </listitem> <listitem> <para> - BEA WebLogic 9.1 &#8211; 10.0 + A major servlet container, such as <productname>Jetty 6</productname> or <productname>Apache Tomcat 6</productname>. </para> </listitem> - <listitem> - <para> - JBoss 4.2 and higher - </para> - </listitem> - <listitem> - <para> - Geronimo 2.0 and higher - </para> - </listitem> - <listitem> - <para> - Glassfish (J2EE 5 and JEE 6) - </para> - </listitem> - <listitem> - <para> - Resin 3.1 - </para> - </listitem> - <listitem> - <para> - Sun Application Server 9 (J2EE 1.5) - </para> - </listitem> - <listitem> - <para> - Websphere 7.0 and higher - </para> - </listitem> </itemizedlist> </section> <section id="sect-Component_Reference-RichFaces_overview-Client_requirements"> @@ -97,17 +65,17 @@ <title>Linux environments</title> <listitem> <para> - Firefox 3.0 and higher + <productname>Firefox 3.0</productname> and higher </para> </listitem> <listitem> <para> - Google Chrome + <productname>Google Chrome</productname> </para> </listitem> <listitem> <para> - Opera 9.5 and higher + <productname>Opera 9.5</productname> and higher </para> </listitem> </itemizedlist> @@ -115,17 +83,17 @@ <title>Mac OS environments</title> <listitem> <para> - Firefox 3.5 and higher + <productname>Firefox 3.5</productname> and higher </para> </listitem> <listitem> <para> - Google Chrome + <productname>Google Chrome</productname> </para> </listitem> <listitem> <para> - Safari 3.0 and higher + <productname>Safari 3.0</productname> and higher </para> </listitem> </itemizedlist> @@ -133,27 +101,27 @@ <title>Microsoft Windows environments</title> <listitem> <para> - Firefox 3.0 and higher + <productname>Firefox 3.0</productname> and higher </para> </listitem> <listitem> <para> - Google Chrome + <productname>Google Chrome</productname> </para> </listitem> <listitem> <para> - Internet Explorer 7.0 and higher + <productname>Internet Explorer 7.0</productname> and higher </para> </listitem> <listitem> <para> - Opera 9.5 and higher + <productname>Opera 9.5</productname> and higher </para> </listitem> <listitem> <para> - Safari 3.0 and higher + <productname>Safari 4.0</productname> and higher </para> </listitem> </itemizedlist> @@ -185,28 +153,21 @@ <para> RichFaces supports the following JSF implementations and frameworks: <itemizedlist> - <!-- <listitem> <para> - Facelets 1.1.1 &#8211; 1.2 + <productname>MyFaces 2</productname> and higher </para> </listitem> - --> <listitem> <para> - MyFaces 2 and higher + <productname>Seam 3</productname> and higher </para> </listitem> <listitem> <para> - Seam 2 and higher + <productname>Mojara 2</productname> and higher </para> </listitem> - <listitem> - <para> - Sun JSF-RI 2 and higher - </para> - </listitem> </itemizedlist> </para> </listitem> @@ -219,12 +180,12 @@ <itemizedlist> <listitem> <para> - JBoss Tools 3.1 and higher + <productname>JBoss Tools 3.1</productname> and higher </para> </listitem> <listitem> <para> - Maven 2.1.0 and higher (2.2.1 recommended) + <productname>Maven 2.0.9</productname> and higher (2.2.1 recommended) </para> </listitem> </itemizedlist> @@ -253,12 +214,17 @@ </listitem> <listitem> <para> + Ajax Output + </para> + </listitem> + <listitem> + <para> Skins and Theming </para> </listitem> <listitem> <para> - RichFaces JavaScript Engine + RichFaces Ajax Extensions </para> </listitem> </itemizedlist> @@ -311,16 +277,23 @@ <section id="sect-Developer_Guide-Architecture-Ajax_Action_Components"> <title>Ajax Action Components</title> <para> - The RichFaces framework includes several Ajax Action Components: <sgmltag>&lt;a4j:commandButton&gt;</sgmltag>, <sgmltag>&lt;a4j:commandLink&gt;</sgmltag>, <sgmltag>&lt;a4j:poll&gt;</sgmltag>, <sgmltag>&lt;a4j:support&gt;</sgmltag>, and more. Use Ajax Action Components to send Ajax requests from the client side. + The RichFaces framework includes several Ajax Action Components and Submitting Bahaviors: <sgmltag>&lt;a4j:commandButton&gt;</sgmltag>, <sgmltag>&lt;a4j:commandLink&gt;</sgmltag>, <sgmltag>&lt;a4j:poll&gt;</sgmltag>, <sgmltag>&lt;a4j:ajax&gt;</sgmltag>, and more. Use Ajax Action Components to send Ajax requests from the client side. </para> </section> <section id="sect-Developer_Guide-Architecture-Ajax_Containers"> <title>Ajax Containers</title> <para> - <classname>AjaxContainer</classname> <remark>(name possibly changed in release)</remark> is an interface that describes an area on a JSF page that is decoded during an Ajax request. <classname>AjaxViewRoot</classname> and <classname>AjaxRegion</classname> are implementations of this interface. + <classname>AjaxContainer</classname> is an interface that marks part of the JSF tree that is decoded during an Ajax request. It only marks the JSF tree if the component or behavior sending the request does not explicitly specify an alternative. <classname>AjaxRegion</classname> is an implementation of this interface. </para> </section> + + <section id="sect-Developer_Guide-Architecture-Ajax_Output"> + <title>Ajax Output</title> + <para> + <classname>AjaxContainer</classname> is an interface that marks part of the JSF tree that will be updated and rendered on the client for every Ajax request. It only marks the JSF tree if the component or behavior sending the request does not explicitly turn off automatic updates. + </para> + </section> <section id="sect-Developer_Guide-Architecture-Skins_and_theming"> <title>Skins and theming</title> @@ -332,10 +305,10 @@ </para> </section> - <section id="sect-Developer_Guide-Architecture-RichFaces_JavaScript_Engine"> - <title>RichFaces JavaScript Engine</title> + <section id="sect-Developer_Guide-Architecture-RichFaces_Ajax_Extensions"> + <title>RichFaces Ajax Extensions</title> <para> - The RichFaces JavaScript Engine runs on the client side. It can update different areas on a JSF page based on an Ajax response. It is not necessary to use the JavaScript code directly, as it is available automatically. + The RichFaces Ajax Extensions plug in to the standard JSF 2 Ajax script facility. They extend the script facility with new features and options. </para> </section> @@ -344,27 +317,21 @@ <section id="sect-Developer_Guide-RichFaces_overview-Technologies"> <title>Technologies</title> <para> - RichFaces originated from the <emphasis>Ajax4jsf</emphasis> project, an open-source web application framework that added Ajax capabilities to the JavaServer Faces (<acronym>JSF</acronym>) framework. The RichFaces components were split into a separate commercial component library, then later both the Ajax4jsf and RichFaces libraries were re-combined under the RichFaces name. + RichFaces 4 features full JSF 2 integration and uses standard web application technologies such as JavaScript, <acronym>XML</acronym> (Extensible Markup Language), and <acronym>XHTML</acronym> (Extensible Hypertext Markup Language). </para> - <para> - RichFaces 4.0 features full JSF2 integration and uses standard web application technologies such as JavaScript, <acronym>XML</acronym> (Extensible Markup Language), and <acronym>XHTML</acronym> (Extensible Hypertext Markup Language). - </para> </section> <section id="sect-Developer_Guide-RichFaces_overview-Differences_between_JSF_and_RichFaces_mechanisms"> <title>Differences between <acronym>JSF</acronym> and RichFaces mechanisms</title> - <itemizedlist> - <listitem> - <para> - JavaServer Faces (<acronym>JSF</acronym>) declares render and execute processes on the client side, while RichFaces declares server-side definitions of lists. - </para> - </listitem> - <listitem> - <para> - RichFaces components uses their own renderers. In the <emphasis>Render Response Phase</emphasis>, the RichFaces framework makes a traversal of the component tree, calls its own renderer, and passes the result to the Faces Response. - </para> - </listitem> - </itemizedlist> + <para> + JavaServer Faces 2 evaluates Ajax options, such as <code>execute</code> and <code>render</code>, while rendering a page. This allows any parameters to be sent directly from the client side. + </para> + <para> + RichFaces evaluates the options when the current request is sent. This increases both the security of the data and the convenience for evaluating parameters. + </para> + <para> + For example, binding Ajax options to Java Bean properties in RichFaces allows you to evaluate the options dynamically for the current request, such as defining additional zones to render. Parameters changed manually on the client side will not influence the request processing. With JSF 2, the options have evaluated during the previous page rendering would need to be used. + </para> </section> <section id="sect-Developer_Guide-RichFaces_overview-Restrictions"> @@ -374,27 +341,19 @@ <itemizedlist> <listitem> <para> - Any Ajax framework should not append or delete elements on a page, but should instead replace them. For successful updates, an element with the same identifier as in the response must exist on the page. If it is necessary to append code to a page, include a placeholder for it (an empty element). - <!-- For the same reason, it is recommended that messages be placed in the <sgmltag>&lt;a4j:outputPanel&gt;</sgmltag> component.--> + As with most Ajax frameworks, you should not attempt to append or delete elements on a page using RichFaces Ajax, but should instead replace them. As such, elements that are rendered conditionally should not be targeted in the <varname>render</varname> attributes for Ajax controls. For successful updates, an element with the same identifier as in the response must exist on the page. If it is necessary to append code to a page, include a placeholder for it (an empty element). </para> </listitem> <listitem> <para> - <sgmltag>&lt;f:verbatim&gt;</sgmltag> should not be used for self-rendered containers, since it is transient and not saved in the tree. + JSF 2 does not allow resources such as JavaScript or Cascading Style Sheets (<acronym>CSS</acronym>) to be added if the element requiring the resource is not initially present in the JSF tree. As such, components added to the tree via Ajax must have any required resources already loaded. In RichFaces, any components added to the JSF tree should have components with corresponding resources included on the main page initially. To facilitate this, components can use the <code>rendered="false"</code> setting to not be rendered on the page. </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. As such, a strict standards-compliant code for HTML and XHTML should be used, without skipping any required elements or attributes. Any necessary XML corrections are automatically made by the XML filter on the server, but unexpected effects can be produced through incorrect HTML code. + Switching RichFaces skins via Ajax during runtime should be avoided, as this requires all the stylesheets to be reloaded. </para> </listitem> - --> - <listitem> - <para> - The RichFaces <classname>ViewHandler</classname> puts itself in front of the Facelets <classname>ViewHandlers</classname> chain. - </para> - </listitem> </itemizedlist> </para> </section> @@ -402,35 +361,36 @@ <section id="sect-Component_Reference-RichFaces_overview-Compiling_from_source_code"> <title>Compiling from source code</title> <para> - The source code for the RichFaces framework can be downloaded and compiled manually rather than using the pre-compiled binaries. + The source code for the RichFaces framework can be compiled manually rather than using the pre-compiled binaries. </para> <procedure> <step> - <title>Download source code</title> + <title>Acquiring the source code</title> <stepalternatives> <step> <title>JBoss RichFaces Downloads area</title> <!-- Update download location in Enterprise docs, or remove this section altogether --> <para> - Download the source files (also available in <filename class="extension">.bin.zip</filename> or <filename class="extension">.bin.tar.gz</filename> archives) from the JBoss RichFaces Downloads area at <ulink url="http://www.jboss.org/richfaces/download.html">http://ww...;. + Download the RichFaces distribution as described in <xref linkend="sect-Developer_Guide-Getting_started_with_RichFaces-Setting_up_RichFaces" />. The distribution bundles contain the full RichFaces source code. </para> </step> <step> <title>Anonymous SVN repository</title> <!-- Remove SVN details in Enterprise docs --> <para> - Alternatively, the source files can be downloaded from the anonymous SVN repository at <ulink url="http://anonsvn.jboss.org/repos/richfaces/root/">http://... using the following command: + Alternatively, the source files can be checked out from the anonymous SVN repository at <ulink url="http://anonsvn.jboss.org/repos/richfaces/branches/4.0.X/"&... using the following command: </para> - <screen>svn co http://anonsvn.jboss.org/repos/richfaces/root/</screen> + <screen>svn co http://anonsvn.jboss.org/repos/richfaces/branches/4.0.X/</screen> </step> </stepalternatives> </step> <step> <title>Unzip archive</title> <para> - Create a new directory named <filename>RichFaces</filename>, then unzip the archive containing the source code there. + If using the downloaded distribution, create a new directory named <filename>RichFaces</filename>, then unzip the archive containing the source code there. </para> </step> + <!-- <step> <title>Configure <productname>Maven</productname> with JBoss developer settings</title> <para> @@ -466,6 +426,7 @@ </varlistentry> </variablelist> </step> + --> <step> <title>Compile using <productname>Maven</productname></title> <para> @@ -561,23 +522,30 @@ <itemizedlist> <listitem> <para> - <filename>ui/assembly/target/dist/richfaces-ui-<replaceable>version</replaceable>-SNAPSHOT.jar</filename> + <filename>/ui/dist/richfaces-components-api/target/richfaces-components-api-<replaceable>version</replaceable>-SNAPSHOT.jar</filename> </para> </listitem> <listitem> <para> - <filename>framework/api/target/richfaces-api-<replaceable>version</replaceable>-SNAPSHOT.jar</filename> + <filename>/ui/dist/richfaces-components-ui/target/richfaces-components-ui-<replaceable>version</replaceable>-SNAPSHOT.jar</filename> </para> </listitem> <listitem> <para> - <filename>framework/impl/target/richfaces-impl-<replaceable>version</replaceable>-SNAPSHOT.jar</filename> + <filename>/core/api/target/richfaces-core-api-<replaceable>version</replaceable>-SNAPSHOT.jar</filename> </para> </listitem> + <listitem> + <para> + <filename>/core/impl/target/richfaces-core-impl-<replaceable>version</replaceable>-SNAPSHOT.jar</filename> + </para> + </listitem> </itemizedlist> + <!-- TODO check build location <para> If Maven built the framework using the <command>-P release</command> option, the distribution package containing all three compiled libraries and reference documentation is located at <filename>ui/assembly/target/dist/richfaces-ui-<replaceable>version</replaceable>-SNAPSHOT-bin.zip</filename>. </para> + --> </step> </procedure> <para> Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Skinning_and_theming.xml =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Skinning_and_theming.xml 2011-03-20 21:51:14 UTC (rev 22276) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Skinning_and_theming.xml 2011-03-21 06:45:02 UTC (rev 22277) @@ -3,33 +3,26 @@ ]> <chapter id="chap-Developer_Guide-Skinning_and_theming"> <title>Skinning and theming</title> - <!-- In development notification --> - <important> - <title>Documentation in development</title> - <para> - Some concepts covered in this chapter may refer to the previous version of <productname>Richfaces</productname>, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date. - </para> - </important> <para> Read this chapter for a guide to skinning and theming RichFaces applications, including how to implement themes, and details on customizing and extending skins. </para> <section id="sect-Developer_Guide-Skinning_and_theming-What_are_skins"> <title>What are skins?</title> <para> - Application skins are used with the RichFaces framework to change the appearance of an application through setting the colors and decoration of controls and components. Typically the appearance of web applications is handled through the <acronym>CSS</acronym> (Cascading Style Sheet) files associated with the application, but skinning allows the settings in a CSS file to be abstracted and easily edited. Using skins avoids repetitive coding and duplication in CSS files through the use of style variables and generalization. CSS files are not completely replaced: skins work as a high-level extension to standard CSS. + Application skins are used with the RichFaces framework to change the appearance of an application through setting the colors and decoration of controls and components. Typically the appearance of web applications is handled through the <acronym>CSS</acronym> (Cascading Style Sheet) files associated with the application, but skinning allows the settings in a CSS file to be abstracted and easily edited. Skins consist of a small, generalized set of font and color parameters that can be applied to multiple different styles. This avoids repetitive coding and duplication in CSS files. CSS files are not completely replaced: skins work as a high-level extension to standard CSS. </para> <para> Each skin has a set of <varname>skin-parameters</varname>, which are used to define the theme palette and other elements of the user interface. These parameters work together with regular CSS declarations, and can be referred to from within CSS using JavaServer Faces Expression Language (<acronym>EL</acronym>). </para> <para> - The skinning feature of RichFaces also allows themes to be changed at runtime, so users can personalize an application's appearance. + The skinning feature of RichFaces also allows skins to be changed at runtime, so users can personalize an application's appearance on the fly. </para> </section> <section id="sect-Developer_Guide-Skinning_and_theming-Using_skins"> <title>Using skins</title> <para> - RichFaces includes a number of predefined skins. These skins can be used in RichFaces web applications by specifying the skin name in the <varname>org.richfaces.SKIN</varname> context parameter in the <filename>web.xml</filename> settings file. The predefined skins are as follows: + RichFaces includes a number of predefined skins. These skins can be used in RichFaces web applications by specifying the skin name in the <varname>org.richfaces.skin</varname> context parameter in the <filename>web.xml</filename> settings file. The predefined skins are as follows: </para> <itemizedlist> <listitem> @@ -77,6 +70,7 @@ <literal>deepMarine</literal> </para> </listitem> + <!-- <listitem> <para> <literal>laguna</literal> @@ -92,6 +86,7 @@ <literal>glassX</literal> </para> </listitem> + --> </itemizedlist> <para> To add one of these skins to your application, add the <literal>org.richfaces.SKIN</literal> context parameter to the <filename>web.xml</filename> configuration file: @@ -105,7 +100,7 @@ <section id="sect-Developer_Guide-Skinning_and_theming-Customizing_skins"> <title>Customizing skins</title> <para> - RichFaces skins are designed to use a combination of styling elements. Themes for components can be applied using any of the following style classes: + RichFaces skins are implemented using the following three-level scheme: </para> <variablelist> <varlistentry> @@ -139,44 +134,55 @@ Using any component, such as a panel, without specifying a <varname>styleClass</varname> will use the default skin parameters for that component. </para> -<programlisting language="XML" role="XML">&lt;rich:panel&gt;...&lt;/rich:panel&gt;</programlisting> +<programlisting language="XML" role="XML">&lt;rich:panel&gt;This is a panel without a header&lt;/rich:panel&gt;</programlisting> <para> When rendered for display, the panel consists of two HTML elements: a wrapper <sgmltag>&lt;div&gt;</sgmltag> element and a <sgmltag>&lt;div&gt;</sgmltag> element for the body of the panel. The wrapper element for a panel without a specified <varname>styleClass</varname> is rendered as follows: </para> - -<programlisting language="XML" role="XML">&lt;div class="dr-pnl rich-panel"&gt; - ... -&lt;/div&gt;</programlisting> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/prog-Developer_Guide-Using_skins-Rendered_panel.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - <literal>dr-pnl</literal> refers to a CSS class specified in the framework. The CSS class uses skin parameters for generic theme styles: + <classname>rf-p</classname> and <classname>rf-p-b</classname> refer to CSS classes specified in the framework. The CSS classes use skin parameters for generic theme styles: </para> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/prog-Developer_Guide-Using_skins-Panel_styles.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <itemizedlist> <listitem> <para> - The <varname>background-color</varname> CSS class attribute is defined by the <literal>generalBackgroundColor</literal> skin parameter. + The <property>background-color</property> CSS class attribute is defined by the <parameter>generalBackgroundColor</parameter> skin parameter. </para> </listitem> <listitem> <para> - The <varname>border-color</varname> CSS class attribute is defined by the <literal>panelBorderColor</literal> skin parameter. + The <property>color</property> CSS class attribute is defined by the <parameter>panelBorderColor</parameter> skin parameter. </para> </listitem> </itemizedlist> <para> - Changing the definitions for <literal>generalBackgroundColor</literal> or <literal>panelBorderColor</literal> in the skin will cause all panels in the application to change. + To customize the panel appearance according to the three-level scheme, adjust the styles according to the following approach: </para> - <para> - If a <varname>styleClass</varname> attribute is used, the specified style class is applied to the component, which could extend or override the default styles. - </para> - -<programlisting language="XML" role="XML">&lt;rich:panel styleClass="customClass"&gt;...&lt;/rich:panel&gt;</programlisting> - <para> - The <literal>customClass</literal> style is added to the CSS, and is applied to the component when it is rendered for display: - </para> - -<programlisting language="XML" role="XML">&lt;div class="dr-pnl rich-panel customClass"&gt; - ... + <procedure> + <step> + <para> + Change the definitions for the <parameter>generalBackgroundColor</parameter> or <parameter>panelBorderColor</parameter> parameters in the skin. This will cause all panels in the application to change to the new settings. + </para> + </step> + <step> + <para> + Redefine the <classname>rf-p</classname> class in the application CSS. This will also cause all panels in the application to change to the new settings, though the skin itself has not been altered. Any properties not mapped to skin parameters should be redefined in this way. + </para> + </step> + <step> + <para> + Specify a different <varname>styleClass</varname> attribute to style the individual component. If a <varname>styleClass</varname> attribute is used, the specified style class is applied to the component, which could extend or override the default styles. + </para> + <programlisting language="XML" role="XML">&lt;rich:panel styleClass="customClass"&gt;...&lt;/rich:panel&gt;</programlisting> + <para> + The <literal>customClass</literal> style is added to the CSS, and is applied to the component when it is rendered for display: + </para> +<programlisting language="XML" role="XML">&lt;div class="rf-p customClass"&gt; + ... &lt;/div&gt;</programlisting> + </step> + </procedure> + </example> </section> @@ -200,273 +206,273 @@ </thead> <tbody> <row> - <entry><varname> + <entry><parameter> headerBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #BED6F8 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> headerGradientColor - </varname></entry> + </parameter></entry> <entry><literal> #F2F7FF </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> headTextColor - </varname></entry> + </parameter></entry> <entry><literal> #000000 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> headerWeightFont - </varname></entry> + </parameter></entry> <entry><literal> bold </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> generalBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #FFFFFF </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> generalTextColor - </varname></entry> + </parameter></entry> <entry><literal> #000000 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> generalSizeFont - </varname></entry> + </parameter></entry> <entry><literal> 11px </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> generalFamilyFont - </varname></entry> + </parameter></entry> <entry><literal> Arial, Verdana, sans-serif </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> controlTextColor - </varname></entry> + </parameter></entry> <entry><literal> #000000 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> controlBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #ffffff </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> additionalBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #ECF4FE </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> shadowBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #000000 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> shadowOpacity - </varname></entry> + </parameter></entry> <entry><literal> 1 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> panelBorderColor - </varname></entry> + </parameter></entry> <entry><literal> #BED6F8 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> subBorderColor - </varname></entry> + </parameter></entry> <entry><literal> #ffffff </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tabBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #C6DEFF </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tabDisabledTextColor - </varname></entry> + </parameter></entry> <entry><literal> #8DB7F3 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> trimColor - </varname></entry> + </parameter></entry> <entry><literal> #D6E6FB </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tipBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #FAE6B0 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tipBorderColor - </varname></entry> + </parameter></entry> <entry><literal> #E5973E </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> selectControlColor - </varname></entry> + </parameter></entry> <entry><literal> #E79A00 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> generalLinkColor - </varname></entry> + </parameter></entry> <entry><literal> #0078D0 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> hoverLinkColor - </varname></entry> + </parameter></entry> <entry><literal> #0090FF </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> visitedLinkColor - </varname></entry> + </parameter></entry> <entry><literal> #0090FF </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> headerSizeFont - </varname></entry> + </parameter></entry> <entry><literal> 11px </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> headerFamilyFont - </varname></entry> + </parameter></entry> <entry><literal> Arial, Verdana, sans-serif </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tabSizeFont - </varname></entry> + </parameter></entry> <entry><literal> 11px </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tabFamilyFont - </varname></entry> + </parameter></entry> <entry><literal> Arial, Verdana, sans-serif </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> buttonSizeFont - </varname></entry> + </parameter></entry> <entry><literal> 11px </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> buttonFamilyFont - </varname></entry> + </parameter></entry> <entry><literal> Arial, Verdana, sans-serif </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tableBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #FFFFFF </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tableFooterBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #cccccc </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tableSubfooterBackgroundColor - </varname></entry> + </parameter></entry> <entry><literal> #f1f1f1 </literal></entry> </row> <row> - <entry><varname> + <entry><parameter> tableBorderColor - </varname></entry> + </parameter></entry> <entry><literal> #C0C0C0 </literal></entry> @@ -489,28 +495,47 @@ </step> <step> <title>Reference the skin bean</title> - <para>Use <acronym>EL</acronym> (Expression Language) to reference the skin bean from the <filename>web.xml</filename> settings file.</para> + <para> + Add the <code>@ManagedBean</code> and <code>@SessionScoped</code> references to the class. + </para> + <stepalternatives> + <step> + <para> + Alternatively, use <acronym>EL</acronym> (Expression Language) to reference the skin bean from the <filename>web.xml</filename> settings file. + </para> <programlisting language="XML" role="XML">&lt;context-param&gt; - &lt;param-name&gt;org.richfaces.SKIN&lt;/param-name&gt; + &lt;param-name&gt;org.richfaces.skin&lt;/param-name&gt; &lt;param-value&gt;#{skinBean.skin}&lt;/param-value&gt; &lt;/context-param&gt;</programlisting> + </step> + </stepalternatives> </step> <step> <title>Set initial skin</title> <para> - The application needs an initial skin to display before the user chooses an alternative skin. The initial skin is specified in the <filename>web.xml</filename> configuration file. + The application needs an initial skin to display before the user chooses an alternative skin. Specify the skin in your class with <code>@ManagedProperty</code>. </para> +<programlisting language="Java" role="JAVA">@ManagedProperty(value="blueSky") +Private String skin;</programlisting> + <stepalternatives> + <step> + <para> + Alternatively, specify the initial skin in the <filename>web.xml</filename> configuration file. + </para> <programlisting language="XML" role="XML">&lt;managed-bean&gt; &lt;managed-bean-name&gt;skinBean&lt;/managed-bean-name&gt; &lt;managed-bean-class&gt;SkinBean&lt;/managed-bean-class&gt; &lt;managed-bean-scope&gt;session&lt;/managed-bean-scope&gt; &lt;managed-property&gt; &lt;property-name&gt;skin&lt;/property-name&gt; - &lt;value&gt;classic&lt;/value&gt; + &lt;value&gt;blueSky&lt;/value&gt; &lt;/managed-property&gt; &lt;/managed-bean&gt;</programlisting> + </step> + </stepalternatives> </step> </procedure> + <!-- TODO <example id="exam-Developer_Guide-Skinning_and_theming-Skin_changing_example"> <title>Skin changing example</title> <para> @@ -533,6 +558,7 @@ </figure> </blockquote> </example> + --> </section> <section id="sect-Developer_Guide-Creating_a_new_skin"> @@ -550,78 +576,77 @@ <para> The <filename>blueSky.skin.properties</filename> file lists all the skin parameter constants for the skin. It can be extracted from the <filename>/META-INF/skins</filename> directory in the <package>richfaces-impl-<replaceable>version</replaceable>.jar</package> package. </para> -<programlisting>#Colors -headerBackgroundColor=#BED6F8 -headerGradientColor=#F2F7FF -headerTextColor=#000000 -headerWeightFont=bold - -generalBackgroundColor=#FFFFFF -generalTextColor=#000000 -generalSizeFont=11px -generalFamilyFont=Arial, Verdana, sans-serif - -controlTextColor=#000000 -controlBackgroundColor=#ffffff -additionalBackgroundColor=#ECF4FE - -shadowBackgroundColor=#000000 -shadowOpacity=1 - -panelBorderColor=#BED6F8 -subBorderColor=#ffffff - -tabBackgroundColor=#C6DEFF -tabDisabledTextColor=#8DB7F3 - -trimColor=#D6E6FB - -tipBackgroundColor=#FAE6B0 -tipBorderColor=#E5973E - -selectControlColor=#E79A00 - -generalLinkColor=#0078D0 -hoverLinkColor=#0090FF -visitedLinkColor=#0090FF - -# Fonts -headerSizeFont=11px -headerFamilyFont=Arial, Verdana, sans-serif - -tabSizeFont=11 -tabFamilyFont=Arial, Verdana, sans-serif - -buttonSizeFont=11 -buttonFamilyFont=Arial, Verdana, sans-serif - -tableBackgroundColor=#FFFFFF -tableFooterBackgroundColor=#cccccc -tableSubfooterBackgroundColor=#f1f1f1 -tableBorderColor=#C0C0C0 -tableBorderWidth=1px - -#Calendar colors -calendarWeekBackgroundColor=#F5F5F5 - -calendarHolidaysBackgroundColor=#FFEBDA -calendarHolidaysTextColor=#FF7800 - -calendarCurrentBackgroundColor=#FF7800 -calendarCurrentTextColor=#FFEBDA - -calendarSpecBackgroundColor=#E4F5E2 -calendarSpecTextColor=#000000 - -warningColor=#FFE6E6 -warningBackgroundColor=#FF0000 - -editorBackgroundColor=#F1F1F1 -editBackgroundColor=#FEFFDA - -#Gradients -gradientType=plain -</programlisting> +<programlisting>#Colors +headerBackgroundColor=#BED6F8 +headerGradientColor=#F2F7FF +headerTextColor=#000000 +headerWeightFont=bold + +generalBackgroundColor=#FFFFFF +generalTextColor=#000000 +generalSizeFont=11px +generalFamilyFont=Arial, Verdana, sans-serif + +controlTextColor=#000000 +controlBackgroundColor=#ffffff +additionalBackgroundColor=#ECF4FE + +shadowBackgroundColor=#000000 +shadowOpacity=1 + +panelBorderColor=#BED6F8 +subBorderColor=#ffffff + +tabBackgroundColor=#C6DEFF +tabDisabledTextColor=#8DB7F3 + +trimColor=#D6E6FB + +tipBackgroundColor=#FAE6B0 +tipBorderColor=#E5973E + +selectControlColor=#E79A00 + +generalLinkColor=#0078D0 +hoverLinkColor=#0090FF +visitedLinkColor=#0090FF + +# Fonts +headerSizeFont=11px +headerFamilyFont=Arial, Verdana, sans-serif + +tabSizeFont=11 +tabFamilyFont=Arial, Verdana, sans-serif + +buttonSizeFont=11 +buttonFamilyFont=Arial, Verdana, sans-serif + +tableBackgroundColor=#FFFFFF +tableFooterBackgroundColor=#cccccc +tableSubfooterBackgroundColor=#f1f1f1 +tableBorderColor=#C0C0C0 +tableBorderWidth=1px + +#Calendar colors +calendarWeekBackgroundColor=#F5F5F5 + +calendarHolidaysBackgroundColor=#FFEBDA +calendarHolidaysTextColor=#FF7800 + +calendarCurrentBackgroundColor=#FF7800 +calendarCurrentTextColor=#FFEBDA + +calendarSpecBackgroundColor=#E4F5E2 +calendarSpecTextColor=#000000 + +warningColor=#FFE6E6 +warningBackgroundColor=#FF0000 + +editorBackgroundColor=#F1F1F1 +editBackgroundColor=#FEFFDA + +#Gradients +gradientType=plain</programlisting> </example> <para> Alternatively, instead of redefining an entire new skin, your skin can use an existing skin as a base on which to build new parameters. Specify a base skin by using the <varname>baseSkin</varname> parameter in the skin file, as shown in <xref linkend="exam-Developer_Guide-Skinning_and_theming-Using_a_base_skin" />. Added: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Using_skins-Panel_styles.xml_sample =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Using_skins-Panel_styles.xml_sample (rev 0) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Using_skins-Panel_styles.xml_sample 2011-03-21 06:45:02 UTC (rev 22277) @@ -0,0 +1,14 @@ +.rf-p{ + background-color:'#{richSkin.generalBackgroundColor}'; + color:'#{richSkin.panelBorderColor}'; + border-width:1px; + border-style:solid; + padding:1px; +} + +.rf-p-b{ + font-size:'#{richSkin.generalSizeFont}'; + color:'#{richSkin.generalTextColor}'; + font-family:'#{richSkin.generalFamilyFont}'; + padding:10px; +} Added: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Using_skins-Rendered_panel.xml_sample =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Using_skins-Rendered_panel.xml_sample (rev 0) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Using_skins-Rendered_panel.xml_sample 2011-03-21 06:45:02 UTC (rev 22277) @@ -0,0 +1,5 @@ +<div id="..." class="rf-p"> + <div id="..." class="rf-p-b"> + This is a panel without a header + </div> +</div>