Developing and Using ADF Faces Skins
Jonas Jacobi, Oracle Corporation
Introduction to the The ADF Faces Skinning Feature
ADF Faces lets you change the appearance or look and feel of an application without having to rewrite the code that implements the application's user interface. ADF Faces provides two parent skins, Simple and Minimal, which you can extend to provide custom skins for your applications. By default a custom skin inherits the appearance of its parent look and feel. When you wish to modify the appearance of a component, you simply provide custom style definitions, custom icons.
This HowTo demonstrates how to create a simple ADF Faces skin, that replaces the default Oracle skin, with Oracle JDeveloper 10.1.3. For more information and HowTos, please, refer to the JDeveloper HowTo documents on Oracle Technology Network (OTN). For this simple application we are using only using ADF Faces components, and no business logic.
This article covers the following tasks:
There are no specific editor requirements to follow this HowTo and build this new ADF Faces Skin, but for educational purposes we are going to use the Oracle JDeveloper 10.1.3 EA1 release - optionally you may need an image editor if you want to edit and replace images provided by this HowTo. You also need to download the sample WAR file - adffaces_skin.war - that contains a newer version of ADF Faces needed for this How To, and a simple JSF page with some ADF Faces components that we will use to illustrate the effect of the new skin.
ADF Faces Default Skins
ADF Faces provides three main skins that are provided for you to use "as is" in your applications - Oracle (oracle), Minimal (minimal), and Simple (simple). The default skin for your application is set to "oracle", which conform to Oracle's UI standards (Browser Look and Feel - BLAF) for applications. The Minimal skin provides some formatting and the Simple skin contains almost no special formatting.
A skin in ADF Faces is a global style sheet that only needs to be set in one place for the entire application. Instead of having to style each component, or having to insert a style sheet on each page, you can create one skin for the entire application. Every component will automatically use the styles as described by the skin. Any changes to the skin will be picked up at runtime, no change to code is needed. Skins are based on the Cascading Style Sheet specification, and is using CSS 3.0 syntax.
In addition to using a CSS file to determine the styles, skins also use a resource bundle to determine the text. For example, the words "Previous" and "Next" in the navigation bar of the ADF Faces table component, is determined using the skin�s resource bundle. All the included skins use the same resource bundle.
Creating a Custom Skin
You create a custom skin by extending the Simple skin and overriding the provided selectors. There are three different types of selectors - Global, Button, and Component-level selectors.
To create a custom skin
In most cases you will probably not customize the skin of every component available in the ADF Faces component library (there are after all 84 UI components.) By reviewing your application using, for example, the Simple skin you can determine what components to customize.
Note: At the moment application developer can only extend the Simple skin.
If you have not downloaded Oracle JDeveloper 10.1.3 EA 1 release, yet, it is now time to do so. Unzip and launch JDeveloper.
Figure 1. Screenshot of the sample.jspx page as shown in JDeveloper 10.1.3
A skin consists of the following artifacts:
Modifying the ADF Faces Skin CSS
The sample application already contains a pre-canned CSS file that we are going to use and extend in order to create the look and feel we need for our components. To this file you can add any selectors that you wish to override to your CSS file, and set the properties as needed. You can set any properties as supported by the CSS specification. You can also create your own alias classes.
The sample application also contains an adf-faces-skins-doc.xml file. This file contains information about all style classes and selctors that are provided by ADF Faces and that you can override. The file is located in the skins directory.
Figure 2. The adf-faces-skins-doc.xml file located in the skins directory
Changing the Color Schema of a Skin
The easiest part of changing the look of your application is to change the base classes of a skin to use other colors. For example the Simple skin looks like this without changes:
and with some very minor changes to the following alias classes:
you can change the look and feel by changing the style classes controlling the base colors of the Simple skin:
Adding a Skin to an ADF Faces Component
The components that we are going to provide a skin for are - af:selectOneShuttle, af:selectManyShuttle, and af:selectInputDate. We are going to start with the af:selectInputDate component. At the moment the af:selectInputDate component looks like this with the Oracle Look and Feel:
but we would like to change to look like this:
To able to do this we need to add the component selector for the af:selectInputDate component. By adding the following code sample to the myComponent.css file we can change the icon of the Calendar launch button.
Next we are going to look at the ADF Faces shuttle control. There are two shuttle controls available in ADF Faces - af:selectOneShuttle and af:selectOneShuttle. You can adjust the skin for each one of them or create one skin for both. This component is slightly more complex than the af:selectInputDate component with more controls and attributes that can be adjusted. The default look and feel for these to controls is this:
and we are going to change it to:
By using the alias class of the shuttle controls we can add a set of icons to the skin that are generic to all shuttle controls. We have also added icons that are unique to the selectOrderShuttle control by using the component specific selector. It is important that you add width and height to any style using images/icons, since some browser might have problems displaying the actual icons, for example Internet Explorer.
Note: There is a bug in ADF Faces that will break the image/icons in case you add "" around the actual URI, for example
The sample skin contains more styles than what we will be able to cover in this HowTo. There are three other components covered in the actual CSS file - af:table, af:showOneTab, and af:menuTabs - that are worth looking at.
Setup of a Custom Skin
Let's now have a look at how to setup your application to use an ADF Faces custom skin.
First of all we need the CSS file, stored somewhere at the root of your web application. In the sample application it stored in the /skin/myCompany director. We should also make sure that we have access to all resources need for the skin, for example images and other CSS files. In the sample application these are stored in the /skin/myCompany/images directory.
Secondly, we need to make sure that our ADF Faces application is aware of the custom skin. This is done by adding a configuration file to the WEB-INF directory called adf-faces-skins.xml.
Register a Custom Skin
The <id> element is used to reference your skin in an EL expression. For example, if you want to have different skins for different locals, you can create an EL expression that will select the correct skin based on its ID.
The <family> element configures an application to use a particular family of skins. This allows you to group skins together for an application, based on the render kit used.
The <render-kit-id> determines which render-kit to use for the skin. You can enter one of the following:
The <style-sheet-name> element defines the path to the custom CSS file.
Configuring an Application to Use a Custom Skin
You set an element in the adf-faces-config.xml file that determines which skin to use, and if necessary, under what conditions. To configure an application to use a skin:
Let's now add the actual component that will perform the actual swithcing at runtime
Creating ADF Faces skins are easy and using them even easier. An application developer can set a skin based on any criteria using EL expression and JSF backing beans (not shown in this sample). This allows application developers to have different skins per user, page, application, and so on, without impacting the actual application logic!