1 About Skinning a Web Application

This chapter introduces you to developing an ADF skin. It provides an overview of the process of developing an ADF skin, takes a look at some of the changes that an ADF skin can implement, and describes the inheritance relationship of the ADF skins that Oracle ADF provides for you to extend from.

This chapter includes the following sections:

For definitions of unfamiliar terms found in this and other books, see the Glossary.

1.1 Introduction to Skinning a Web Application

Skinning is the development of an ADF skin to apply to a web application that uses ADF Faces and ADF Data Visualization components in the user interface.

An ADF skin uses the format, properties, and selectors of cascading style sheets (CSS) to allow you to customize the appearance of these components. Instead of providing a CSS file for each component, or inserting a style sheet on each page of the application, you create one ADF skin for the web application. Every component that renders in the user interface automatically uses the styles defined by the ADF skin. This means you do not have to make design-time changes to individual pages to change their appearance when you use an ADF skin.

Using an ADF skin also makes it easy for you to maintain a consistent appearance for all the pages that the application renders. Changes to the appearance of your application can easily be made should you decide to do so. You might decide, for example, to change colors to make your application adhere to your company's corporate brand. Additionally, you may want to define a style property for a component to make your application more usable. For example, Figure 1-1 shows an ADF Faces inputText component.

Figure 1-1 Writable inputText Component

Description of Figure 1-1 follows
Description of "Figure 1-1 Writable inputText Component"

Figure 1-2 shows another ADF Faces inputText component where the background color is grayed out by the ADF skin to indicate to the end user that the inputText component is read only.

Figure 1-2 Read-Only inputText Component with Grayed-Out Background Color

This image is described in the surrounding text

Other benefits of skinning include the ability to easily change the default text labels that ADF Faces components render at runtime. For example, the default text for the dialog component's labels are OK and Cancel if you set the component's type property to okCancel. You cannot modify the values of these labels by specifying properties for the dialog component. Instead, if you want to change OK to Submit, for example, you make changes in the ADF skin that references a resource bundle with the alternative string value. See Working With Text in an ADF Skin.

The previous examples illustrate some of the use cases for ADF skins plus the benefits of creating an ADF skin. Note that you do not have to define all the changes that you want for your application in one ADF skin. You can create different ADF skins to serve different purposes. For example, you might create ADF skins with different color schemes to adhere to the corporate brand of different companies. In addition, you can configure an application so that the skin changes dynamically (for example, based on the role of the end user, or in response to a selection by the end user).

Oracle ADF provides a number of tools and resources to assist you in the task of creating an ADF skin. Overview of Developing an ADF Skin briefly describes the tools that you can use while ADF Skins Provided by Oracle ADF describes the ADF skins that Oracle ADF provides as a starting point for your ADF skin creation project. A new web application that you create in this release uses the Alta skin by default. Migrated web applications continue to use their existing ADF skin. To get the full benefit of the Oracle Alta UI system, Oracle recommends that you go beyond simply using the Alta skin and design your application around the Oracle Alta UI Design Principles. Designing your application using these principles enables you to make use of the layouts, responsive designs and components the Oracle Alta UI system incorporates to present content to your end users in a clean and uncluttered way. For information about the Oracle Alta UI system and the Oracle Alta UI Design Principles, see http://www.oracle.com/webfolder/ux/middleware/alta/index.html and for information about Oracle Alta UI Patterns, see http://www.oracle.com/webfolder/ux/middleware/alta/patterns/index.html.

Note that this guide makes the following assumptions:

  • You are familiar with the ADF Faces and ADF Data Visualization components that you can skin. The usage and functionality of these components is beyond the scope of this guide. For information about these components, see Using Common ADF Faces Components and Using ADF Data Visualization Components in Developing Web User Interfaces with Oracle ADF Faces.

  • You are familiar with CSS. It is beyond the scope of this guide to explain CSS. For extensive information about CSS, including the official specification, visit the World Wide Web Consortium (W3C) web site at:

    http://www.w3.org/

1.2 Overview of Developing an ADF Skin

