JBoss.orgCommunity Documentation

Chapter 6. Skinning and theming

6.1. What are skins?
6.2. Using skins
6.3. Customizing skins
6.4. Skin parameter tables in RichFaces
6.5. Changing skins at runtime
6.6. Creating a new skin
6.7. Skinning standard controls
6.7.1. Skinning standard JSF components
6.7.2. Skinning standard HTML controls
6.8. Defining skins for individual components
6.9. Plug-n-skin

Documentation in development

Some concepts covered in this chapter may refer to the previous version of Richfaces, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date.

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

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 themes to be changed at runtime, so users can personalize an application's appearance.

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 designed to use a combination of styling elements. Themes for components can be applied using any of the following style classes:

Table 6.1, “Parameter settings for the blueSky skin” lists the default values for the parameter settings in the blueSky skin. These values can be customized and extended for a unique application theme as described in Section 6.3, “Customizing skins”.

The user can change skins at runtime if a managed bean is used to access the skin.

Example 6.2. Skin changing example

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.

    <div style="display: block; float: left">
        <h:selectOneRadio value="#{skinBean.skin}" border="0" layout="pageDirection" title="Changing skin" style="font-size: 8; font-family: comic" onchange="submit()">
            <f:selectItem itemLabel="plain" itemValue="plain" />
            <f:selectItem itemLabel="emeraldTown" itemValue="emeraldTown" />
            <f:selectItem itemLabel="blueSky" itemValue="blueSky" />
            <f:selectItem itemLabel="wine" itemValue="wine" />
            <f:selectItem itemLabel="japanCherry" itemValue="japanCherry" />
            <f:selectItem itemLabel="ruby" itemValue="ruby" />
            <f:selectItem itemLabel="classic" itemValue="classic" />
            <f:selectItem itemLabel="laguna" itemValue="laguna" />
            <f:selectItem itemLabel="deepMarine" itemValue="deepMarine" />
            <f:selectItem itemLabel="blueSky Modified" itemValue="blueSkyModify" />
    <div style="display: block; float: left">
        <rich:panelBar height="100" width="200">
            <rich:panelBarItem label="Item 1" style="font-family: monospace; font-size: 12;">
                Changing skin in runtime
            <rich:panelBarItem label="Item 2" style="font-family: monospace; font-size: 12;">
                This is a result of the modification "blueSky" skin

Figure 6.1. Skin changing example

  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 skin constants

    Add skin parameter constants and values to the file. Example 6.3, “blueSky.skin.properties file” shows how the skin parameters listed in Table 6.1, “Parameter settings for the blueSky skin” are included in the skin file.

    Example 6.3. blueSky.skin.properties file

    The blueSky.skin.properties file lists all the skin parameter constants for the skin. It can be extracted from the /META-INF/skins directory in the richfaces-impl-version.jar package.

    generalFamilyFont=Arial, Verdana, sans-serif 
    # Fonts
    headerFamilyFont=Arial, Verdana, sans-serif
    tabFamilyFont=Arial, Verdana, sans-serif
    buttonFamilyFont=Arial, Verdana, sans-serif
    #Calendar colors

    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 baseSkin parameter in the skin file, as shown in Example 6.4, “Using a base skin”.

  3. Reference skin definition

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


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:

Skinning for standard HTML controls can be included in one of two ways:

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.

Browser lists may need to be updated.

Extended skinning

  • Microsoft Internet Explorer 7 in standards-compliant mode

  • Mozilla Firefox

If the browser type cannot be identified, the extended level is used. Set the level explicitly by adding the following context parameter to the web.xml configuration file, and specifying the <param-value> element as either basic or extended:


RichFaces uses XCSS (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.

XCSS files contain mappings between CSS properties and skin parameters. The name attribute of the <u:selector> element is the name of the CSS selector. Each <u:style> element defines a CSS property with the name attribute as its name. Using the skin attribute specifies a skin parameter from the current skin file, while using the value attribute enters the literal value in the CSS file. An example of this is shown in Example 6.5, “XCSS style mappings”.

Style properties can be modified using XML-based XCSS code, or using embedded standard CSS code, as shown in Example 6.6, “Using XCSS code or standard CSS code”

Plug-n-skin 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.

  1. Create a template

    Use the Maven build and deployment tool to create the skin template by using the following command:

    mvn archetype:create -DarchetypeGroupId=org.richfaces.cdk -DarchetypeArtifactId=maven-archetype-plug-n-skin -DarchetypeVersion=RF-VERSION -DartifactId=ARTIFACT-ID -DgroupId=GROUP-ID -Dversion=VERSION

    Use the following parameters for the command:

  2. Add the skin to the CDK

    Change to the newly-created directory. Ensure it contains the pom.xml project file, then enter the following command to create a new skin and add it to the CDK (Component Development Kit):

    mvn cdk:add-skin -Dname=SKIN-NAME -Dpackage=SKIN-PACKAGE

    Use the following parameters for the command:

    Use the following optional keys for advanced features:

    The command creates the following files:

  3. Edit XCSS files

    Edit the XCSS files contained in the src/main/resources/META-INF/skins/ directory. Refer to Section 6.8, “Defining skins for individual components” for instructions on how to edit XCSS files.

  4. Build the skin

    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 pom.xml file).

    mvn clean install
  5. Add the skin to the project configuration

    Add the following context parameter to your project's web.xml configuration file to use the new skin in your application: