JBoss.orgCommunity Documentation
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:
skin.properties files. Refer to Section 6.3.1, “Skin parameter tables” for a listing of the skin parameters used in a typical skin.
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”.
Table 6.1. Parameter settings for the blueSky skin
| Parameter name | Default value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Support for round borders in your skins is available via 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 gracefully degrades to square corners.
Units of the panelBorderRadius skin parameter must be either px (pixels). or % (a percentage).
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.1. ECSS style mappings
The ECSS code for the <rich:panel> component contains styles for the panel and its body:
.rf-p{
background-color:'#{a4jSkin.generalBackgroundColor}';
color:'#{a4jSkin.panelBorderColor}';
border-width:1px;
border-style:solid;
padding:1px;
}
.rf-p-b{
font-size:'#{a4jSkin.generalSizeFont}';
color:'#{a4jSkin.generalTextColor}';
font-family:'#{a4jSkin.generalFamilyFont}';
padding:10px;
}
.rf-p defines the panel stylesbackground-color CSS property maps to the generalBackgroundColor skin parameter.
color CSS property maps to the panelBorderColor skin parameter.
.rf-p-b defines the panel body stylesfont-family CSS property maps to the generalFamilyFont skin parameter.
font-size CSS property maps to the generalSizeFont skin parameter.
color CSS property maps to the generalTextColor skin parameter.
Skins in RichFaces can be customized on each of the three levels:
skin.properties file to change the style of every component mapped to that skin property.
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.
<h:outputStylesheet> which rewrites of extends styles defined for style classes of components.
If you want to extend/overwrite style sheet definitions with own stylesheets, make sure you place definitions to be rendered in right order of occurence (see Restrictions section for details).
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:
generalBackgroundColor or panelBorderColor parameters in the skin. This will cause all panels in the application to change to the new settings.
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.
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>
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.
Define the skin constants
Define all the skin constants
Add skin parameter constants and values to the file. All the skin parameters listed in Table 6.1, “Parameter settings for the blueSky skin” should be included in the skin file, with settings relevant to your new skin.
Example 6.3. blueSky.skin.properties file
Open the blueSky.skin.properties file from the /META-INF/skins directory in the richfaces-core-{version}.jar package. The file lists all the skin parameter constants shown in Table 6.1, “Parameter settings for the blueSky skin”.
You can use the blueSky.skin.properties file as a template for your new skin.
Extend a base skin
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”.
Example 6.4. Using a base skin
This example takes the blueSky skin as a base and only changes the generalSizeFont parameter.
baseSkin=blueSky generalSizeFont=12px
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.
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;
}
}
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>
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.
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.
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>
The skinning style properties can be 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 configuration file:
<context-param>
<param-name>org.richfaces.enableControlSkinningClasses</param-name>
<param-value>true</param-value>
</context-param>
When enabled, a stylesheet with predefined classes offers a special 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 /META-INF/resources/org.richfaces/skinning_both.ecss file in the richfaces-core-{version}.jar package for examples of specially-defined CSS classes with skin parameters for HTML controls.