14.3 Using Skins to Change the Look and Feel

Skins allow you to globally change the appearance of ADF Faces components within an application. A skin 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. The application developer does not need to add any code, and any changes to the skin will be picked up at runtime, no change to code is needed.

Skins are also based on the Cascading Style Sheet specification. By default, ADF Faces applications use the Oracle skin. Components in the visual editor as well as in the web page display using the settings for this skin. Figure 14-1 shows the SRList page with the Oracle skin applied.

Note:

The syntax in a skin style sheet is based on the CSS3 specification. However, many browsers do not yet adhere to this version. At runtime, ADF Faces converts the CSS to the CSS2 specification.

Figure 14-1 The SRList Page Using the Oracle Skin

ADF Faces also provides two other skins. The Minimal skin provides some formatting, as shown in Figure 14-2. Notice that almost everything except the graphic for the page has changed, including the colors, the shapes of the buttons, and where the copyright information displays.

Figure 14-2 The SRList Page Using the Minimal Skin

The SRList page with minimal formatting.

The third skin provided by ADF Faces is the Simple skin. This skin contains almost no special formatting, as shown in Figure 14-3.

Figure 14-3 The SRList Page Using the Simple Skin

The SRDemo application uses a custom skin created just for that application, as shown in Figure 14-4.

Figure 14-4 The SRList Page Using the Custom SRDemo Skin

In addition to using a CSS file to determine the styles, skins also use a resource bundle to determine the text within a component. For example, the word "Select" in the selection column shown in Figure 14-4 is determined using the skin's resource bundle. All the included skins use the same resource bundle.

14.3.1 How to Use Skins

Custom skins extend the Simple skin. To create a custom skin, you declare selectors in a style sheet that override the selectors in the Simple skin's style sheet. Any selectors that you choose not to override will continue to use the style as defined in the Simple skin. Once you create your skin's style sheet, you need to register it as a valid skin in the application, and then configure the application to use the skin.

The selectors used by the simple skin are listed in the "Selectors for Skinning ADF Faces Components" topic in JDeveloper's online help. It is located in the Reference > Oracle ADF Faces > book. This document shows selectors broken down into three sections: global selectors, button selectors, and component-level selectors. Global selectors determine the style properties for multiple components. Examples include the default font family and background colors. Button selectors are used to style all buttons in the application.

Note:

Button selectors style all buttons in the application. You cannot define separate selectors for different buttons. For example, the af:commandButton and af:goButton components will display the same.

Component selectors determine the styles for specific components or portions of a component. Icon selectors denote where the icon can be found.

Within each section are the selectors that can be styled. There are three types of selectors: standard selectors, selectors with pseudo elements, and selectors that use the alias pseudo classes. Standard selectors are those that directly represent an element that can have styles applied to it. For example af|body represents the af:body component. You can set CSS styles, properties, and icons for this type of element.

Pseudo elements are used to denote a specific area of component that can have styles applied. Pseudo elements are denoted by a double colon followed by the portion of the component the selector represents. For example, af|column::cell-text provides the styles and properties for the text in a cell of a column.

The alias pseudo class is used for a selector that sets styles for more than one component or more than one portion of a component. For example, the .AFMenuBarItem:alias selector defines skin properties that are shared by all af:menuBar items. Any properties defined in this alias are included in the af|menuBar::enabled and af|menuBar::selected style classes. If you change the .AFMenuBarItem:alias style, you will affect the af|menuBar::enabled and af|menuBar::selected selectors. You can also create your own pseudo classes for inclusion in other selectors.

You can create multiple skins. For example, you might create one skin for the version of an application for the web, and another for when the application runs on a PDA. Or you can change the skin based on the locale set on the current user's browser.

The text used in the skins is defined in a resource bundle. As with the selectors for the Simple skin, you can override the text by creating a custom resource bundle and declaring only the text you want to change. The keys for the text that you can override are documented in the "Reference: Keys for Resource Bundle Used by Skins" topic of the JDeveloper online help. Once you create your custom resource bundle, you register it with the skin.

Note:

ADF Faces components provide automatic translation. The resource bundle used for the components' skin is translated into 28 languages. If a user sets the browser to use the German (Germany) language, any text contained within the components will automatically display in German. For this reason, if you create a resource bundle for a custom skin, you must also create localized versions of that bundle for any other languages the application supports. For more information about Internationalization, see Section 14.4, "Internationalizing Your Application".

14.3.1.1 Creating a Custom Skin

You create a custom skin by extending the Simple skin and overriding the selectors. You then need to register the skin with the application.

To create a custom skin:

Review your pages using the Simple skin to determine what you would like to change. For procedures on changing the skin, see Section 14.3.1.2, "Configuring an Application to Use a Skin".
In JDeveloper, create a CSS file:
1. Right-click the project that contains the code for the user interface and choose New to open the New Gallery.
2. In the New Gallery, expand the Web Tier node and select HTML.
3. Double-click CSS File.
4. Complete the Create Cascading Style Sheet dialog. Click Help for help regarding this dialog.
Refer to the "Selectors for Skinning ADF Faces Components" topic in JDeveloper's online help. It is located in the Reference > Oracle ADF Faces > book. Add any selectors that you wish to override to your CSS file and set the properties as needed. You can set any properties as specified by the CSS specification.

