Developing and Using ADF Faces Skins
Created by Jonas Jacobi, Oracle Corporation
January, 2006
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.
Tasks
This article covers the following tasks:
- Create a new Style sheet (CSS 3.0 syntax) that overrides the simple
theme style sheet.
- Create a new ADF Faces skin configuration file -
adf-faces-skins.xml
- Adding images where needed
- Change text on specific components
- Set the new ADF Faces skin in the
adf-faces-config.xml file
Prerequisites
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.
About Skins
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.
- Global Style selectors are selectors that affect more than one
component. If the selector name ends in the :alias pseudo-class, then the
selector is most likely included in other component-specific selectors.
Defining properties for a selector that ends in :alias will most likely
affect the skin for more than one component.
- Component-level selectors are selectors that can be used to skin a
particular ADF Faces component. The selectors defined below are specified by
the component they affect. Let's say you want to skin the
af:chooseDate
component. One of the selectors is
af|chooseDate::title. The
::title
pseudo-element indicates that this is the title portion of the
af:chooseDate
component. If you want to skin the title of the
af:chooseDate component, you
would set css properties on the
af|chooseDate::title selector in your ADF
Faces skin .css file.
You may see selector names that end in :alias in the component-level
section. These are meant to provide short-cuts to skin more than one
component that share a certain style or icon, or to skin more than one piece
of a component. For example, the
.AFMenuBarItem:alias style defines skin
properties that are shared by all
af:menuBar items. This is included by the
af|menuBar::enabled and
af|menuBar::selected style classes. Therefore, if
you change the .AFMenuBarItem:alias style, you will affect the
af|menuBar::enabled and
af|menuBar::selected style selectors.
- ADF Faces does not currently support component-level selectors for
buttons. For example, you cannot customize a
goButton differently from a
commandButton. Skinning supports two very different button implementations.
By default, standard browser buttons are used. However, the skinning also
supports dynamic generation of image-based buttons. In order to enable
image-based buttons, the following four button icon must be specified:
1. .AFButtonStartIcon:alias
2. .AFButtonEndIcon:alias
3. .AFButtonTopBackgroundIcon:alias
4. .AFButtonBottomBackgroundIcon:alias
When these four icons are specified, ADF Faces combines the images specified
by these icons into a single button image. (Note: These icons must be
specified using either context-image or resource-image icons. Text-based
icons are not allowed.)
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.
- In JDeveloper, create a new Application workspace and name it -
ADFFaces_skin_sample.
Cancel the dialog asking to create a new project.
- Right click on the new Application workspace and create a new "Project
from WAR file" and click OK.
- Enter view as
the new name for this project and click Next.
- In the dialog for selecting a WAR file, select the
adffaces_skin.war
file you just downloaded. Click FINISH to
close the dialog.
- Before we can view the sample page in the visual editor we first have to
make sure that the ADF Faces libraries shipped with the WAR file is executed
in the Visual Editor. Double click on the view project node to open the
Project Properties dialog.
- In the Project Properties dialog select the JSP Tag Libraries and make
sure that the "Execute Tags in JSP Visual Editor" option is checked on both
ADF Faces libraries.
- IMPORTANT: You also need to add the JSF Core and JSF HTML tag libraries as shown in the
above figure.
- Close the dialog by click OK.
- Locate the sample.jspx and open it in the visual editor.
- Acquaint yourself with the page to understand what is there in form of
ADF Faces components.
- Make sure that you also look at the files provided for this skin sample
application.
Figure 1. Screenshot of the sample.jspx page as shown in JDeveloper 10.1.3
A skin consists of the following artifacts:
- A CSS file that defines the actual look of the components
- A configuration file -
adf-faces-skins.xml - that lists all skins available for this
application (not including Oracle, Minimal, and Simple). This file has to be
located in your applications
WEB-INF directory
- An entry in the ADF Faces configuration file -
adf-faces-config.xml
- Any other resources need to create the actual look of the componets -
additional CSS files, Images etc...
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:
.AFDarkForeground:alias
{color:#003366;}
.AFDarkBackground:alias {background-color:#003366;}
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.
- Open the myCompanySkin.css file by double clicking on it. This will
bring up the JDeveloper CSS editor.
- Search for the section at the top of the
myCompany.css file that starts
with the following:
/** Section where to add
styles/selectors used in the ADF Faces Skin Sample **/ /**
======================================================================= **/
- Add the following selectInputDate style class code snippet to just below
the comment
/** selectInputDate launch icon **/
af|selectInputDate::launch-icon {
content:url(/skins/mycompany/skin_images/timedate_ena.png);
}
af|selectInputDate::launch-icon:rtl {
content:url(/skins/mycompany/skin_images/timedate_ena.png);
}
- Save your changes.
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:
- In the myCompany.css
file add the following code snippet just below the
selectInputDate
styles
/** Shuttle icons selectOne, selectMany, and selectOrder shuttles**/
.AFShuttleMoveIcon:alias {content:url(/skins/mycompany/skin_images/move.png);
width: 16px; height: 16px;}
.AFShuttleMoveAllIcon:alias {content:url(/skins/mycompany/skin_images/moveAll.png);
width: 16px; height: 16px;}
.AFShuttleRemoveIcon:alias {content:url(/skins/mycompany/skin_images/remove.png);
width: 16px; height: 16px;}
.AFShuttleRemoveAllIcon:alias {content:url(/skins/mycompany/skin_images/removeAll.png);
width: 16px; height: 16px;}
/** Icons unique to the selectOrderShuttle for re-ordering user selections
**/
af|selectOrderShuttle::reorder-top-icon {
content:url(/skins/mycompany/skin_images/reordertop_enabled.png);
width: 16px;
height: 16px;
}
af|selectOrderShuttle::reorder-up-icon {
content:url(/skins/mycompany/skin_images/reorderup_enabled.png);
width: 16px;
height: 16px;
}
af|selectOrderShuttle::reorder-down-icon {
content:url(/skins/mycompany/skin_images/reorderdown_enabled.png);
width: 16px;
height: 16px;
}
af|selectOrderShuttle::reorder-bottom-icon {
content:url(/skins/mycompany/skin_images/reorderbottom_enabled.png);
width: 16px;
height: 16px;}
- Save your work.
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
url("/skins/mycompany/skin_images/reorderdown_enabled.png")
This will cause the icons to not show up at rendering. The fix is to
remove the "".
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:
- oracle.adf.desktop:
the skin will automatically be used when the application is rendered on a
desktop.
- oracle.adf.pda:
the skin will be used when rendered on a PDA.
The <style-sheet-name>
element defines the path to the custom CSS file.
- In JDeveloper, right click on the
WEB-INF folder of
the sample project and create a new XML document and name it -
adf-faces-skins.xml
- Replace the generated code with the following:
<?xml version="1.0"
encoding="ISO-8859-1"?>
<skins xmlns="http://xmlns.oracle.com/adf/view/faces/skin">
<skin>
<id>mycompany.desktop</id>
<family>mycompany</family>
<render-kit-id>oracle.adf.desktop</render-kit-id>
<style-sheet-name>skins/mycompany/myCompanySkin.css</style-sheet-name>
</skin>
</skins>
- Save your work.
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:
- Open the adf-faces-config.xml
file.
- Replace the
<skin-family> value with the family name for the skin(s) you wish to
use.
- To conditionally set the value, enter an EL expression that can be
evaluated to determine the skin to display.
For example, if you want to use the German skin if the user's browser is set
to the German locale, and use the English skin otherwise, you could have the
following entry in the adf-faces-config.xml file.<skin-family>#{facesContext.viewRoot.locale.language=='de'
? 'german' : 'english'}</skin-family>
- In the sample application we are going to use
selectOneChoice
component to switch skins at runtime, so we need to replace the following
<skin-family>oracle</skin-family> in the
adf-faces-config.xml
file with:
<skin-family>#{sessionScope.skinFamily}</skin-family>
- Save your work.
Let's now add the actual component that will perform the actual swithcing at
runtime
- Open the sample.jspx
file in the source code editor.
- Locate the following comment in the source:
<!--
================================================================ -->
<!-- Add the sample selectOneChoice component here. -->
- Now add the following code snippet:
<f:facet name="menuGlobal">
<af:selectOneChoice label="Select Skin" value="#{sessionScope.skinFamily}"
onchange="form.submit();">
<af:selectItem label="Simple" value="simple"/>
<af:selectItem label="Minimal" value="minimal"/>
<af:selectItem label="Oracle" value="oracle"/>
<af:selectItem label="MyCompany" value="mycompany"/>
</af:selectOneChoice>
</f:facet>
The onchange event handler will perform a form
POST when ever a
skin is selected in the
selectOneChoice component. Alternative you can add a commandButton to
the page that will re-submit the page. Every time there is a
POST the EL
expression will be evaluated, and if there is a new value redraw the page
with the new skin.
- Save your work and run the
sample.jspx page.
Use the switcher to select a skin!
Summary
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!
| 
Bookmark
