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:

  • DEFAULT
  • plain, which contains no skin parameters and is intended for embedding RichFaces components into existing projects with their own styles.
  • emeraldTown
  • blueSky
  • wine
  • japanCherry
  • ruby
  • classic
  • deepMarine

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


<context-param>
    <param-name>org.richfaces.skin</param-name>
    <param-value>skin_name</param-value>
</context-param>

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:

Skin property files
Application interfaces can be modified by altering the values of skin parameters in the skin itself. Edit the constant values defined in the skin.properties file to change the style of every component mapped to that skin property.
Component stylesheets
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.
Custom components style classes
Individual components can use the styleClass 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 styleClass attribute.
Overwriting stylesheets in application
You can load custom stylesheets using <h:outputStylesheet> which rewrites of extends styles defined for style classes of components.

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
   </div>
</div>

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">
       ...
    </div>

  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:

    
    <context-param>
       <param-name>org.richfaces.skin</param-name>
       <param-value>new_skin_name</param-value>
    </context-param>

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

  1. Create the skin bean

    The skin bean is a simple interface to manage the skin:

    public class SkinBean {
    
    
        private String skin;
        public String getSkin() {
            return skin;
        }
        public void setSkin(String skin) {
            this.skin = skin;
        }
    }
  2. Reference the skin bean

    Add the @ManagedBean and @SessionScoped references to the class.

    • Alternatively, use EL (Expression Language) to reference the skin bean from the web.xml settings file.

      
      <context-param>
          <param-name>org.richfaces.skin</param-name>
          <param-value>#{skinBean.skin}</param-value>
      </context-param>
  3. Set initial skin

    The application needs an initial skin to display before the user chooses an alternative skin. Specify the skin in your class with @ManagedProperty.

    @ManagedProperty(value="blueSky")
    
    private String skin;
    • Alternatively, specify the initial skin in the web.xml configuration file.

      
      <managed-bean>
          <managed-bean-name>skinBean</managed-bean-name>
          <managed-bean-class>SkinBean</managed-bean-class>
          <managed-bean-scope>session</managed-bean-scope>
          <managed-property>
              <property-name>skin</property-name>
              <value>blueSky</value>
          </managed-property>
      </managed-bean>

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