Author: SeanRogers
Date: 2011-03-22 01:43:42 -0400 (Tue, 22 Mar 2011)
New Revision: 22289
Added:
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings-0.xml_sample
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings-1.xml_sample
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings.css
Removed:
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-0.xml_sample
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-1.xml_sample
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings.css
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-RichFaces_overview.xml
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Skinning_and_theming.xml
Log:
Updated Skinning section of Developer Guide based on review RFPL-1350
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-21
19:11:35 UTC (rev 22288)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Getting_started_with_RichFaces.xml 2011-03-22
05:43:42 UTC (rev 22289)
@@ -215,7 +215,7 @@
The profile then needs to be activated in the
<sgmltag><activeProfiles></sgmltag> element:
</para>
<programlisting language="XML"
role="XML"><activeProfiles>
- <activeProfile>jboss-public-repository</activeProfile>
+ <activeProfile>jboss-public-repository</activeProfile>
</activeProfiles></programlisting>
<para>
For further details, refer to the <citetitle>JBoss RichFaces
Wiki</citetitle>.
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-21
19:11:35 UTC (rev 22288)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-RichFaces_overview.xml 2011-03-22
05:43:42 UTC (rev 22289)
@@ -369,14 +369,12 @@
<stepalternatives>
<step>
<title>JBoss RichFaces Downloads area</title>
- <!-- Update download location in Enterprise docs, or remove this section
altogether -->
<para>
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 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>
@@ -390,43 +388,12 @@
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>
+ <title>Configure <productname>Maven</productname> for
RichFaces</title>
<para>
- To compile the RichFaces source code, <productname>Maven</productname>
requires access to JBoss development repositories. Edit the
<filename><replaceable>maven_installation_folder</replaceable>/conf/settings.xml</filename>
file and add the following settings:
+ To compile the RichFaces source code, <productname>Maven</productname>
requires access to the JBoss repositories. Refer to <xref
linkend="step-Developer_Guide-Using_RichFaces_with_Maven-Add_required_repositories"
/> of the procedure in <xref
linkend="sect-Component_Reference-Using_RichFaces_with_Maven-Using_the_RichFaces_project_archetype"
/> to configure the required repositories.
</para>
- <variablelist>
- <varlistentry>
- <term>Server definitions</term>
- <listitem>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/prog-Developer_Guide-Compiling_from_source_code-Maven_server_definitions.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- Change the
<code><replaceable>username</replaceable></code> and
<code><replaceable>password</replaceable></code> in your server
definitions to your <orgname>JBoss.org</orgname> username and password.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Mirror definitions</term>
- <listitem>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/prog-Developer_Guide-Compiling_from_source_code-Maven_mirror_definitions.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Profile definitions</term>
- <listitem>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/prog-Developer_Guide-Compiling_from_source_code-Maven_profile_definitions.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Activate profile</term>
- <listitem>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/prog-Developer_Guide-Compiling_from_source_code-Maven_activate_profile.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </listitem>
- </varlistentry>
- </variablelist>
</step>
- -->
<step>
<title>Compile using
<productname>Maven</productname></title>
<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-21
19:11:35 UTC (rev 22288)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Skinning_and_theming.xml 2011-03-22
05:43:42 UTC (rev 22289)
@@ -97,65 +97,434 @@
</context-param></programlisting>
</section>
- <section
id="sect-Developer_Guide-Skinning_and_theming-Customizing_skins">
- <title>Customizing skins</title>
+ <section
id="sect-Developer_Guide-Skinning_and_theming-Skinning_overview">
+ <title>Skinning overview</title>
<para>
RichFaces skins are implemented using the following three-level scheme:
</para>
<variablelist>
<varlistentry>
- <term>A default style class inserted into the framework</term>
+ <term>Component stylesheets</term>
<listitem>
<para>
- Style classes contain skin parameters linked to constant theme styles in the skin.
Each component has a class style defining a default representation level. Application
interfaces can be modified by altering the values of skin parameters in the skin itself.
+ Stylesheets are provided for each component. CSS style parameters map to skin
parameters defined in the skin property file. This mapping is accomplished through the use
of ECSS files. Refer to <xref
linkend="sect-Developer_Guide-Skinning_and_theming-ECSS_files" /> for details
on ECSS files.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>A style class extending the skin</term>
+ <term>Skin property files</term>
<listitem>
<para>
- A custom style class can be added to the skin, working in conjunction with CSS
classes of the same name. All components referencing the class are extended in the same
way.
+ Skin property files map skin parameters to constant styles. Skin properties are
defined in <filename>skin.properties</filename> files. Refer to <xref
linkend="sect-Developer_Guide-Skinning_overview-Skin_parameter_tables" /> for
a listing of the skin parameters used in a typical skin.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>User style class</term>
+ <term>Custom style classes</term>
<listitem>
<para>
- Components can use the <varname>styleClass</varname> attribute to
redefine specific component elements. As such, the appearance of an individual component
can be customized according to a CSS style parameter specified in the class.
+ Individual components can use the <varname>styleClass</varname>
attribute to redefine specific elements. These components then use the styles defined in a
CSS file instead of the standard look for components as defined by the ECSS stylesheets.
</para>
</listitem>
</varlistentry>
</variablelist>
- <example
id="exam-Developer_Guide-Using_skins-Simple_skinning_example">
- <title>Simple skinning example</title>
+
+ <section
id="sect-Developer_Guide-Skinning_overview-Skin_parameter_tables">
+ <title>Skin parameter tables</title>
<para>
- Using any component, such as a panel, without specifying a
<varname>styleClass</varname> will use the default skin parameters for that
component.
+ <xref
linkend="tabl-Developer_Guide-Skin_parameter_tables_in_RichFaces-Parameter_settings_for_the_blueSky_skin"
/> lists the default values for the parameter settings in the
<literal>blueSky</literal> skin. These values are all listed in the
<filename>buleSky.skin.properties</filename> file, which can be customized and
extended as described in <xref
linkend="sect-Developer_Guide-Skinning_and_theming-Customizing_skins" />.
</para>
-
-<programlisting language="XML"
role="XML"><rich:panel>This is a panel without a
header</rich:panel></programlisting>
+ <table
id="tabl-Developer_Guide-Skin_parameter_tables_in_RichFaces-Parameter_settings_for_the_blueSky_skin">
+ <title>Parameter settings for the <literal>blueSky</literal>
skin</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ Parameter name
+ </entry>
+ <entry>
+ Default value
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><parameter>
+ headerBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #BED6F8
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ headerGradientColor
+ </parameter></entry>
+ <entry><literal>
+ #F2F7FF
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ headTextColor
+ </parameter></entry>
+ <entry><literal>
+ #000000
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ headerWeightFont
+ </parameter></entry>
+ <entry><literal>
+ bold
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ generalBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #FFFFFF
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ generalTextColor
+ </parameter></entry>
+ <entry><literal>
+ #000000
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ generalSizeFont
+ </parameter></entry>
+ <entry><literal>
+ 11px
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ generalFamilyFont
+ </parameter></entry>
+ <entry><literal>
+ Arial, Verdana, sans-serif
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ controlTextColor
+ </parameter></entry>
+ <entry><literal>
+ #000000
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ controlBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #ffffff
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ additionalBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #ECF4FE
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ shadowBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #000000
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ shadowOpacity
+ </parameter></entry>
+ <entry><literal>
+ 1
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ panelBorderColor
+ </parameter></entry>
+ <entry><literal>
+ #BED6F8
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ subBorderColor
+ </parameter></entry>
+ <entry><literal>
+ #ffffff
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tabBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #C6DEFF
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tabDisabledTextColor
+ </parameter></entry>
+ <entry><literal>
+ #8DB7F3
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ trimColor
+ </parameter></entry>
+ <entry><literal>
+ #D6E6FB
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tipBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #FAE6B0
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tipBorderColor
+ </parameter></entry>
+ <entry><literal>
+ #E5973E
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ selectControlColor
+ </parameter></entry>
+ <entry><literal>
+ #E79A00
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ generalLinkColor
+ </parameter></entry>
+ <entry><literal>
+ #0078D0
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ hoverLinkColor
+ </parameter></entry>
+ <entry><literal>
+ #0090FF
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ visitedLinkColor
+ </parameter></entry>
+ <entry><literal>
+ #0090FF
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ headerSizeFont
+ </parameter></entry>
+ <entry><literal>
+ 11px
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ headerFamilyFont
+ </parameter></entry>
+ <entry><literal>
+ Arial, Verdana, sans-serif
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tabSizeFont
+ </parameter></entry>
+ <entry><literal>
+ 11px
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tabFamilyFont
+ </parameter></entry>
+ <entry><literal>
+ Arial, Verdana, sans-serif
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ buttonSizeFont
+ </parameter></entry>
+ <entry><literal>
+ 11px
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ buttonFamilyFont
+ </parameter></entry>
+ <entry><literal>
+ Arial, Verdana, sans-serif
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tableBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #FFFFFF
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tableFooterBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #cccccc
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tableSubfooterBackgroundColor
+ </parameter></entry>
+ <entry><literal>
+ #f1f1f1
+ </literal></entry>
+ </row>
+ <row>
+ <entry><parameter>
+ tableBorderColor
+ </parameter></entry>
+ <entry><literal>
+ #C0C0C0
+ </literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="sect-Developer_Guide-Skinning_and_theming-ECSS_files">
+ <title><acronym>ECSS</acronym> files</title>
<para>
- When rendered for display, the panel consists of two HTML elements: a wrapper
<sgmltag><div></sgmltag> element and a
<sgmltag><div></sgmltag> element for the body of the panel. The
wrapper element for a panel without a specified <varname>styleClass</varname>
is rendered as follows:
+ RichFaces uses <acronym>ECSS</acronym> files to add extra functionality
to the skinning process. ECSS files are CSS files which use Expression Language
(<acronym>EL</acronym>) to connect styles with skin properties.
</para>
- <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>
- <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>
+ <example
id="exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings">
+ <title>ECSS style mappings</title>
+ <para>
+ The ECSS code for the <sgmltag><rich:panel></sgmltag>
component contains styles for the panel and its body:
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include
parse="text"
href="extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings.css"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><classname>.rf-p</classname> defines the panel
styles</term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <property>background-color</property> CSS property maps to the
<parameter>generalBackgroundColor</parameter> skin parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <property>color</property> CSS property maps to the
<parameter>panelBorderColor</parameter> skin parameter.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><classname>.rf-p-b</classname> defines the panel body
styles</term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <property>font-family</property> CSS property maps to the
<parameter>generalFamilyFont</parameter> skin parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <property>font-size</property> CSS property maps to the
<parameter>generalSizeFont</parameter> skin parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <property>color</property> CSS property maps to the
<parameter>generalTextColor</parameter> skin parameter.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </example>
+ </section>
+ </section>
+
+ <section
id="sect-Developer_Guide-Skinning_and_theming-Customizing_skins">
+ <title>Customizing skins</title>
+ <para>
+ Skins in RichFaces can be customized on each of the three levels:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Skin property files</term>
<listitem>
<para>
- The <property>background-color</property> CSS class attribute is
defined by the <parameter>generalBackgroundColor</parameter> skin parameter.
+ Application interfaces can be modified by altering the values of skin parameters in
the skin itself. Edit the constant values defined in the
<filename>skin.properties</filename> file to change the style of every
component mapped to that skin property.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Component stylesheets</term>
<listitem>
<para>
- The <property>color</property> CSS class attribute is defined by the
<parameter>panelBorderColor</parameter> skin parameter.
+ Mappings and other style attributes listed in a component's ECSS file can be
edited. Edit the ECSS file to change the styles of all components of that type.
</para>
</listitem>
- </itemizedlist>
+ </varlistentry>
+ <varlistentry>
+ <term>Custom style classes</term>
+ <listitem>
+ <para>
+ Individual components can use the <varname>styleClass</varname>
attribute to use a unique style class. Add the new style class to the application CSS and
reference it from an individual component with the
<varname>styleClass</varname> attribute.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example
id="exam-Developer_Guide-Using_skins-Simple_skinning_example">
+ <title>Simple skinning example</title>
<para>
+ 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"><rich:panel>This is a panel without a
header</rich:panel></programlisting>
+ <para>
+ When rendered for display, the panel consists of two HTML elements: a wrapper
<sgmltag><div></sgmltag> element and a
<sgmltag><div></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"><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>
To customize the panel appearance according to the three-level scheme, adjust the
styles according to the following approach:
</para>
<procedure>
@@ -177,315 +546,69 @@
<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"><div
class="rf-p customClass">
+ <programlisting language="XML" role="XML"><div
class="rf-p customClass">
...
</div></programlisting>
</step>
</procedure>
</example>
+
+ <section
id="sect-Developer_Guide-Customizing_skins-Creating_a_new_skin">
+ <title>Creating a new skin</title>
+ <procedure>
+ <step>
+ <title>Create the skin file</title>
+ <para>The name of the skin file should follow the format
<filename><replaceable>new_skin_name</replaceable>.skin.properties</filename>
and is placed in either the <filename>META-INF/skins/</filename> directory or
the classpath directory of your project.</para>
+ </step>
+ <step>
+ <title>Define the skin constants</title>
+ <stepalternatives>
+ <step>
+ <title>Define all the skin constants</title>
+ <para>Add skin parameter constants and values to the file. All the skin
parameters listed in <xref
linkend="tabl-Developer_Guide-Skin_parameter_tables_in_RichFaces-Parameter_settings_for_the_blueSky_skin"
/> should be included in the skin file, with settings relevant to your new
skin.</para>
+ <example
id="exam-Developer_Guide-Skinning_and_theming-blueSky.skin.properties_file">
+ <title><filename>blueSky.skin.properties</filename>
file</title>
+ <para>
+ Open the <filename>blueSky.skin.properties</filename> file from the
<filename>/META-INF/skins</filename> directory in the
<package>richfaces-impl-<replaceable>version</replaceable>.jar</package>
package. The file lists all the skin parameter constants shown in <xref
linkend="tabl-Developer_Guide-Skin_parameter_tables_in_RichFaces-Parameter_settings_for_the_blueSky_skin"
/>.
+ </para>
+ <para>
+ You can use the <filename>blueSky.skin.properties</filename> file as
a template for your new skin.
+ </para>
+ </example>
+ </step>
+ <step>
+ <title>Extend a base skin</title>
+ <para>
+ 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" />.
+ </para>
+ <example
id="exam-Developer_Guide-Skinning_and_theming-Using_a_base_skin">
+ <title>Using a base skin</title>
+ <para>
+ This example takes the <literal>blueSky</literal> skin as a base and
only changes the <varname>generalSizeFont</varname> parameter.
+ </para>
+ <programlisting>baseSkin=blueSky
+generalSizeFont=12pt</programlisting>
+ </example>
+ </step>
+ </stepalternatives>
+ </step>
+ <step>
+ <title>Reference the skin definition</title>
+ <para>Add a skin definition
<sgmltag><context-param></sgmltag> to the
<filename>web.xml</filename> settings file of your application:</para>
+ <programlisting><context-param>
+ <param-name>org.richfaces.skin</param-name>
+
<param-value><replaceable>new_skin_name</replaceable></param-value>
+</context-param></programlisting>
+ </step>
+ </procedure>
+ </section>
</section>
- <section
id="sect-Developer_Guide-Skinning_and_theming-Skin_parameter_tables_in_RichFaces">
- <title>Skin parameter tables in RichFaces</title>
- <para>
- <xref
linkend="tabl-Developer_Guide-Skin_parameter_tables_in_RichFaces-Parameter_settings_for_the_blueSky_skin"
/> lists the default values for the parameter settings in the
<literal>blueSky</literal> skin. These values can be customized and extended
for a unique application theme as described in <xref
linkend="sect-Developer_Guide-Skinning_and_theming-Customizing_skins" />.
- </para>
- <table
id="tabl-Developer_Guide-Skin_parameter_tables_in_RichFaces-Parameter_settings_for_the_blueSky_skin">
- <title>Parameter settings for the <literal>blueSky</literal>
skin</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- Parameter name
- </entry>
- <entry>
- Default value
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><parameter>
- headerBackgroundColor
- </parameter></entry>
- <entry><literal>
- #BED6F8
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- headerGradientColor
- </parameter></entry>
- <entry><literal>
- #F2F7FF
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- headTextColor
- </parameter></entry>
- <entry><literal>
- #000000
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- headerWeightFont
- </parameter></entry>
- <entry><literal>
- bold
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- generalBackgroundColor
- </parameter></entry>
- <entry><literal>
- #FFFFFF
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- generalTextColor
- </parameter></entry>
- <entry><literal>
- #000000
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- generalSizeFont
- </parameter></entry>
- <entry><literal>
- 11px
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- generalFamilyFont
- </parameter></entry>
- <entry><literal>
- Arial, Verdana, sans-serif
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- controlTextColor
- </parameter></entry>
- <entry><literal>
- #000000
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- controlBackgroundColor
- </parameter></entry>
- <entry><literal>
- #ffffff
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- additionalBackgroundColor
- </parameter></entry>
- <entry><literal>
- #ECF4FE
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- shadowBackgroundColor
- </parameter></entry>
- <entry><literal>
- #000000
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- shadowOpacity
- </parameter></entry>
- <entry><literal>
- 1
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- panelBorderColor
- </parameter></entry>
- <entry><literal>
- #BED6F8
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- subBorderColor
- </parameter></entry>
- <entry><literal>
- #ffffff
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tabBackgroundColor
- </parameter></entry>
- <entry><literal>
- #C6DEFF
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tabDisabledTextColor
- </parameter></entry>
- <entry><literal>
- #8DB7F3
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- trimColor
- </parameter></entry>
- <entry><literal>
- #D6E6FB
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tipBackgroundColor
- </parameter></entry>
- <entry><literal>
- #FAE6B0
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tipBorderColor
- </parameter></entry>
- <entry><literal>
- #E5973E
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- selectControlColor
- </parameter></entry>
- <entry><literal>
- #E79A00
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- generalLinkColor
- </parameter></entry>
- <entry><literal>
- #0078D0
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- hoverLinkColor
- </parameter></entry>
- <entry><literal>
- #0090FF
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- visitedLinkColor
- </parameter></entry>
- <entry><literal>
- #0090FF
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- headerSizeFont
- </parameter></entry>
- <entry><literal>
- 11px
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- headerFamilyFont
- </parameter></entry>
- <entry><literal>
- Arial, Verdana, sans-serif
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tabSizeFont
- </parameter></entry>
- <entry><literal>
- 11px
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tabFamilyFont
- </parameter></entry>
- <entry><literal>
- Arial, Verdana, sans-serif
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- buttonSizeFont
- </parameter></entry>
- <entry><literal>
- 11px
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- buttonFamilyFont
- </parameter></entry>
- <entry><literal>
- Arial, Verdana, sans-serif
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tableBackgroundColor
- </parameter></entry>
- <entry><literal>
- #FFFFFF
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tableFooterBackgroundColor
- </parameter></entry>
- <entry><literal>
- #cccccc
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tableSubfooterBackgroundColor
- </parameter></entry>
- <entry><literal>
- #f1f1f1
- </literal></entry>
- </row>
- <row>
- <entry><parameter>
- tableBorderColor
- </parameter></entry>
- <entry><literal>
- #C0C0C0
- </literal></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
<section
id="sect-Developer_Guide-Skinning_and_theming-Changing_skins_at_runtime">
<title>Changing skins at runtime</title>
<para>
- The user can change skins at runtime if a managed bean is used to access the skin.
+ To allow users to change skins at runtime, use a managed bean to access the skin.
</para>
<procedure>
<step>
@@ -535,560 +658,46 @@
</stepalternatives>
</step>
</procedure>
- <!-- TODO
- <example
id="exam-Developer_Guide-Skinning_and_theming-Skin_changing_example">
- <title>Skin changing example</title>
- <para>
- This example renders a list of radio buttons from which the user can choose their
desired skin. The chosen skin is then applied to the panel bar items.
- </para>
-<programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Developer_Guide-Skinning_and_theming-Skin_changing_example.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <blockquote>
- <figure
id="figu-Developer_Guide-Skinning_and_theming-Skin_changing_example">
- <title>Skin changing example</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/figu-Developer_Guide-Skinning_and_theming-Skin_changing_example.png"
format="PNG" />
- </imageobject>
- <textobject>
- <para>
- A list of radio buttons from which the user can choose their desired skin. The
chosen skin is then applied to the panel bar items.
- </para>
- </textobject>
- </mediaobject>
- </figure>
- </blockquote>
- </example>
- -->
</section>
- <section id="sect-Developer_Guide-Creating_a_new_skin">
- <title>Creating a new skin</title>
- <procedure>
- <step>
- <title>Create the skin file</title>
- <para>The name of the skin file should follow the format
<filename><replaceable>new_skin_name</replaceable>.skin.properties</filename>
and is placed in either the <filename>META-INF/skins/</filename> directory or
the classpath directory of your project.</para>
- </step>
- <step>
- <title>Define skin constants</title>
- <para>Add skin parameter constants and values to the file. <xref
linkend="exam-Developer_Guide-Skinning_and_theming-blueSky.skin.properties_file"
/> shows how the skin parameters listed in <xref
linkend="tabl-Developer_Guide-Skin_parameter_tables_in_RichFaces-Parameter_settings_for_the_blueSky_skin"
/> are included in the skin file.</para>
- <example
id="exam-Developer_Guide-Skinning_and_theming-blueSky.skin.properties_file">
- <title><filename>blueSky.skin.properties</filename>
file</title>
- <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>
- </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" />.
- </para>
- <example
id="exam-Developer_Guide-Skinning_and_theming-Using_a_base_skin">
- <title>Using a base skin</title>
- <para>
- This example takes the <literal>blueSky</literal> skin as a base and
only changes the <varname>generalSizeFont</varname> parameter.
- </para>
-<programlisting>baseSkin=blueSky
-generalSizeFont=12pt</programlisting>
- </example>
- </step>
- <step>
- <title>Reference skin definition</title>
- <para>Add a skin definition
<sgmltag><context-param></sgmltag> to the
<filename>web.xml</filename> settings file of your application:</para>
-<programlisting><context-param>
- <param-name>org.richfaces.SKIN</param-name>
-
<param-value><replaceable>new_skin_name</replaceable></param-value>
-</context-param></programlisting>
- </step>
- </procedure>
- </section>
-
<section
id="sect-Developer_Guide-Skinning_and_theming-Skinning_standard_controls">
<title>Skinning standard controls</title>
- <section
id="sect-Developer_Guide-Skinning_and_theming-Skinning_standard_JSF_components">
- <title>Skinning standard JSF components</title>
- <para>
- The RichFaces framework can also use skinning to theme JSF (JavaServer Faces)
components in addition to RichFaces components. Follow these additional steps to skin JSF
components.
- </para>
- <procedure>
- <step>
- <title>Register a custom render kit</title>
- <para>The custom render kit is created by registering it in the
<filename>faces-config.xml</filename> configuration file:</para>
-<programlisting><render-kit>
-
<render-kit-id><replaceable>new_skin_name</replaceable></render-kit-id>
-
<render-kit-class>org.ajax4jsf.framework.renderer.ChameleonRenderKitImpl</render-kit-class>
-</render-kit></programlisting>
- </step>
- <step>
- <title>Register custom renderers for the JSF component</title>
- <para>Add custom renderers in the
<filename>faces-config.xml</filename> configuration file for each JSF
component you want to skin:</para>
-<programlisting><renderer>
- <component-family>javax.faces.Command</component-family>
- <renderer-type>javax.faces.Link</renderer-type>
-
<renderer-class><replaceable>new_skin_name</replaceable>.HtmlCommandLinkRenderer</renderer-class>
-</renderer></programlisting>
- </step>
- <step>
- <title>Reference the render kit in the skin file</title>
- <para>Add the following to the top of the skin parameters file:
<code>render.kit=<replaceable>new_skin_name</replaceable></code></para>
- </step>
- </procedure>
- </section>
-
- <section
id="sect-Developer_Guide-Skinning_and_theming-Skinning_standard_HTML_controls">
- <title>Skinning standard HTML controls</title>
- <para>
- Standard HTML controls and components used alongside RichFaces and JSF components can
also be themed to create a cohesive user interface. The following HTML elements accept
skinning:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <sgmltag><a></sgmltag> (including
<sgmltag>a:hover</sgmltag>, <sgmltag>a:visited</sgmltag> and other
elements)
- </para>
- </listitem>
- <listitem>
- <para>
- <sgmltag><fieldset></sgmltag>
- </para>
- </listitem>
- <listitem>
- <para>
- <sgmltag><hr></sgmltag>
- </para>
- </listitem>
- <listitem>
- <para>
- <sgmltag><input></sgmltag>
- </para>
- </listitem>
- <listitem>
- <para>
- <sgmltag><isindex></sgmltag>
- </para>
- </listitem>
- <listitem>
- <para>
- <sgmltag><keygen></sgmltag>
- </para>
- </listitem>
- <listitem>
- <para>
- <sgmltag><legend></sgmltag>
- </para>
- </listitem>
- <listitem>
- <para>
- <sgmltag><select></sgmltag>
- </para>
- </listitem>
- <listitem>
- <para>
- <sgmltag><textarea></sgmltag>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Skinning for standard HTML controls can be included in one of two ways:
- </para>
- <variablelist>
- <varlistentry>
- <term>Automatic skinning</term>
- <listitem>
- <para>
- The skinning style properties are automatically applied to controls based on their
element names and attribute types. Specify the
<literal>org.richfaces.CONTROL_SKINNING</literal> context parameter in the
<filename>web.xml</filename> configuration file:
- </para>
- <programlisting language="XML"
role="XML"><context-param>
- <param-name>org.richfaces.CONTROL_SKINNING</param-name>
- <param-value>enable</param-value>
- </context-param></programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Skinning with CSS classes</term>
- <listitem>
- <para>
- The skinning style properties are determined through CSS. This method is available
by default, but can be disabled through the
<literal>org.richfaces.CONTROL_SKINNING_CLASSES</literal> context parameter in
the <filename>web.xml</filename> configuration file:
- </para>
- <programlisting language="XML"
role="XML"><context-param>
- <param-name>org.richfaces.CONTROL_SKINNING_CLASSES</param-name>
- <param-value>disable</param-value>
- </context-param></programlisting>
- <para>
- When enabled, the parameter offers a predefined CSS class named
<literal>rich-container</literal>. Reference the class from any container-like
component, and the standard HTML controls in the container will be skinned. Standard HTML
controls can also be specifically defined in the CSS; refer to the
<filename>org/richfaces/renderkit/html/css/basic_classes.xcss</filename> file
in the <package>richfaces-ui.jar</package> package for examples of
specially-defined CSS classes with skin parameters for HTML controls.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <section
id="sect-Developer_Guide-Skinning_and_theming-Skinning_levels_for_standard_HTML_controls">
- <title>Skinning levels for standard HTML controls</title>
- <para>
- There are two levels of skinning for HTML controls, depending on whether the browser
viewing the application includes rich visual styling capabilities, and whether the browser
supports features of CSS2 and CSS3.
- </para>
- <remark>Browser lists may need to be updated.</remark>
- <itemizedlist>
- <title>Basic skinning</title>
- <listitem>
- <para>
- <productname>Apple Safari</productname>
- </para>
- </listitem>
- <listitem>
- <para>
- <productname>Microsoft Internet Explorer 6</productname>
- </para>
- </listitem>
- <listitem>
- <para>
- <productname>Microsoft Internet Explorer 7</productname> in
<literal>BackCompat</literal> mode (refer to <citetitle
pubwork="article"><varname>compatMode</varname>
Property</citetitle> at <ulink
url="http://msdn.microsoft.com/en-us/library/ms533687(VS.85).aspx&qu...
- </para>
- </listitem>
- <listitem>
- <para>
- <productname>Opera</productname>
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <title>Extended skinning</title>
- <listitem>
- <para>
- <productname>Microsoft Internet Explorer 7</productname> in
standards-compliant mode
- </para>
- </listitem>
- <listitem>
- <para>
- <productname>Mozilla Firefox</productname>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- If the browser type cannot be identified, the extended level is used. Set the level
explicitly by adding the following context parameter to the
<filename>web.xml</filename> configuration file, and specifying the
<sgmltag><param-value></sgmltag> element as either
<literal>basic</literal> or <literal>extended</literal>:
- </para>
-<programlisting language="XML"
role="XML"><context-param>
-
<param-name>org.richfaces.CONTROL_SKINNING_LEVEL</param-name>
- <param-value>basic</param-value>
-</context-param></programlisting>
-<!--
- <para>
- Browsers with rich visual styling for controls (such as Opera and Safari) will not
work correctly with standard HTML control skinning. The RichFaces framework includes a
client-side script (<filename>skinning.js</filename>) for determining the
styling capabilities of the browser and enabling extended skinning accordingly.
- </para>
- <procedure
id="proc-Developer_Guide-Skinning_and_theming-Using_the_skinning.js_script">
- <title>Using the skinning.js script</title>
- <step>
- <title>Activate the script on the page</title>
- <para>Add the following code to the head of the page:</para>
-<programlisting language="XML" role="XML"><script
type="text/javascript">
- window.RICH_FACES_EXTENDED_SKINNING_ON = true;
-</script></programlisting>
- </step>
- </procedure>
--->
- </section>
- </section>
- </section>
-
- <section
id="sect-Developer_Guide-Skinning_and_theming-Defining_skins_for_individual_components">
- <title>Defining skins for individual components</title>
<para>
- RichFaces uses <acronym>XCSS</acronym> (XML-formatted CSS) files to add
extra functionality to the skinning process. XCSS files can contain all the styling
information for each RichFaces component in the library.
+ Standard HTML controls used alongside RichFaces components are also themed to create a
cohesive user interface.
</para>
- <para>
- XCSS files contain mappings between CSS properties and skin parameters. The
<varname>name</varname> attribute of the
<sgmltag><u:selector></sgmltag> element is the name of the CSS
selector. Each <sgmltag><u:style></sgmltag> element defines a
CSS property with the <varname>name</varname> attribute as its name. Using the
<varname>skin</varname> attribute specifies a skin parameter from the current
skin file, while using the <varname>value</varname> attribute enters the
literal value in the CSS file. An example of this is shown in <xref
linkend="exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings" />.
- </para>
- <example
id="exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings">
- <title>XCSS style mappings</title>
+
+ <section
id="sect-Developer_Guide-Skinning_standard_controls-Automatic_skinning">
+ <title>Automatic skinning</title>
<para>
- The XCSS code for the CSS selector named
<literal>.rich-component-name</literal> is as follows:
+ The skinning style properties are automatically applied to controls based on their
element names and attribute types. If the HTML elements are referenced in the standard
skin stylesheets, the controls will be styled according to the mapped skin properties.
</para>
-<programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-0.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
- This renders the following CSS code to be read by a standard browser:
+ Standard HTML controls are skinned in this way by default. To override this behavior,
set the <literal>org.richfaces.enableControlSkinning</literal> context
parameter in the <filename>web.xml</filename> configuration file to
<literal>false</literal>:
</para>
-<programlisting language="Java" role="JAVA"><xi:include
parse="text"
href="extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings.css"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- CSS selectors with identical skinning properties can be listed in a single
<varname>name</varname> attribute of a
<sgmltag><u:selector></sgmltag> element, separated by commas.
- </para>
-<programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-1.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- <para>
- Style properties can be modified using XML-based XCSS code, or using embedded standard
CSS code, as shown in <xref
linkend="exam-Developer_Guide-Skinning_and_theming-Using_XCSS_code_or_standard_CSS_code"
/>
- </para>
- <example
id="exam-Developer_Guide-Skinning_and_theming-Using_XCSS_code_or_standard_CSS_code">
- <title>Using XCSS code or standard CSS code</title>
- <formalpara>
- <title>Using XCSS code</title>
+ <programlisting language="XML"
role="XML"><context-param>
+
<param-name>org.richfaces.enableControlSkinning</param-name>
+ <param-value>false</param-value>
+</context-param></programlisting>
+ </section>
+
+ <section
id="sect-Developer_Guide-Skinning_standard_controls-Skinning_with_the_rfs-ctn_class">
+ <title>Skinning with the <classname>rfs-ctn</classname>
class</title>
<para>
- XCSS code follows an XML structure, using
<sgmltag><u:selector></sgmltag> elements to define style classes
and <sgmltag><u:style></sgmltag> elements for each style
parameter.
+ The skinning style properties can be determined through a separate CSS class. This
method is not available by default, but is enabled through the
<literal>org.richfaces.enableControlSkinningClasses</literal> context
parameter in the <filename>web.xml</filename> configuration file:
</para>
- </formalpara>
-<programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Developer_Guide-Skinning_and_theming-Using_XCSS_code_or_standard_CSS_code-XCSS.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <formalpara>
- <title>Using standard CSS code</title>
+ <programlisting language="XML"
role="XML"><context-param>
+
<param-name>org.richfaces.enableControlSkinningClasses</param-name>
+ <param-value>true</param-value>
+</context-param></programlisting>
<para>
- CSS code can be included in an XCSS file through the use of a
<sgmltag><f:verbatim></sgmltag> element with a character data
(CDATA) section.
+ When enabled, a stylesheet with predefined classes offers a special CSS class named
<classname>rfs-ctn</classname>. Reference the
<classname>rfs-ctn</classname> class from any container element (such as a
<sgmltag><div></sgmltag> element) to skin all the standard HTML
controls in the container.
</para>
- </formalpara>
-<programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Developer_Guide-Skinning_and_theming-Using_XCSS_code_or_standard_CSS_code-CSS.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- </section>
-
- <section
id="sect-Developer_Guide-Skinning_and_theming-Extended_skinning">
- <title>Plug-n-skin</title>
- <para>
- <emphasis>Plug-n-skin</emphasis> is an alternate method to create,
customize, and add a skin. The skin can be based on an existing RichFaces skin, and can
include support for skinning standard HTML controls.
- </para>
- <procedure>
- <step>
- <title>Create a template</title>
- <para>Use the <productname>Maven</productname> build and deployment
tool to create the skin template by using the following command:</para>
-<screen>mvn archetype:create -DarchetypeGroupId=org.richfaces.cdk
-DarchetypeArtifactId=maven-archetype-plug-n-skin
-DarchetypeVersion=<replaceable>RF-VERSION</replaceable>
-DartifactId=<replaceable>ARTIFACT-ID</replaceable>
-DgroupId=<replaceable>GROUP-ID</replaceable>
-Dversion=<replaceable>VERSION</replaceable></screen>
<para>
- Use the following parameters for the command:
+ Standard HTML controls can also be specifically defined in the CSS. Refer to the
<filename>/core/impl/src/main/resources/META-INF/resources/skinning_both.ecss</filename>
file in the <package>richfaces-ui.jar</package> package for examples of
specially-defined CSS classes with skin parameters for HTML controls.
</para>
- <variablelist>
- <varlistentry>
- <term><parameter>archetypeVersion</parameter></term>
- <listitem>
- <para>
- The version of RichFaces, for example, <literal>4.0.0.GA</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>artifactId</parameter></term>
- <listitem>
- <para>
- The artifact identifier or name of the project. The Maven template will be
created in a directory using this name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>groupId</parameter></term>
- <listitem>
- <para>
- The group identifier of the project.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>version</parameter></term>
- <listitem>
- <para>
- The version of your project, for example, <literal>1.0</literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </step>
- <step>
- <title>Add the skin to the CDK</title>
- <para>Change to the newly-created directory. Ensure it contains the
<filename>pom.xml</filename> project file, then enter the following command to
create a new skin and add it to the <acronym>CDK</acronym> (Component
Development Kit):</para>
-<screen>mvn cdk:add-skin -Dname=<replaceable>SKIN-NAME</replaceable>
-Dpackage=<replaceable>SKIN-PACKAGE</replaceable></screen>
- <para>
- Use the following parameters for the command:
- </para>
- <variablelist>
- <varlistentry>
- <term><parameter>name</parameter></term>
- <listitem>
- <para>
- The name of your new skin.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>package</parameter></term>
- <listitem>
- <para>
- The base package of the skin. By default, the group identifier is used.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- Use the following optional keys for advanced features:
- </para>
- <variablelist>
- <varlistentry>
- <term><parameter>baseSkin</parameter></term>
- <listitem>
- <para>
- The skin to use as a base for the new skin.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>createExt</parameter></term>
- <listitem>
- <para>
- Use <code>createExt=true</code> to add extended CSS classes for
skinning standard HTML controls.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- The command creates the following files:
- </para>
- <variablelist>
- <varlistentry>
- <term><filename>src/main/java/<replaceable>SKIN-PACKAGE</replaceable>/<replaceable>SKIN-NAME</replaceable>/images/BaseImage.java</filename></term>
- <listitem>
- <para>
- The base class to store images.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>src/test/java/<replaceable>SKIN-PACKAGE</replaceable>/<replaceable>SKIN-NAME</replaceable>/images/BaseImage.java</filename></term>
- <listitem>
- <para>
- A test version of the base class to store images.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>src/main/resources/<replaceable>SKIN-PACKAGE</replaceable>/<replaceable>SKIN-NAME</replaceable>/css/</filename></term>
- <listitem>
- <para>
- The directory that holds the XCSS files that define the themes for RichFaces
components affected by the new skin.
- </para>
- <para>
- If the <code>createExt=true</code> parameter was used with the
command, the following XCSS files are included for defining styles for standard HTML
controls:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <filename>extended_classes.xcss</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- <filename>extended.xcss</filename>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>src/main/resources/<replaceable>SKIN-PACKAGE</replaceable>/<replaceable>SKIN-NAME</replaceable>/css/<replaceable>SKIN-NAME</replaceable>.properties</filename></term>
- <listitem>
- <para>
- The file that contains the skin properties.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>src/main/resources/META-INF/skins/<replaceable>SKIN-NAME</replaceable>.xcss</filename></term>
- <listitem>
- <para>
- A global XCSS file that imports the component-specific XCSS files.
- </para>
- <para>
- If the <code>createExt=true</code> parameter was used with the
command, the following
<filename><replaceable>skin-name</replaceable>-ext.xcss</filename>
file is included, which imports the XCSS files for standard HTML controls.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>src/main/config/resources/<replaceable>SKIN-NAME</replaceable>-resources.xml</filename></term>
- <listitem>
- <para>
- The file that contains the description of all the files listed above.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </step>
- <step>
- <title>Edit XCSS files</title>
- <para>
- Edit the XCSS files contained in the
<filename>src/main/resources/META-INF/skins/</filename> directory. Refer to
<xref
linkend="sect-Developer_Guide-Skinning_and_theming-Defining_skins_for_individual_components"
/> for instructions on how to edit XCSS files.
- </para>
- </step>
- <step>
- <title>Build the skin</title>
- <para>
- After editing the XCSS files, build the skin by running the following command in the
root directory of your skin project (the directory that contains the
<filename>pom.xml</filename> file).
- </para>
-<screen>mvn clean install</screen>
- </step>
- <step>
- <title>Add the skin to the project configuration</title>
- <para>Add the following context parameter to your project's
<filename>web.xml</filename> configuration file to use the new skin in your
application:</para>
-<programlisting><context-param>
- <param-name>org.ajax4jsf.SKIN</param-name>
-
<param-value><replaceable>SKIN-NAME</replaceable></param-value>
-</context-param></programlisting>
- </step>
- </procedure>
+ </section>
+
</section>
-
+
</chapter>
Copied:
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings-0.xml_sample
(from rev 21645,
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-0.xml_sample)
===================================================================
---
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings-0.xml_sample
(rev 0)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings-0.xml_sample 2011-03-22
05:43:42 UTC (rev 22289)
@@ -0,0 +1,6 @@
+<u:selector name=".rich-component-name">
+ <u:style name="background-color"
skin="additionalBackgroundColor" />
+ <u:style name="border-color" skin="tableBorderColor" />
+ <u:style name="border-width" skin="tableBorderWidth" />
+ <u:style name="border-style" value="solid" />
+</u:selector>
Copied:
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings-1.xml_sample
(from rev 21645,
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-1.xml_sample)
===================================================================
---
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings-1.xml_sample
(rev 0)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings-1.xml_sample 2011-03-22
05:43:42 UTC (rev 22289)
@@ -0,0 +1,3 @@
+<u:selector name=".rich-ordering-control-disabled, .rich-ordering-control-top,
.rich-ordering-control-bottom, .rich-ordering-control-up,
.rich-ordering-control-down">
+ <u:style name="border-color" skin="tableBorderColor" />
+</u:selector>
Copied:
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings.css
(from rev 21645,
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings.css)
===================================================================
---
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings.css
(rev 0)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-ECSS_style_mappings.css 2011-03-22
05:43:42 UTC (rev 22289)
@@ -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;
+}
Deleted:
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-0.xml_sample
===================================================================
---
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-0.xml_sample 2011-03-21
19:11:35 UTC (rev 22288)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-0.xml_sample 2011-03-22
05:43:42 UTC (rev 22289)
@@ -1,6 +0,0 @@
-<u:selector name=".rich-component-name">
- <u:style name="background-color"
skin="additionalBackgroundColor" />
- <u:style name="border-color" skin="tableBorderColor" />
- <u:style name="border-width" skin="tableBorderWidth" />
- <u:style name="border-style" value="solid" />
-</u:selector>
Deleted:
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-1.xml_sample
===================================================================
---
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-1.xml_sample 2011-03-21
19:11:35 UTC (rev 22288)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings-1.xml_sample 2011-03-22
05:43:42 UTC (rev 22289)
@@ -1,3 +0,0 @@
-<u:selector name=".rich-ordering-control-disabled, .rich-ordering-control-top,
.rich-ordering-control-bottom, .rich-ordering-control-up,
.rich-ordering-control-down">
- <u:style name="border-color" skin="tableBorderColor" />
-</u:selector>
Deleted:
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings.css
===================================================================
---
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings.css 2011-03-21
19:11:35 UTC (rev 22288)
+++
modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/exam-Developer_Guide-Skinning_and_theming-XCSS_style_mappings.css 2011-03-22
05:43:42 UTC (rev 22289)
@@ -1,6 +0,0 @@
-.rich-component-name {
- background-color: additionalBackgroundColor; /*the value of the constant defined by
your skin*/
- border-color: tableBorderColor; /*the value of the constant defined by your skin*/
- border-width: tableBorderWidth; /*the value of the constant defined by your skin*/
- border-style: solid;
-}