Developing an ADF skin is an iterative process that you accomplish using the tools that Oracle ADF provides.

Before you proceed, familiarize yourself with the concepts of CSS plus the ADF Faces and ADF Data Visualization components.

Oracle ADF provides two tools to help you to develop an ADF skin: the Theme Editor and JDeveloper’s editor for ADF skins. The Theme Editor is a web application where you can change the style properties of the most frequently-skinned ADF Faces components. You can view the results of the changes you make immediately within a preview pane of the same browser page where you make the style property changes.

The goal of the Theme Editor is to assist you accomplish the majority of your skinning tasks. For those skinning tasks that you cannot accomplish using the Theme Editor, we recommend that you export the ADF skin from the Theme Editor to an ADF Library JAR once you complete the tasks that can be completed in the Theme Editor. Using the exported ADF Library JAR, you can complete the remainder of your skinning project by creating an ADF skin that extends from the exported Theme Editor’s ADF skin using the editors for ADF skins in JDeveloper. Examples of tasks that require you to use the editors for ADF skins in JDeveloper include styling DVT components, writing alternative text strings for the default labels that ADF Faces components render, and specifying at-rules in your ADF skin to determine the look and feel if the web application page renders in a specific browser or on a device.

Note:

You cannot import an ADF skin into the Theme Editor and the Theme Editor user interface refers to an ADF skin as a “theme.”

The high level steps to develop a theme (ADF skin) in the Theme Editor are:

  1. Create an ADF skin using the Theme Editor.

  2. Modify the style properties for the ADF Faces components that the Theme Editor enables you to customize using the provided controls.

  3. Review your changes in the provided preview pages.

  4. If satisfied or if you have completed all tasks that can be accomplished using the Theme Editor, export your completed ADF skin to an ADF Library JAR, as described in Working with the Theme Editor.

  5. Choose the appropriate option:

The high level steps to develop an ADF skin in JDeveloper are:

  1. Create an ADF skin in JDeveloper.

    You create an ADF skin in JDeveloper where you write the declarations for the selectors that the ADF skinning framework exposes. When creating an ADF skin in JDeveloper, you must choose an existing ADF skin to extend from. If this ADF skin is the first ADF skin that you create, you choose from one of the ADF skins that Oracle ADF provides. See ADF Skins Provided by Oracle ADF. For information about the inheritance relationship between these ADF skins, see Inheritance Relationship of the ADF Skins Provided by Oracle ADF . If you create subsequent ADF skins, you can choose to extend from an ADF skin that you created previously.

    For information about creating an ADF skin, see Creating an ADF Skin File.

  2. Write declarations for the selectors, rules, and pseudo-elements in the ADF skin that you created.

    The editor for ADF skins in JDeveloper provides a number of tabs that facilitate this task.

    Note:

    The Design tab only appears if you extend your ADF skin from the Skyros ADF skin. The Theme Editor (described previously) enables you to edit and preview changes that you make to an Alta or Skyros skin in a browser page. The selectors editor appears irrespective of the skin family that you extend from. See Working with the ADF Skin Design Editor and Working with the ADF Skin Selectors Editor.

    For a description of the different categories of selectors, rules, and pseudo-elements, see Working with ADF Skin Selectors.

  3. If applicable, import images that you want your ADF skin to reference at runtime in the web application, as described in Working with Images and Color in Your ADF Skin.

  4. If applicable, override the default text labels defined for the ADF Faces and ADF Data Visualization components by entering new values in a resource bundle. See Working With Text in an ADF Skin.

  5. Preview and test the changes that you made to the ADF skin to verify that the results are what you want. Modify the ADF skin as necessary. The Design tab described in Step 2 provides a number of sample pages where you can view your changes within the editor for ADF skins in JDeveloper or within a browser by clicking the Preview in Browser icon, as described in Working with the ADF Skin Design Editor. For information about previewing and testing an ADF skin in a running web application, see Testing Changes in Your ADF Skin .

  6. Once you complete development of the ADF skin, you may want to package it for distribution, as described in Packaging an ADF Skin into an ADF Library JAR.

  7. Having completed the ADF skin and distributed it, you configure your web application so that it uses it, as described in Applying an ADF Skin to Your Web Application.

