Author: msorokin Date: 2008-05-23 12:35:54 -0400 (Fri, 23 May 2008) New Revision: 8738 Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml Log: http://jira.jboss.com/jira/browse/RF-3163 Description of Plug-n-Skin feature was corrected according to comments of Maksim Kaszynski. Modified: trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2008-05-23 16:17:29 UTC (rev 8737) +++ trunk/docs/userguide/en/src/main/docbook/modules/RFCarchitectover.xml 2008-05-23 16:35:54 UTC (rev 8738) @@ -2315,78 +2315,153 @@ <section id="StPluggableSkinnability"> <title>Plug-n-Skin</title> - <para>Plug-n-Skin feature is designed to extend and override the base skin you use, - it allows to redefine the look of a set of components by taking the base skin as basis and plugging-in custom styles. + <para> + Plug-n-Skin feature is designed to easily create a new custom skin which extends and overrides a base skin, + it allows to redefine the look of a set of components by taking the base skin as basis and plugging-in custom styles + as well as to unify the appearance of standard controls and RichFaces components. - </para> - - -<para>Basically, implementation of this feature is performed the same way as you create your own custom skin. - For more information, please, read <link linkend="CreatingAndUsingYourOwnSkinFile"> &quot;Creating and Using Your Own Skin File&quot;</link> section of the guide. - The properties that are used to perform the redefinition of the - base skin are stored in &lt;name&gt;.skin.properties file (same type of file as you would use for creating your own skin). </para> - - - <para>These are the properties you need to set-up this feature:</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> - </listitem> + </para> - <listitem> - <para><property>generalStyleSheet</property> - - a path to the style sheet (&lt;newskinname&gt;.xcss) that imports style sheets of the components to be affected by the new skin - </para> + <para>In order to create your own skin using Plug-n-Skin feature, you can follow these step by step instructions.</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></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> - </listitem> - - - </itemizedlist> - + + <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"...;. 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 +-DarchetypeVersion=RF-VERSION +-DartifactId=ARTIFACT-ID +-DgroupId=GROUP-ID -Dversion=VERSION +... +]]></programlisting> + <para>Primary keys for the command:</para> + <itemizedlist> + <listitem><para><property>DarchetypeVersion</property> Indicates the RichFaces version. For example, &quot;3.2.1-SNAPSHOT&quot;</para></listitem> + <listitem><para><property>DartifactId</property> Artifact id of the project</para></listitem> + <listitem><para><property>DgroupId</property> Group id of the project</para></listitem> + <listitem><para><property>Dversion</property> The version of the project you create, by default it is &quot;1.0.-SNAPSHOT&quot;</para></listitem> + </itemizedlist> <para> - As it has already been mentioned the <property>&lt;newskinname&gt;.xcss</property> contains a list of style sheeted that the new skin affects. + After this operation, a folder with the name of your &quot;ARTIFACT-ID&quot; appears. + The folder contains a template of Maven project. </para> - <para>Importing of the style sheets that redefine the appearance of component to the &lt;newskinname&gt;.xcss is performed using - <property>&lt;f:importResource&gt;</property> tag. Please see the example below. - </para> - - <programlisting role="XML"><![CDATA[... -<f:importResource src="org/richfaces/newSkinName/componentName.xcss" /> + + <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> + + <programlisting role="XML"><![CDATA[... +mvn cdk:add-skin -Dname=SKIN-NAME -Dpackage=SKIN-PACKAGE ... ]]></programlisting> - - <para>Here is template of the <property>&lt;newskinname&gt;.xcss</property> file.</para> - <programlisting role="XML"><![CDATA[ -<f:template xmlns:f='http:/jsf.exadel.com/template' - xmlns:u='http:/jsf.exadel.com/template/util' - xmlns="http://www.w3.org/1999/xhtml" > - <f:importResource src="org/richfaces/newSkinName/calendar.xcss" /> - <f:importResource src="org/richfaces/newSkinName/combobox.xcss" /> + + <para>Primary keys for the command:</para> + + <itemizedlist> + <listitem><para> + <property>Dname</property> defines the name of the new skin + </para> + </listitem> + + <listitem> + <para> + <property>Dpackage</property> base package of the skin. By default &quot;groupId&quot; of the project is used. + </para> + </listitem> + <para> + Additional optional keys for the command: + </para> + <listitem> + <para> + <property>DbaseSkin</property> defines the name of the base skin. + </para> + </listitem> + + <listitem> + <para> + <property>DcreateExt</property> 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> + + <itemizedlist> + <listitem><para><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></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></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 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> + </listitem> + <listitem> + <para><property>generalStyleSheet</property> - + a path to the style sheet (&lt;SKIN-NAME&gt;.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></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> + </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></listitem> + <listitem><para><property>XCSS files</property> If the command is executed with the &quot;DcreateExt&quot; key set to &quot;true&quot;, 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></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></listitem> + </itemizedlist> + + + + <para>Having performed the previous steps you can proceed to building the new skin. This 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 ... - <f:importResource src="org/richfaces/newSkinName/tree.xcss" /> - <f:importResource src="org/richfaces/newSkinName/virtualEarth.xcss" /> -</f:template> -]]></programlisting> +]]></programlisting> + + + + <para>Now, you can use your newly-created skin in your project by adding your new skin parameters to web.xml file.</para> + + <programlisting role="XML"><![CDATA[... +<context-param> + <param-name>org.ajax4jsf.SKIN</param-name> + <param-value>SKIN-NAME</param-value> +</context-param> +... +]]></programlisting> - + <para> - So, now having imported the XCSS files with style sheets of components you want to be affected by the new skin, you can start redefining style properties for each component in the - <property> componentName.xcss</property> files. Please study the example below.</para> + So, now having built your new skin you can start redefining style properties in the corresponding XCSS files(located in &quot;\src\main\resources\SKIN-PACKAGE\SKIN-NAME\css\&quot; folder). + In the example below, it's shown how to redefine the style properties for &quot;combobox&quot; component.</para> <programlisting role="XML"><![CDATA[... <u:selector name=".rich-combobox-item-selected"> @@ -2406,7 +2481,6 @@ ... ]]></programlisting> - <para>In the shown example, new skin properties are applied to the <property>combobox</property> component.</para> <para>Please notice that <property>background-image</property> can be used to set a predefined gradient by means of <property>&lt;f:resource f:key=&quot;org.richfaces.renderkit.html.CustomizeableGradient&quot;&gt;</property> and the <property>gradientType</property> constant set to one of the possible values. </para> @@ -2421,22 +2495,9 @@ <listitem><para> gradientType</para></listitem> </itemizedlist> - <para>The base skin and the new skin should be set in web.xml</para> - <programlisting role="XML"><![CDATA[... - <context-param> - <param-name>org.richfaces.SKIN</param-name> - <param-value>#{skinBean.skin}</param-value> - </context-param> - <context-param> - <param-name>org.richfaces.BASE_SKIN</param-name> - <param-value>#{skinBean.baseSkin}</param-value> - </context-param> -... -]]></programlisting> - </section> </section>