JBoss.orgCommunity Documentation

Chapter 6. Skinning and theming

6.1. What are skins?
6.2. Using skins
6.3. Skinning overview
6.3.1. Skin parameter tables
6.3.2. Support for round corners
6.3.3. ECSS files
6.4. Customizing skins
6.4.1. Creating a new skin
6.5. Changing skins at runtime
6.6. Skinning standard controls
6.6.1. Automatic skinning
6.6.2. Skinning with the rfs-ctn class

Read this chapter for a guide to skinning and theming RichFaces applications, including how to implement themes, and details on customizing and extending skins.

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 CSS (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.

Each skin has a set of skin-parameters, 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 (EL).

The skinning feature of RichFaces also allows skins to be changed at runtime, so users can personalize an application's appearance on the fly.

RichFaces includes a number of predefined skins. These skins can be used in RichFaces web applications by specifying the skin name in the org.richfaces.skin context parameter in the web.xml settings file. The predefined skins are as follows:

To add one of these skins to your application, add the org.richfaces.SKIN context parameter to the web.xml configuration file:


RichFaces skins are implemented using the following three-level scheme:

Component stylesheets

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 Section 6.3.3, “ECSS files” for details on ECSS files.

Skin property files

Skin property files map skin parameters to constant styles. Skin properties are defined in skin.properties files. Refer to Section 6.3.1, “Skin parameter tables” for a listing of the skin parameters used in a typical skin.

Custom style classes

Individual components can use the styleClass 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.

Table 6.1, “Parameter settings for the blueSky skin” lists the default values for the parameter settings in the blueSky skin. These values are all listed in the blueSky.skin.properties file, which can be customized and extended as described in Section 6.4, “Customizing skins”.

Skins in RichFaces can be customized on each of the three levels:

Example 6.2. Simple skinning example

Using any component, such as a panel, without specifying a styleClass will use the default skin parameters for that component.

<rich:panel>This is a panel without a header</rich:panel>

When rendered for display, the panel consists of two HTML elements: a wrapper <div> element and a <div> element for the body of the panel. The wrapper element for a panel without a specified styleClass is rendered as follows:

<div id="..." class="rf-p">
   <div id="..." class="rf-p-b">
      This is a panel without a header

To customize the panel appearance according to the three-level scheme, adjust the styles according to the following approach:

  1. Change the definitions for the generalBackgroundColor or panelBorderColor parameters in the skin. This will cause all panels in the application to change to the new settings.

  2. Redefine the rf-p 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.

  3. Specify a different styleClass attribute to style the individual component. If a styleClass attribute is used, the specified style class is applied to the component, which could extend or override the default styles.

    <rich:panel styleClass="customClass">...</rich:panel>

    The customClass style is added to the CSS, and is applied to the component when it is rendered for display:

    <div class="rf-p customClass">

  1. Create the skin file

    The name of the skin file should follow the format new_skin_name.skin.properties and is placed in either the META-INF/skins/ directory or the classpath directory of your project.

  2. Define the skin constants

  3. Reference the skin definition

    Add a skin definition <context-param> to the web.xml settings file of your application:

    new_skin_name </param-value>

To allow users to change skins at runtime, use a managed bean to access the skin.

Standard HTML controls used alongside RichFaces components are also themed to create a cohesive user interface.