1.3 Taking a Look at an ADF Skin

An ADF skin is a type of cascading style sheet that is specific to Oracle ADF. You can specify properties in the ADF skin that the end user’s browser processes and properties that the Fusion web application processes on its server.

An ADF skin differs from a cascading style sheet in a number of ways. One way it differs is that you can specify properties for the selectors that the ADF skinning framework exposes in the source file for the ADF skin. A selector exposed by the ADF skinning framework is similar to a CSS selector in that it identifies the ADF Faces and ADF Data Visualization components for which you want to change the appearance and allows you to specify one or more style properties for the component.

A selector exposed by the ADF skinning framework differs from a CSS selector in that it allows you to set values both for CSS properties and ADF skin properties exposed by the ADF skinning framework. CSS properties are interpreted directly by the end user's browser. ADF skin properties are prefaced by the characters -tr-. Some of these ADF skin properties are read and interpreted by the web application. These properties are also known as server-side properties. A component that renders in the user interface may read these properties before it decides what to render. Other types of ADF skin properties, for example -tr-rule-ref or -tr-property-ref, enhance the capabilities of the ADF skinning framework, as described in Properties in the ADF Skinning Framework.

The following example shows the selector for the gauge component that sets values for the ADF skin properties -tr-graphic-antialiasing and -tr-animation-indicators, plus the CSS properties background-color and font-family.

af|dvt-gauge
{
  /** ADF skin properties */ 
  -tr-graphic-antialiasing: false;
  -tr-animation-indicators: none;
  /** CSS properties */
  font-family: Geneva, Arial, Helvetica, sans-serif;
  background-color: rgb(243,255,185);
}

As the previous example demonstrates, you can set values for CSS properties and ADF skin properties within the declaration of a selector exposed by the ADF skinning framework. The ADF skinning framework exposes the ADF skin properties that you can define. In addition to ADF skin properties, the ADF skinning framework defines a number of pseudo classes and at-rules that you can specify in an ADF skin. Examples of supported at-rules and pseudo classes include @platform, @agent, @accessibility-profile, :rtl, and @locale. See Working with ADF Skin Selectors.

At runtime, the web application creates a browser-specific CSS file from the ADF skin. The application then references this browser-specific CSS file as it would any CSS file.

Figure 1-3 demonstrates the impact that an ADF skin can have on the appearance of an application's page. The page on the left renders using the skyros ADF skin. The page on the right renders using the alta skin. Each ADF skin defines different values for colors and fonts.

Figure 1-3 File Explorer Application Using the Skyros ADF Skin and the Alta Skin

This image is described in the surrounding text

Note:

An ADF skin can affect the time it takes a client to render the user interface. The more styles that an ADF skin uses, the more the client has to load. This can affect performance in low bandwidth or high latency environments.

1.4 Inheritance Relationship of the ADF Skins Provided by Oracle ADF

Oracle ADF provides a number of ADF skin families that you can use in your application or extend when you create an ADF skin. The ADF skins provided by Oracle ADF offer increasing levels of customization for the appearance rendered by ADF Faces and ADF Data Visualization components at runtime.

Figure 1-4 shows the inheritance relationship between the different ADF skin families. The skyros-v1 and alta-v1 ADF skin families both extend from the simple ADF skin.

All ADF Faces components use, at a minimum, styles defined in the simple ADF skin as this is the skin from which the other ADF skins extend. The simple ADF skin defines the minimum style properties that ADF Faces components require to render in a web application. If you want to create an ADF skin with a minimal amount of customization, you create an ADF skin that extends from the simple ADF skin.

Figure 1-4 Inheritance Relationship of ADF Skin Families Provided by Oracle ADF

This image is described in the surrounding text

You can apply any of the ADF skins in Figure 1-4 or an ADF skin that you create yourself to an application. For information about applying an ADF skin to an application, see Applying an ADF Skin to Your Web Application.

For a more detailed description of the ADF skins that Oracle ADF provides, see ADF Skins Provided by Oracle ADF.