If you are overriding a selector for an icon, use a content relative path for the URL to the icon image (that is, start with a leading forward slash), and do not use quotes. Also, you must include the width and the height for the icon. Example 14-2 shows a selector for an icon.
Example 14-2 Selector for an Icon
```
.AFButtonDisabledStartIcon:alias
 {
      content:url(/skins/srdemo/images/btnDisabledStart.gif);
      width:7px; height:18px
 }
```
Icons and buttons can both use the rtl pseudo class. This defines an icon or button for use when the application displays in right-to-left mode. Example 14-3 shows the rtl psuedo class used for an icon.
Example 14-3 Icon Selector Using the rtl Psuedo Class
```
.AFButtonDisabledStartIcon:alias:rtl
 {
      content:url(/skins/srdemo/images/btnDisabledStartRtl.gif);
      width:7px; height:18px
 }
```
Tip:
Overriding an alias will likely change the appearance of more than one component. Be sure to carefully read the reference document so that you understand what you may be changing.
Y ou can create your own alias classes that you can then include on other selectors. To do so:
1. Create a selector class for the alias. For example, the SRDemo skin has an alias used to set the color of a link when a cursor hovers over it:
```
.MyLinkHoverColor:alias {color: #CC6633;}
```
2. To include the alias in another selector, add a pseudo element to an existing selector to create a new selector, and then reference the alias using the -ora-rule-ref:selector property.
  
  For example, the SRDemo skin created a new selector for the af|menuBar::enabled-link selector in order to style the hover color, and then referenced the custom alias, as shown in Example 14-4.
  Example 14-4 Referencing a Custom Alias in a New Selector
```
af|menuBar::enabled-link:hover
{
  -ora-rule-ref:selector(".MyLinkHoverColor:alias");
}
```
Save the file to a directory.

Once you've created the CSS, you need to register the skin and then configure the application to use the skin.

To create a custom bundle for the skin:

Review the "Reference: Keys for Resource Bundle Used by Skins" topic of the JDeveloper online help and your pages using the Simple skin to determine what text you would like to change. For procedures on changing the skin to the Simple skin, see Section 14.3.1.2, "Configuring an Application to Use a Skin".
In JDeveloper, create a resource bundle. It must be of type java.util.ResourceBundle. For detailed instructions, see Section 14.4.1, "How to Internationalize an Application"

Add any keys to your bundle that you wish to override and set the text as needed.

Tip:

If you internationalize your application, you must also create localized versions of this resource bundle. For more information and procedures, see Section 14.4.1, "How to Internationalize an Application".

To register a custom skin and bundle:

If one does not yet exist, create an adf-faces-skins.xml file (the file is located in the <view_project_name>/WEB-INF directory). This file will be used to declare each skin accessible to the application.
1. Right-click your view project and choose New to open the New Gallery.
  
  The New Gallery launches. The file launches in the Source editor.
2. In the Categories tree on the left, select XML. If XML is not displayed, use the Filter By dropdown list at the top to select All Technologies.
3. In the Items list, select XML Document and click OK.
4. Name the file adf-faces-skins.xml, place it in the <view_project_name>/WEB-INF directory, and click OK.
5. Replace the generated code with the code shown in Example 14-5.
  Example 14-5 Default Code for an adf-faces-skins.xml File
```
<?xml version="1.0" encoding="ISO-8859-1"?>
<skins xmlns="http://xmlns.oracle.com/adf/view/faces/skin">
    
  <skin>

  </skin>
 
</skins>
```
Register the new skin by defining the following for the skin element:
- <id>: This value will be used if you want to reference your skin in an EL expression. For example, if you want to have different skins for different locales, you can create an EL expression that will select the correct skin based on its ID.
- <family>: You configure an application to use a particular family of skins. Doing so allows you to group skins together for an application, based on the render kit used.
- <render-kit-id>: This value 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.
- <style-sheet-name>: This is the fully qualified path to the custom CSS file.
- <bundle-name>: The resource bundle created for the skin. If you did not create a custom bundle, then you do not need to declare this element.
  
  Note:
  If you have created localized versions of the resource bundle, you only need to register the base resource bundle.
Example 14-6 shows the entry in the adf-faces-skins.xml file for the SRDemo skin.
Example 14-6 Skins Entry for the SRDemo Skin in the adf-faces-skins.xml File
```
<skin>
  <id>
    srdemo.desktop
  </id>
  <family>
    srdemo
  </family>
  <render-kit-id>
    oracle.adf.desktop
  </render-kit-id>
  <style-sheet-name>
    skins/srdemo/srdemo.css
  </style-sheet-name>
</skin>
```

14.3.1.2 Configuring an Application to Use a 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 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 when the user's browser is set to the German locale, and use the English skin otherwise, you would have the following entry in the adf-faces-config.xml file:
```
<skin-family>#{facesContext.viewRoot.locale.language=='de' ? 'german' : 'english'}</skin-family>
```