6.5. Components for Skinning

⁠6.5. Components for Skinning

⁠6.5.1. About Skins

Application skins are used with the RichFaces framework to change the appearance of an application by setting the visual elements of controls and components. Typically the appearance of web applications is handled through CSS files associated with the application, but skinning allows CSS settings to be 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 for defining 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).

Skins can be changed at runtime so users can personalize an application's appearance on the fly.

Report a bug

⁠6.5.2. Using Predefined Skins

RichFaces includes the following predefined skins:

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>

Report a bug

⁠6.5.3. Using Custom Skins

There are many ways to modify skins to suit the style of your layout. Custom skins can be used to attain total control over how the layout appears.

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 implemented using ECSS files.
Skin property files: Skin property files map skin parameters to constant styles. Skin properties are defined in skin.properties files.
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.

Report a bug

⁠6.5.3.1. Modifying Predefined Skins

Skins in RichFaces can be customized in several ways:

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: Load custom stylesheets using <h:outputStylesheet>, which rewrites and extends styles defined for style classes of components.

Note

To extend or overwrite style sheet definitions with your own stylesheets, ensure their definitions are placed to be rendered in the correct order of occurrence.

Report a bug

⁠6.5.3.2. Creating a New Skin

⁠

Procedure 6.1. Creating a New Skin

Create a new text file and name it following the format new_skin_name.skin.properties. Save it to either your project's /WEB-INF/classes directory.
Define the skin constants
1. Add skin parameter constants and values to the file.
  ⁠
  Example 6.14. blueSky.skin.properties file
  Open the /META-INF/skins/blueSky.skin.properties file in the richfaces-impl-version.jar package. This file lists the constants and values of the skin.
  You can use the blueSky.skin.properties file as a template for your new skin.
2. 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.
  ⁠
  Example 6.15. Using a base skin
  This example takes the blueSky skin as a base and only changes the generalSizeFont parameter.
```
baseSkin=blueSky
generalSizeFont=12pt
```
To add the skin, navigate to the project's home directory and open the web.xml settings file. Add a <context-param> property and the new skin's filename to the settings file:
```
<context-param>
   <param-name>org.richfaces.skin</param-name>
   <param-value>new_skin_name</param-value>
</context-param>
```
Save the web.xml settings file and exit. The new skin loads when you build the project.

Report a bug

⁠6.5.3.3. Using Round Corners

Support for adding round borders to skins is available with the panelBorderRadius skin parameter. The value of this parameter maps to the CSS 3 border-radius property. This CSS 3 property is ignored in older browsers, and the skin reverts to square corners.

Units of the panelBorderRadius skin parameter must be either px (pixels) or % (a percentage). The greater the pixels or percentage, the more rounded the edges are.

Report a bug

⁠6.5.3.4. Adding Extra Skinning Functionality with ECSS

RichFaces uses ECSS files to add extra functionality to the skinning process. ECSS files are CSS files which use Expression Language (EL) to connect styles with skin properties.

⁠

Example 6.16. ECSS style mappings

The ECSS code for the <rich:panel> component contains styles for the panel and its body:

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

.rf-p defines the panel styles

The background-color CSS property maps to the generalBackgroundColor skin parameter.
The color CSS property maps to the panelBorderColor skin parameter.

.rf-p-b defines the panel body styles

The font-family CSS property maps to the generalFamilyFont skin parameter.
The font-size CSS property maps to the generalSizeFont skin parameter.
The color CSS property maps to the generalTextColor skin parameter.

Report a bug

⁠6.5.4. Enabling Skin Changes when Applications are Running

⁠

Procedure 6.2. Enabling Skin Changes During Runtime

To enable changing skins during runtime, a new skin bean is required. Add the following to your skin:

public class SkinBean {

    private String skin;

    public String getSkin() {
        return skin;
    }
    public void setSkin(String skin) {
        this.skin = skin;
    }
}

Reference the skin bean
Add the @ManagedBean and @SessionScoped references to the class.
- Alternatively, use EL 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>
```

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

Report a bug

⁠6.5.5. Applying Skins to Standard HTML Controls

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

Automatic skinning

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 are styled according to the mapped skin properties.

Standard HTML controls are skinned in this way by default. To override this behavior and prevent the RichFaces skins from being applied to the standard HTML controls, set the org.richfaces.enableControlSkinning context parameter in the web.xml configuration file to false:

<context-param>
   <param-name>org.richfaces.enableControlSkinning</param-name>
   <param-value>false</param-value>
</context-param>

Skinning with the rfs-ctn class

The skinning style properties are determined through a separate CSS class. This method is not available by default, but is enabled through the org.richfaces.enableControlSkinningClasses context parameter in the web.xml settings file:

<context-param>
   <param-name>org.richfaces.enableControlSkinningClasses</param-name>
   <param-value>true</param-value>
</context-param>

When enabled, a stylesheet with predefined classes generates a CSS class named rfs-ctn. Reference the rfs-ctn class from any container element (such as a <div> element) to skin all the standard HTML controls in the container.

Standard HTML controls can also be specifically defined in the CSS. Refer to the /core/impl/src/main/resources/META-INF/resources/skinning_both.ecss file in the richfaces-ui.jar package for examples of specially-defined CSS classes with skin parameters for HTML controls.

Report a bug