Developing ADF Skins · 4.3.2 Interactive Preview in the Selectors Editor 4-7 4.4 Working with the...

Oracle® Fusion MiddlewareDeveloping ADF Skins

12c (12.2.1.3.0)E80021-01August 2017

Oracle Fusion Middleware Developing ADF Skins, 12c (12.2.1.3.0)

E80021-01

Copyright © 2014, 2017, Oracle and/or its affiliates. All rights reserved.

Primary Author: Walter Egan

Contributing Authors: Laura Akel

This software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify,license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means.Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are"commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of theprograms, including any operating system, integrated software, any programs installed on the hardware,and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications.It is not developed or intended for use in any inherently dangerous applications, including applications thatmay create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure itssafe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks areused under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron,the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced MicroDevices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services unless otherwiseset forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not beresponsible for any loss, costs, or damages incurred due to your access to or use of third-party content,products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

Audience vii

Documentation Accessibility vii

Related Documents vii

Conventions vii

1 About Skinning a Web Application

1.1 Introduction to Skinning a Web Application 1-1

1.2 Overview of Developing an ADF Skin 1-2

1.3 Taking a Look at an ADF Skin 1-4

1.4 Inheritance Relationship of the ADF Skins Provided by Oracle ADF 1-6

2 Working with the Theme Editor

2.1 About the Theme Editor 2-1

2.2 Setting Up and Starting the Theme Editor 2-2

2.2.1 How to Set Up the Theme Editor 2-3

2.2.2 How to Persist ADF Skins Created in the Theme Editor 2-3

2.2.3 How to Start the Theme Editor 2-4

2.3 Exporting an ADF Skin from the Theme Editor 2-4

3 Working with ADF Skin Selectors

3.1 About ADF Skin Selectors 3-1

3.1.1 ADF Skin Selectors and Pseudo-Elements 3-3

3.1.2 ADF Skin Selectors and Icon Images 3-3

3.1.3 Grouped ADF Skin Selectors 3-5

3.1.4 Descendant ADF Skin Selectors 3-6

3.2 Pseudo-Classes in the ADF Skinning Framework 3-7

3.3 Properties in the ADF Skinning Framework 3-10

3.4 Accessing Selector Information from Within JDeveloper 3-12

iii

4 Working with ADF Skins in JDeveloper

4.1 About the Editors for ADF Skins in JDeveloper 4-1

4.2 Working with the ADF Skin Design Editor 4-1

4.2.1 How to Change the Browser that Renders the Design Editor's SamplePages 4-2

4.3 Working with the ADF Skin Selectors Editor 4-3

4.3.1 About the Selector Tree 4-5

4.3.2 Interactive Preview in the Selectors Editor 4-7

4.4 Working with the Properties Window 4-8

4.5 Navigating ADF Skins 4-10

5 Creating the Source Files for an ADF Skin

5.1 About Creating an ADF Skin 5-1

5.2 Creating an ADF Skin File 5-1

5.2.1 How to Create an ADF Skin in JDeveloper 5-2

5.2.2 What Happens When You Create an ADF Skin 5-3

5.3 Importing One or More ADF Skins Into the Current ADF Skin 5-5

5.4 Adding ADF Skins from an ADF Library JAR 5-6

5.4.1 How to Add an ADF Skin from an ADF Library JAR 5-6

5.4.2 What Happens When You Import an ADF Skin from an ADF LibraryJAR 5-6

6 Working with Component-Specific Selectors

6.1 About Working with Component-Specific Selectors 6-1

6.2 Changing ADF Faces Components' Selectors 6-3

6.3 Changing ADF Data Visualization Components' Selectors 6-4

6.4 Changing a Component-Specific Selector 6-7

6.4.1 How to Change a Component-Specific Selector 6-8

6.4.2 What Happens When You Change a Component-Specific Selector 6-8

6.5 Configuring ADF Skin Properties to Apply to Messages 6-10

6.5.1 How to Configure an ADF Skin Property to Apply to a Message 6-11

6.5.2 What Happens When You Configure ADF Skin Properties to Apply toMessages 6-12

6.6 Configuring an ADF Skin for Accessibility 6-13

6.6.1 How to Configure an ADF Skin for Accessibility 6-13

7 Working with Images and Color in Your ADF Skin

7.1 About Working with Images and Color in Your ADF Skin 7-1

7.2 Changing Images and Colors in the ADF Skin Design Editor 7-3

iv

7.3 Working with Anchor Colors in an ADF Skin 7-4

7.4 Changing an Image for a Component Selector 7-8

7.4.1 How to Copy an Image into the Project 7-9

7.4.2 What Happens When You Copy an Image into the Project 7-10

8 Working With Text in an ADF Skin

8.1 About Working with Text in an ADF Skin 8-1

8.2 Using Text From Your Own Resource Bundle 8-2

8.2.1 How to Specify an Additional Resource Bundle for an ADF Skin 8-3

8.2.2 What Happens When You Specify an Additional Resource Bundle for anADF Skin 8-3

9 Working With Global Selector Aliases

9.1 About Global Selector Aliases 9-1

9.2 Creating a Global Selector Alias 9-5

9.2.1 How to Create a Global Selector Alias 9-5

9.2.2 What Happens When You Create a Global Selector Alias 9-6

9.3 Modifying a Global Selector Alias 9-6

9.3.1 How to Modify a Global Selector Alias 9-7

9.4 Applying a Global Selector Alias 9-7

9.4.1 How to Apply a Global Selector Alias 9-8

9.4.2 What Happens When You Apply a Global Selector Alias 9-8

9.4.3 What You May Need to Know About Applying a Global Selector Alias 9-9

9.5 Referencing a Property Value from Another Selector 9-10

9.5.1 How to Reference a Property Value from Another Selector 9-11

9.5.2 What Happens When You Reference a Property Value from AnotherSelector 9-11

10

Working with Style Classes

10.1 About Style Classes 10-1

10.2 Creating a Style Class 10-2

10.2.1 How to Create a Style Class 10-2

10.2.2 What Happens When You Create a Style Class 10-3

10.3 Modifying a Style Class 10-3

10.3.1 How to Modify a Style Class 10-3

10.4 Configuring a Style Class for a Specific Instance of a Component 10-4

10.4.1 How to Configure a Style Class for a Specific Instance of a Component10-5

v

10.4.2 What Happens When You Configure a Style Class for a SpecificInstance of a Component 10-5

11

Working with At-Rules

11.1 About At-Rules in the ADF Skinning Framework 11-1

11.2 Working with Server-Side At-Rules 11-2

11.3 Working with Client-Side At-Rules 11-5

11.4 Creating At-Rules in an ADF Skin 11-7

11.4.1 How to Create an At-Rule 11-7

11.4.2 What Happens When You Create an At-Rule 11-8

11.4.3 What Happens at Runtime: How the ADF Skinning Framework AppliesAt-Rules 11-9

12

Applying the Finished ADF Skin to Your Web Application

12.1 About Applying a Finalized ADF Skin to an Application 12-1

12.2 Testing Changes in Your ADF Skin 12-1

12.2.1 How to Set Parameters for Testing Your ADF Skin 12-3

12.2.2 What Happens When You Set Parameters for Testing Your ADF Skin 12-4

12.3 Packaging an ADF Skin into an ADF Library JAR 12-4

12.3.1 How to Package an ADF Skin into an ADF Library JAR 12-5

12.3.2 What Happens When You Package an ADF Skin into an ADF LibraryJAR 12-5

12.4 Applying an ADF Skin to Your Web Application 12-6

12.4.1 How to Apply an ADF Skin to an Application 12-7

12.4.2 What Happens When You Apply an ADF Skin to an Application 12-7

12.5 Applying an ADF Skin to a Running Web Application 12-7

12.5.1 How to Configure your Web Application to Accept an Updated ADFSkin 12-7

12.5.2 How to Deploy an ADF Library JAR to an MBean Server 12-8

12.5.3 What Happens When You Apply an ADF Skin to a Running Application12-10

13

Advanced Topics

13.1 Referring to URLs in an ADF Skin's CSS File 13-1

13.2 Configuration Files for an ADF Skin 13-2

13.3 ADF Skins Provided by Oracle ADF 13-3

13.4 Versioning ADF Skins 13-4

13.4.1 How to Version an ADF Skin 13-4

13.4.2 What Happens When You Version ADF Skins 13-4

vi

Preface

Welcome to Developing ADF Skins.

AudienceThis document is intended for application developers and user interface designers whowant to change the look and feel of their application by skinning ADF Faces RichClient components.

Documentation AccessibilityFor information about Oracle's commitment to accessibility, visit the OracleAccessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic supportthrough My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsif you are hearing impaired.

Related DocumentsFor more information, see the following documents:

• Developing Web User Interfaces with Oracle ADF Faces

• Tag Reference for Oracle ADF Faces

• Tag Reference for Oracle ADF Faces Skin Selectors

• Tag Reference for Oracle ADF Faces Data Visualization Tools

• Tag Reference for Oracle ADF Data Visualization Tools Skin Selectors

ConventionsThe following text conventions are used in this document:

Convention Meaning

boldface Boldface type indicates graphical user interface elements associatedwith an action, or terms defined in text or the glossary.

vii

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs

Convention Meaning

italic Italic type indicates book titles, emphasis, or placeholder variables forwhich you supply particular values.

monospace Monospace type indicates commands within a paragraph, URLs, codein examples, text that appears on the screen, or text that you enter.

Preface

viii

1About Skinning a Web Application

This chapter introduces you to developing an ADF skin. It provides an overview of theprocess of developing an ADF skin, takes a look at some of the changes that an ADFskin can implement, and describes the inheritance relationship of the ADF skins thatOracle ADF provides for you to extend from.This chapter includes the following sections:

• Introduction to Skinning a Web Application

• Overview of Developing an ADF Skin

• Taking a Look at an ADF Skin

• Inheritance Relationship of the ADF Skins Provided by Oracle ADF

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

1.1 Introduction to Skinning a Web ApplicationSkinning is the development of an ADF skin to apply to a web application that usesADF 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 ofproviding a CSS file for each component, or inserting a style sheet on each page ofthe application, you create one ADF skin for the web application. Every componentthat renders in the user interface automatically uses the styles defined by the ADFskin. This means you do not have to make design-time changes to individual pages tochange their appearance when you use an ADF skin.

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

Figure 1-1 Writable inputText Component

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

Figure 1-2 Read-Only inputText Component with Grayed-Out BackgroundColor

Other benefits of skinning include the ability to easily change the default text labelsthat ADF Faces components render at runtime. For example, the default text for the

1-1

dialog component's labels are OK and Cancel if you set the component's typeproperty to okCancel. You cannot modify the values of these labels by specifyingproperties for the dialog component. Instead, if you want to change OK to Submit, forexample, you make changes in the ADF skin that references a resource bundle withthe alternative string value. See Working With Text in an ADF Skin.

The previous examples illustrate some of the use cases for ADF skins plus thebenefits of creating an ADF skin. Note that you do not have to define all the changesthat you want for your application in one ADF skin. You can create different ADF skinsto serve different purposes. For example, you might create ADF skins with differentcolor 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 ofcreating an ADF skin. Overview of Developing an ADF Skin briefly describes the toolsthat you can use while ADF Skins Provided by Oracle ADF describes the ADF skinsthat Oracle ADF provides as a starting point for your ADF skin creation project. A newweb application that you create in this release uses the Alta skin by default. Migratedweb applications continue to use their existing ADF skin. To get the full benefit of theOracle Alta UI system, Oracle recommends that you go beyond simply using the Altaskin and design your application around the Oracle Alta UI Design Principles.Designing your application using these principles enables you to make use of thelayouts, responsive designs and components the Oracle Alta UI system incorporatesto present content to your end users in a clean and uncluttered way. For informationabout 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 aboutOracle 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 thatyou can skin. The usage and functionality of these components is beyond thescope of this guide. For information about these components, see Using CommonADF Faces Components and Using ADF Data Visualization Components inDeveloping Web User Interfaces with Oracle ADF Faces.

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

http://www.w3.org/

1.2 Overview of Developing an ADF SkinDeveloping an ADF skin is an iterative process that you accomplish using the toolsthat Oracle ADF provides.Before you proceed, familiarize yourself with the concepts of CSS plus the ADF Facesand ADF Data Visualization components.

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

Chapter 1Overview of Developing an ADF Skin

1-2

http://www.oracle.com/webfolder/ux/middleware/alta/index.html


http://www.oracle.com/webfolder/ux/middleware/alta/patterns/index.html

http://www.oracle.com/webfolder/ux/middleware/alta/patterns/index.html

http://www.w3.org/

The goal of the Theme Editor is to assist you accomplish the majority of your skinningtasks. 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 LibraryJAR once you complete the tasks that can be completed in the Theme Editor. Usingthe exported ADF Library JAR, you can complete the remainder of your skinningproject by creating an ADF skin that extends from the exported Theme Editor’s ADFskin using the editors for ADF skins in JDeveloper. Examples of tasks that require youto use the editors for ADF skins in JDeveloper include styling DVT components, writingalternative text strings for the default labels that ADF Faces components render, andspecifying at-rules in your ADF skin to determine the look and feel if the webapplication page renders in a specific browser or on a device.

Note:

You cannot import an ADF skin into the Theme Editor and the Theme Editoruser 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 Editorenables 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 theTheme Editor, export your completed ADF skin to an ADF Library JAR, asdescribed in Working with the Theme Editor.

5. Choose the appropriate option:

• Import the ADF Library JAR into a JDeveloper project from where you canextend the ADF skin to complete any remaining tasks you were unable tocomplete using the Theme Editor, as described in Adding ADF Skins from anADF Library JAR.

• Distribute your completed ADF skin for use in the intended web applications,as described in Applying an ADF Skin to Your Web Application.

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 theselectors that the ADF skinning framework exposes. When creating an ADF skinin JDeveloper, you must choose an existing ADF skin to extend from. If this ADFskin is the first ADF skin that you create, you choose from one of the ADF skinsthat Oracle ADF provides. See ADF Skins Provided by Oracle ADF. Forinformation about the inheritance relationship between these ADF skins, see Inheritance Relationship of the ADF Skins Provided by Oracle ADF . If you createsubsequent ADF skins, you can choose to extend from an ADF skin that youcreated 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 skinthat you created.

Chapter 1Overview of Developing an ADF Skin

1-3

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

Note:

The Design tab only appears if you extend your ADF skin from the SkyrosADF skin. The Theme Editor (described previously) enables you to edit andpreview 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 extendfrom. See Working with the ADF Skin Design Editor and Working with the ADFSkin 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 inthe web application, as described in Working with Images and Color in Your ADFSkin.

4. If applicable, override the default text labels defined for the ADF Faces and ADFData 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 theresults are what you want. Modify the ADF skin as necessary. The Design tabdescribed in Step 2 provides a number of sample pages where you can view yourchanges within the editor for ADF skins in JDeveloper or within a browser byclicking the Preview in Browser icon, as described in Working with the ADF SkinDesign Editor. For information about previewing and testing an ADF skin in arunning web application, see Testing Changes in Your ADF Skin .

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

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

1.3 Taking a Look at an ADF SkinAn ADF skin is a type of cascading style sheet that is specific to Oracle ADF. You canspecify properties in the ADF skin that the end user’s browser processes andproperties 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 itdiffers is that you can specify properties for the selectors that the ADF skinningframework exposes in the source file for the ADF skin. A selector exposed by the ADFskinning framework is similar to a CSS selector in that it identifies the ADF Faces andADF Data Visualization components for which you want to change the appearanceand 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 thatit allows you to set values both for CSS properties and ADF skin properties exposedby the ADF skinning framework. CSS properties are interpreted directly by the enduser's browser. ADF skin properties are prefaced by the characters -tr-. Some ofthese ADF skin properties are read and interpreted by the web application. These

Chapter 1Taking a Look at an ADF Skin

1-4

properties are also known as server-side properties. A component that renders in theuser interface may read these properties before it decides what to render. Other typesof ADF skin properties, for example -tr-rule-ref or -tr-property-ref, enhance thecapabilities of the ADF skinning framework, as described in Properties in the ADFSkinning Framework.

The following example shows the selector for the gauge component that sets values forthe ADF skin properties -tr-graphic-antialiasing and -tr-animation-indicators, plusthe 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 andADF skin properties within the declaration of a selector exposed by the ADF skinningframework. The ADF skinning framework exposes the ADF skin properties that youcan define. In addition to ADF skin properties, the ADF skinning framework defines anumber of pseudo classes and at-rules that you can specify in an ADF skin. Examplesof 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 ofan application's page. The page on the left renders using the skyros ADF skin. Thepage on the right renders using the alta skin. Each ADF skin defines different valuesfor colors and fonts.

Chapter 1Taking a Look at an ADF Skin

1-5

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

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. Thiscan affect performance in low bandwidth or high latency environments.

1.4 Inheritance Relationship of the ADF Skins Provided byOracle ADF

Oracle ADF provides a number of ADF skin families that you can use in yourapplication or extend when you create an ADF skin. The ADF skins provided by OracleADF offer increasing levels of customization for the appearance rendered by ADFFaces 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 skinas this is the skin from which the other ADF skins extend. The simple ADF skin definesthe minimum style properties that ADF Faces components require to render in a webapplication. 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.

Chapter 1Inheritance Relationship of the ADF Skins Provided by Oracle ADF

1-6

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

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

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

Chapter 1Inheritance Relationship of the ADF Skins Provided by Oracle ADF

1-7

Chapter 1

Inheritance Relationship of the ADF Skins Provided by Oracle ADF

1-8

2Working with the Theme Editor

This chapter provides information to help you to configure the environment required touse the Theme Editor to create and modify ADF skins.This chapter includes the following sections:

• About the Theme Editor

• Setting Up and Starting the Theme Editor

• Exporting a Theme from the Theme Editor

2.1 About the Theme EditorThe Theme Editor helps you to define the look and feel of your web application byselecting the colors, fonts, and other style properties that you want ADF Facescomponents to render at runtime. The end result of this process is the creation of anADF skin.

Note:

The Theme Editor's user interface refers to an ADF skin as a "theme".

Once you complete the creation of the theme, you can export it from the Theme Editoras an ADF skin to an ADF Library JAR file. Use this file to apply the ADF skin that youcreated in the Theme Editor to your web application, as described in Applying theFinished ADF Skin to Your Web Application.

If you want to customize the ADF skin further and the Theme Editor does not providethe UI controls to achieve the result you want, import the ADF Library JAR into aproject in JDeveloper where you can use the design-time that JDeveloper provides orJDeveloper's source editor for the CSS source file of an ADF skin to create an ADFskin that extends from the ADF skin you created in the Theme Editor. See Adding ADFSkins from an ADF Library JAR.

2-1

Figure 2-1 Theme Editor's Quick Start Page

2.2 Setting Up and Starting the Theme EditorCreate a new application using JDeveloper’s Application from EAR File option. Deploythis new application to start an instance of the Theme Editor.Oracle ADF delivers the Theme Editor as a web application in the following EAR file inyour JDeveloper installation:

\jdeveloper_install_dir\jdeveloper\skineditor\skin-editor-webapp.ear

To use the Theme Editor, you create a new application in JDeveloper using theApplication from EAR File option in JDeveloper's New Gallery and deploy the ThemeEditor to the Integrated WebLogic Server. See How to Set Up the Theme Editor.

Once you create the new application with the Theme Editor in JDeveloper, youprobably want to edit the application's web.xml file so that any ADF skins you create inthe Theme Editor persist beyond a stop and restart of the Integrated WebLogic Server,as described in How to Persist ADF Skins Created in the Theme Editor.

After you configure the Theme Editor to persist ADF skins, you can start it, asdescribed in How to Start the Theme Editor.

As the Theme Editor is packaged in an EAR file, you can deploy it to IntegratedWebLogic Server that is installed with JDeveloper. You can also deploy it usingEnterprise Manager, Oracle WebLogic Scripting Tool (WLST), or Oracle WebLogicServer Administration Console. For information about deployment options, see Deploying Fusion Web Applications in Developing Fusion Web Applications withOracle Application Development Framework.

Chapter 2Setting Up and Starting the Theme Editor

2-2

2.2.1 How to Set Up the Theme EditorYou set up the Theme Editor by creating a new application in JDeveloper where youimport the Theme Editor from the skin-editor-webapp.ear file in the skineditordirectory of your JDeveloper installation.

How to set up the Theme Editor:

1. In the main menu, choose File and then Application > New.

2. In the New Gallery, in the Items list, double-click Application from EAR file.

3. In the Application from EAR File wizard, enter the location of the EAR file or clickBrowse to navigate to the skin-editor-webapp.ear file in the skineditor directory ofyour JDeveloper install directory.

For additional help with the wizard, click Help.

4. Click Finish.

2.2.2 How to Persist ADF Skins Created in the Theme EditorThe ready-to-use Theme Editor that Oracle ADF provides in the skin-editor-webapp.ear file in the skineditor directory of your JDeveloper install directory does notpersist any ADF skins that you create if you stop and restart the Integrated WebLogicServer where you deploy the Theme Editor. You specify a file directory location in theweb.xml file of the Theme Editor web application. The Theme Editor then saves ADFskins you create (and their resources) to this location so that they will be availableafter an Integrated WebLogic Server restart. You can view these resources in the filedirectory you specify, but you must export the ADF skin, as described in Exporting anADF Skin from the Theme Editor, if you want to extend the ADF skin in JDeveloper ordistribute the ADF skin for use in a web application.

To persist ADF skins created in the Theme Editor:

1. In the Applications window, double-click the web.xml file in the skin-editorproject.

2. In the source editor, add the following context initialization parameter entries:

<context-param> <description>Set this context parameter to file so that themes get saved to a temporary directory. Specify a directory location for oracle.adf.view.rich.SKIN_REPOSITORY_FILE_PATH to persist changes between server restarts.</description> <param-name>oracle.adf.view.rich.SKIN_REPOSITORY</param-name> <param-value>file</param-value></context-param>

<context-param> <description>Set this context parameter to a directory location where themes are saved. Use to persist changes between server restarts</description> <param-name>oracle.adf.view.rich.SKIN_REPOSITORY_FILE_PATH</param-name> <param-value>/home/user/themes</param-value></context-param>

3. Save and close the web.xml file.

Chapter 2Setting Up and Starting the Theme Editor

2-3

2.2.3 How to Start the Theme EditorStart the Theme Editor by running the index.html page in the skin-editor project.

To start the Theme Editor:

• In the Applications window, expand skin-editor, right-click index.html and chooseRun.

The Create Default Domain dialog appears the first time you run an applicationand start a new domain in Integrated WebLogic Server. Use the dialog to definean administrator password for the new domain. Passwords you enter can be eightcharacters or more and must have a numeric character.

The index.html page within the skin-editor project is the run target. When you runthe page, JDeveloper starts a browser and displays the launch page of the ThemeEditor. Once the Theme Editor launch page appears, you can create new ADFskins or edit existing ADF skins.

Note:

The Theme Editor's user interface refers to an ADF skin as a "theme".

2.3 Exporting an ADF Skin from the Theme EditorExport an ADF Skin from the Theme Editor so that you can distribute it for use in webapplications or customize the ADF skin further using the tools provided by JDeveloper.Once you complete the creation of an ADF skin in the Theme Editor, you may want toexport it to an ADF Library JAR so that you can distribute it for use in a webapplication. Alternatively, you may want to edit it further using the design-time toolsthat JDeveloper provides for this purpose. This latter scenario may arise if you cannotachieve the look and feel you want using the controls provided by the Theme Editor. Ifyou want to edit an ADF skin using JDeveloper's design-time tools, you import theADF skin into JDeveloper, as described in Adding ADF Skins from an ADF LibraryJAR, and create a new ADF skin that extends from the ADF skin you exported fromthe Theme Editor.

You select the theme (ADF skin) in the Theme Editor's launch page and chooseExport from the menu that appears when you click the Actions button, as shown in Figure 2-2. The Theme Editor exports the ADF skin to an ADF Library JAR. This ADFLibrary JAR contains all required resources for the ADF skin, such as a .CSS file withentries that reflect the changes you made in the Theme Editor, images that youimported to the ADF skin, and a trinidad-skins.xml file that contains metadatadescribing the ADF skin.

Chapter 2Exporting an ADF Skin from the Theme Editor

2-4

Figure 2-2 Exporting a Theme from the Theme Editor

Chapter 2Exporting an ADF Skin from the Theme Editor

2-5

Chapter 2

Exporting an ADF Skin from the Theme Editor

2-6

3Working with ADF Skin Selectors

ADF skin selectors, along with pseudo-elements, pseudo-classes, ADF skin propertiesand ADF skinning framework rules, allow you to customize the appearance of ADFFaces and ADF Data Visualization components.This chapter includes the following sections:

• About ADF Skin Selectors

• Pseudo-Classes in the ADF Skinning Framework

• Properties in the ADF Skinning Framework

• Accessing Selector Information from Within JDeveloper

3.1 About ADF Skin SelectorsADF skin selectors specify the style properties to render at runtime when a specifiedADF Faces component renders on a page in the Fusion web application.CSS uses selectors to determine the elements in a HTML page you that you definerules for. For example, in CSS the following selector defines a rule that determines theappearance of the content that renders in a <p> tag:

p { color: red }

Likewise, the ADF skinning framework defines selectors that allow you to specifyrules with the style properties to render at runtime when the rule encounters thespecified tag. The ADF skinning framework provides two types of selector: globalselectors and component-specific selectors. A global selector defines style propertiesthat you apply to one or more selectors. A component-specific selector defines styleproperties that apply to one component.

The ADF skins provided by Oracle ADF define many global selectors (GlobalSelector Aliases in the user interface of the selectors editor) that many ADF Facescomponents inherit. For example, many ADF Faces components usethe .AFDefaultFontFamily:alias global selector to specify the font family. If you createan ADF skin that overrides this selector by specifying a different font family, thatchange affects all the components that have included the .AFDefaultFontFamily:aliasselector in their selector definition.

Figure 3-1 shows two instances of the same page. The instance of the page in thelower part of Figure 3-1 renders using the default values specified forthe .AFDefaultFontFamily:alias global selector in the skyros skin. The instance of thepage in the upper part of Figure 3-1 renders using an ADF skin that modifiesthe .AFDefaultFontFamily:alias and .AFDefaultFont global selectors as follows:

.AFDefaultFontFamily:alias {font-family: Georgia;}

.AFDefaultFont:alias {font-size: 12pt;}

The components on the page that render text (for example, af:showDetailItem rendersWelcome and an af:link component renders Login) do so using the font family

3-1

specified by the .AFDefaultFontFamily:alias global selector in the ADF skin that theapplication uses.

Figure 3-1 Global Selector

An ADF skin that you create inherits the global selector aliases defined in the ADF skinthat it extends from. You can also create new global selector aliases in your ADF skinfiles. See Working With Global Selector Aliases.

Component-specific selectors are selectors that the ADF skinning framework exposesthat allow you to identify the corresponding ADF Faces and ADF Data Visualizationcomponents for which you can define style properties. For example, Figure 3-2shows the selector for the ADF Faces button component in the source editor andselectors editor. The value of the property that determines the color of the font toappear in the button has been changed to Red in the Properties window.

Figure 3-2 Button Component's Skin Selector

Chapter 3About ADF Skin Selectors

3-2

For information about the component-specific selectors, see Working with Component-Specific Selectors . For information about global selector aliases, see Working WithGlobal Selector Aliases.

3.1.1 ADF Skin Selectors and Pseudo-ElementsMany ADF skin selectors expose pseudo-elements. A pseudo-element denotes aspecific area of a component for which you can define style properties. Pseudo-elements are denoted by a double colon followed by the portion of the component theselector represents. For example, Figure 3-3 shows how the week-header-row pseudo-element exposed by the af|chooseDate selector allows you to configure style propertiesfor the appearance of the calendar grid. In Figure 3-3, the background-color property ofthe week-header-row pseudo-element has been set to Gray.

Figure 3-3 Pseudo-Elements for the Choose Date Component

3.1.2 ADF Skin Selectors and Icon ImagesADF Faces components that render icons do so using a set of base icon images. NoCSS code entries appear in the source file of the ADF skin for these icon images incontrast to, for example, the CSS code entries that appear in a source file when youspecify an image as a value for the CSS background-image property. Instead, the ADFskinning framework registers the icon image for use with the renderer.

ADF skin selectors use two naming conventions for pseudo-elements that identify iconimages that render in a component. The names of these pseudo-elements end in -iconor in -icon-style. Figure 3-4 shows the example of the Panel Accordion selector'spseudo-elements. Pseudo-elements that end in -icon-style specify a backgroundimage, as shown in Figure 3-4. In contrast, pseudo-elements that end in -icon do not


3-3

specify a background image, but can reference IMG elements or text, as in thefollowing examples:

af|panelAccordion::undisclosed-icon {content "X"} af|panelAccordion::undisclosed-icon {content: url("http:server:port/img/img.png")}

Figure 3-4 Panel Accordion Pseudo-Elements for Icon Images

In Figure 3-4, the undisclosed-icon-style pseudo-element styles the icon used for theundisclosed icon in the panelAccordion component. This pseudo-element specifies theicon as a background image. Use the :hover and :active pseudo-classes to customizethe appearance. For example, write the following syntax to make the background red ifthe end user hovers the mouse over the icon:

af|panelAccordion::undisclosed-icon-style:hover { background-color: Red; }

Tip:

Many browsers do not render background images when in accessibility mode.The following example demonstrates how you can work around this behavior ifyou want your application to display an image when in accessibility mode.

If you want to use your own image rather than the icon specified as a backgroundimage, you need to first prevent the background image from rendering. Do this byspecifying the -tr-inhibit ADF skin property for the component's selector pseudo-element as follows:

af|panelAccordion::undisclosed-icon-style{ -tr-inhibit: background-image; }

Next you specify the text or image that you want to render as a value for the contentproperty of the undisclosed-icon selector. For example, write syntax similar to thefollowing to specify an alternative image:

af|panelAccordion::undisclosed-icon{ content:url("images/undisclosed.png"); width: 10px; height: 10px; }


3-4

The ADF skinning framework also defines a number of global selector aliases thatspecific icon images to use in different scenarios. These global selector aliases appearunder the Icons node in the Selector Tree of the selectors editor, as shown in Figure 3-5. The .AFChangedIcon:alias shown in Figure 3-5 enables you to globally setthe changed icon for all components using that icon.

Figure 3-5 Global Selector Aliases for Icons

These icons can also be viewed and changed using the Replace Icons dialog that youinvoke from the design editor, as described in Changing Images and Colors in the ADFSkin Design Editor, if your ADF skin extends from the Skyros ADF skin. Figure 3-6shows the dialog that appears for an ADF skin that extends from the Skyros ADF skin.Using the dialog, you can export or import multiple icons or replace an individual iconsby double-clicking in the New Icon Source field.

Figure 3-6 Design Editor's Replace Icons Dialog for Status Icons

For information, see Working with Images and Color in Your ADF Skin.

3.1.3 Grouped ADF Skin SelectorsYou can group ADF skin selectors and global selector aliases to minimize the numberof entries in the source file of the ADF skin. The selectors that you group render underthe Grouped Selectors node in the Selector Tree of the selectors editor, as shown in


3-5

Figure 3-7. The View as list in the Preview Pane displays all the selectors that yougrouped.

As the selectors editor does not provide a way to specify grouped selectors, you usethe source editor to specify the selectors and/or global selector aliases that you wantto put in a grouped selector. Separate each selector by a comma (,) to include in thegrouped selector.

Figure 3-7 Grouped Selectors in the Selector Tree

3.1.4 Descendant ADF Skin SelectorsA descendant selector defines style properties for one ADF skin selector (thedescendant selector) to render when the selector's component is a descendant ofanother component in the page that renders the components. For example, assumethat you want the content area of an inputText component to render using abackground color of Green when the component renders inside a table component. Inthis scenario, you specify the descendant selector shown in the following example.

af|table af|inputText::content { background-color: Green;} af|inputText::content { background-color: Red;}

At runtime, when the inputText component renders in a table component, thebackground color of the content area is Green. The appearance of other inputTextcomponents that render outside of table components is determined by the styleproperties defined elsewhere in the ADF skin (for example, Red).


3-6

A descendant selector is made up of two or more selectors separated by white space.When you configure a descendant selector, the selectors editor displays a DescendantSelectors node under the selector included in the descendant selector, as shown in Figure 3-8.

Figure 3-8 Descendant Selectors in the Selector Tree

As the selectors editor does not provide a way to specify descendant selectors, youuse the source editor to specify the selectors and/or global selector aliases that youwant to specify in a descendant selector. Separate each selector by a white space.

3.2 Pseudo-Classes in the ADF Skinning FrameworkThe ADF skinning framework uses pseudo-classes to define style properties for whena selector is in a particular state.The CSS specification defines pseudo-classes, such as :hover and :active, which areused to define style properties for when a selector is in a particular state. You canapply these pseudo-classes to almost every ADF Faces component. In addition, theADF skinning framework provides additional pseudo-classes for specialized functions.Examples include pseudo-classes to apply when a browser's locale is a right-leftlanguage (:rtl) or for drag and drop operations (:drag-target and :drag-source). Thesyntax that appears in the source file of an ADF skin to denote a pseudo-class usesthe following format(s):

adfskinselector:pseudo-class

adfskinselector::pseudo-element:pseudo-class

Figure 3-9 shows the syntax that you write (af|panelList::link:hover {color:Orange;}) in the source file of an ADF skin for the :hover pseudo-class so that apanelList component's link renders orange when the end user hovers a cursor overthe link in Figure 3-9.

Chapter 3Pseudo-Classes in the ADF Skinning Framework

3-7

Figure 3-9 Pseudo-Class Syntax and Runtime Behavior for a Panel List Link

Some components make more use of pseudo-classes than other components. ThepanelBox component's selector, for example, makes extensive use of pseudo-classesto define its appearance when it is in various states (for example, active, disabled, orbusy). Figure 3-10 shows the list of available pseudo-classes that renders when youselect the panelBox component's selector in the Selector Tree of the selectors editorand click the Add Pseudo-Class icon to display the list of available pseudo-classes inan ADF skin that extends from the Skyros ADF skin.

Figure 3-10 Pseudo-classes for the panelBox Component's Selector


3-8

Pseudo-classes can also be applied to pseudo-elements that selectors expose. ThepanelBox component selector's pseudo elements are a good example. Figure 3-11, ofthe Selector Tree in the selectors editor, shows the list of pseudo-classes that thecenter pseudo-element exposed by the panelBox component selector accepts. Many ofthese pseudo-classes allow you to define the appearance for the panelBox componentdepending on the value that the application developer sets for its attributes. Forexample, the core and highlight pseudo-classes define the corresponding appearancewhen the application developer sets the panelBox component's ramp attribute to core orhighlight.

Figure 3-11 Pseudo-classes for the center Pseudo-element

The following are common pseudo-classes used by ADF Faces selectors.

• Drag and drop: The two pseudo-classes available are :drag-source applied to thecomponent initiating the drag and removed once the drag is over, and :drop-target applied to a component willing to accept the drop of the current drag.

• Standard: In CSS, pseudo-classes like :hover, :active, and :focus are consideredstates of the component. This same concept is used in applying skins tocomponents. Components can have states like read-only or disabled. When statesare combined in the same selector, the selector applies only when all states aresatisfied.

• Right-to-left: Use this pseudo-class to set a style or icon definition when thebrowser is in a right-to-left language. Another typical use case is asymmetricalimages. You will want the image to be flipped when setting skin selectors that usethe image in a right-to-left reading direction. Be sure to append the :rtl pseudo-class to the very end of the selector and point it to a flipped image file. The skineditor's preview pane does not render changes that you make to a flipped imagefile. The following example from the Skyros skin shows the image that the calendarcomponent's toolbar-day-hover-icon pseudo-element references when it rendersin a browser that uses a right-to-left language:

af|calendar::toolbar-day-hover-icon:rtl { content: url(/afr/cal_day_ovr_rtl.png); width: 16px;


3-9

height: 16px;}

You can also use :rtl to apply to skin icons. See Working with Images and Colorin Your ADF Skin.

• Inline editing: This pseudo-class is applied when the application activates acomponent subtree for editing in the browser. For example, :inline-selected is apseudo-class applied to currently selected components in the active inline-editablesubtree.

• Message: This pseudo-class is used to set component-level message styles usingCSS pseudo-classes of :fatal, :error, :warning, :confirmation, and :info. See Configuring ADF Skin Properties to Apply to Messages .

Note:

The global selector aliases that appear in the Selector Tree are a special typeof pseudo-class (:alias). See Working With Global Selector Aliases.

3.3 Properties in the ADF Skinning FrameworkADF skin properties can reference or suppress styles from other selectors, referencethe value of a property, or customize the rendering of a component throughout theapplication.The ADF skinning framework defines a number of ADF skin properties. The webapplication, rather than the user's browser, interprets ADF skin properties. Whenconfigured, ADF skin properties enable you to do the following:

• Reference styles from other selectors with the -tr-rule-ref property.

Create your own global selector alias and combine it with other selectors using the-tr-rule-ref property. See Creating a Global Selector Alias, Modifying a GlobalSelector Alias, and Applying a Global Selector Alias .

• Suppress styles defined in an ADF skin with the -tr-inhibit skin property.

Suppress or reset CSS properties inherited from a base skin with the -tr-inhibitskin property. For example, the -tr-inhibit:padding property removes anyinherited padding. Remove (clear) all inherited properties with the -tr-inhibit:allproperty. The suppressed property name must be matched exactly with theproperty name in the base skin.

• Reference the value of a property defined in another selector using the -tr-property-ref property.

See Referencing a Property Value from Another Selector.

• Configure a theme for child components with the -tr-children-theme property.

The Alta skin (and skins that extend from the Alta skin) do not use themes.

• ADF skin selectors with style properties.

Skin style properties allow you to customize the rendering of a componentthroughout the application. A CSS property is stored with a value in the Skin objectand is available when the component is being rendered. For example, in af|

Chapter 3Properties in the ADF Skinning Framework

3-10

breadCrumbs{-tr-show-last-item: false}, the skin property -tr-show-last-item isset to hide the last item in the breadCrumbs component's navigation path.

As already noted, ADF skin properties allow you to customize the rendering of thecomponent throughout the application. This means that you cannot use ADF skinproperties to customize specific instances of a component in your application by, forexample, configuring an ADF skin property in a style class that an instance of acomponent then references using its styleClass attribute.

The ADF skinning framework also provides the + and - operators that allow you to seta selector's color or font properties relative to the value that you specify for the color orfont properties of another selector. This is useful if you want to apply a range of colorsto selectors or maintain a relative size between fonts.

Example 3-1 demonstrates the syntax that you write to make use of this feature for acolor property. A global selector alias defines the background color that another globalselector alias (.fooBackgroundColorTest) applies using the - operator. Example 3-1 alsodemonstrates the syntax that you write to make use of this feature for a font property.A global selector alias (.FontSizeTest:alias) defines the font sizeand .fooFontTestIncrease increases this font size by using the + operator.

Figure 3-12 shows how the style classes defined in Example 3-1 effect the runtimeappearance of instances of the af:outputLabel components to which you apply thefooFontTestIncrease and fooBackgroundColorTest style classes by specifying these styleclasses as values for the component's styleClass attribute, as illustrated in thefollowing example.

<af:outputLabel value="Increase font-size" id="ol2" styleClass="fooFontTestIncrease"/>

Figure 3-12 Using Operators to Apply Color and Change Font Size

For information about style classes, see Working with Style Classes.

Example 3-1 Using Operators to Apply Color and Change Font Size

.FontSizeTest:alias { font-size: 30px;}

.BaseBackgroundColor:alias { background-color: #0099ff;}

.fooFontTestIncrease { -tr-rule-ref: selector(".FontSizeTest:alias"); font-size: +20px;}

.fooBackgroundColorTest { -tr-rule-ref: selector(".BaseBackgroundColor:alias"); background-color: -#333333;

Chapter 3Properties in the ADF Skinning Framework

3-11

}

af|outputLabel { -tr-rule-ref: selector(".BaseBackgroundColor:alias"); -tr-rule-ref: selector(".FontSizeTest:alias"); color: Red; }

3.4 Accessing Selector Information from Within JDeveloperYou can access reference information for ADF skin selectors and CSS properties fromwithin the editor for ADF skins in JDeveloper.The reference information that you can access includes the following referencedocuments for ADF skin selectors:

• Tag Reference for Oracle ADF Faces Skin Selectors

• Tag Reference for Oracle ADF Data Visualization Tools Skin Selectors

You can access these reference documents in the documentation library or in a HelpCenter window if you click the link in the information text that appears when you hoverover a selector in the Selector Tree of the selectors editor, as shown in Figure 3-13.

Figure 3-13 Reference Documentation for ADF Skin Selectors

In addition to referencing information for the ADF skin selectors, you can accessinformation for CSS selectors. You do this from the Source tab of the editor byselecting the CSS property and pressing Control + D or choosing Show QuickReference from the context menu that appears when you right-click the selector, asillustrated in Figure 3-14.

Chapter 3Accessing Selector Information from Within JDeveloper

3-12

Figure 3-14 Quick Reference Documentation for CSS Properties

Chapter 3Accessing Selector Information from Within JDeveloper

3-13

Chapter 3

Accessing Selector Information from Within JDeveloper

3-14

4Working with ADF Skins in JDeveloper

Editors in JDeveloper create ADF skins. Key features of these editors, such as theSelector Tree where you browse selectors, the Properties window where you setproperties, and how you navigate to an ADF skin that you extend, are described.This chapter includes the following sections:

• About the Editors for ADF Skins in JDeveloper

• Working with the ADF Skin Design Editor

• Working with the ADF Skin Selectors Editor

• Working with the Properties Window

• Navigating ADF Skins

4.1 About the Editors for ADF Skins in JDeveloperThe editor for ADF skins in JDeveloper is a tool that creates ADF skins for applicationsbuilt using Oracle ADF.It provides a number of visual and source editors where you edit the selectors exposedby the ADF skinning framework, preview your changes, and package the final ADFskin into an ADF Library JAR.

Key features of the editors for ADF skins in JDeveloper include the:

• ADF Skin Design Editor (design editor) where you can declaratively modify anADF skin that extends from the Skyros ADF skin using the provided controls.

• ADF Skin Selector Editor (selectors editor) where you can view all of the selectorsexposed by the ADF skinning framework in the Selector Tree.

• Properties window where you can modify the properties of the selectors that youchoose in the Selector Tree.

4.2 Working with the ADF Skin Design EditorThe design editor provides a variety of controls to change the most commonly styledparts of application pages. It also provides sample pages where you can previewchanges.By default, the design editor opens when you create an ADF skin that extends fromthe Skyros ADF skin, as described in Creating an ADF Skin File. This editor provides avariety of controls to change the most commonly styled parts of applications.

The lower part of the design editor displays a number of sample pages that render awide variety of the commonly used ADF Faces components, such as buttons, links,and panel accordions. These sample pages refresh to reflect the changes that youmake using the various controls in the upper part of the editor. A Preview in Browsericon renders the sample page in a browser when clicked. In Figure 4-1, for example,clicking this icon renders the sample page in Internet Explorer. You can choose to

4-1

render the sample page in another browser, as described in How to Change theBrowser that Renders the Design Editor's Sample Pages.

The upper part of the design editor displays a variety of tabs that group togethercontrols to modify the selectors for various areas of an application page, such as thebranding area, the global area, buttons, links, and menus. Within each tab, userinterface controls such as color pickers, input text components and links to invokedialogs appear. Figure 4-1 shows the General tab in the design editor that appearswhen you extend an ADF skin from the Skyros ADF skin. This tab renders colorpickers that you can invoke when you click the dropdown arrows beside the fields thatdisplay the current color values, dropdown lists where you can select different fontsand font size and links to invoke dialogs where you can replace the images that theADF skin references for status icons, animations and components.

Figure 4-1 ADF Skin Design Editor that Appears for a Skyros-Extended ADF Skin

Any changes that you make using the controls in the design editor result in thegeneration of CSS syntax that appears in the source file of the ADF skin. The designeditor is useful for changing the commonly styled parts of an application. For example,one click in the Branding Area tab invokes a dialog where you can select a new imageto render as the logo in the branding area of your application's page. Consider usingthe selectors editor, described in Working with the ADF Skin Selectors Editor, whenyou need to go beyond changing the most commonly styled parts.

For information about how you can use the design editor to change colors and images,see Changing Images and Colors in the ADF Skin Design Editor.

4.2.1 How to Change the Browser that Renders the Design Editor'sSample Pages

You can change the browser that renders the design editor's sample pages when youclick the Preview in Browser icon.

To change the browser that renders the design editor's sample pages:

Chapter 4Working with the ADF Skin Design Editor

4-2

1. From the main menu, choose Tools > Preferences.

2. In the Preferences dialog, select the Web Browser and Proxy page.

3. Choose the browser that you want to use in the Web Browsers list.

4. Click OK.

4.3 Working with the ADF Skin Selectors EditorThe selectors editor provides controls to edit selectors in your ADF skin. It alsoprovides controls to inspect and preview ADF skin.Figure 4-2 shows the selectors editor. Each label number corresponds to a descriptionin the list that follows Figure 4-2. The selectors editor opens by default if the ADF skinthat you create extends from the Alta skin family. If your ADF skin extends from theSkyros skin family, you can access the selectors editor by clicking the Selectors tab.

Figure 4-2 ADF Skin Selectors Editor

1. The Projects node in the Applications window displays the source files for the ADFskins that you create. It also displays associated configuration and image files. Bydefault, JDeveloper saves an ADF skin to a directory named skins. You canspecify an alternative directory name to store the source files. For informationabout creating ADF skins, see Creating the Source Files for an ADF Skin.

2. The Structure window lists the selectors, global selector aliases, style classes, andat-rules that you added to the ADF skin file.

Chapter 4Working with the ADF Skin Selectors Editor

4-3

3. Click the Hide/Show Divider icon to hide or show the Selector Tree.

4. Filter the selectors that appear in the Selector Tree.

You can enter text in the input text field to filter the list of selectors that appear inthe Selector Tree or you can use the filter icon to display:

• Available Selectors: all selectors in the Selector Tree.

• Updated Selectors: only those selectors that you modified in the ADF skin.

• Selectors with At-Rules: only those selectors that have an associated at-rule.

5. The Extended Skins list displays the list of ADF skins from which the current ADFskin extends. It also identifies imported ADF skins. See Navigating ADF Skins.

6. Use the Add icon to create a new style class, alias selector, or at-rule.

For information about creating a new style class, see Working with Style Classes.For information about creating an alias selector, see Working With Global SelectorAliases. For information about creating an at-rule, see Working with At-Rules.

7. Use the Delete icon to remove a selector that you added to the ADF skin.

8. Click the Refresh icon to update the Preview Pane after you make changes to theproperties of a selector in the Properties window.

9. Click the Add Pseudo-Class icon to apply a pseudo-class to the item that youselected in the Selector Tree. See Pseudo-Classes in the ADF SkinningFramework.

10. Click the Clear Property Settings icon to undo any change that you made to theitem selected in the Selector Tree.

11. Click the Delete Pseudo-Class from Skin File icon to delete any pseudo-classesthat you specified in the ADF Skin.

12. The View as list allows you to preview how changes you make to a global selectoralias in the Selector Tree affect the components that reference the global selectoralias. The View as list displays all components that reference the global selectoralias. The View as list also allows you to preview how changes you make to theproperties of one component-specific selector impact all sub-types of thatcomponent. For example, Figure 4-3 shows the ADF Data Visualizationcomponent selector for the graph component (af|dvt-graph) that exposes a singleset of component-specific selectors that apply changes to all graph types. Use theView as list to preview a change that you make to a selector in one of the othertypes of graph (for example, Bar, Funnel, Pareto, and so on).


4-4

Figure 4-3 View as List for a Component

For information about global selector aliases, see Working With Global SelectorAliases.

13. The Selector Tree displays the list of selectors, global selector aliases, styleclasses, and at-rules that you can configure values for in an ADF skin. See Working with the ADF Skin Selectors Editor.

14. The Preview Pane renders a preview of the changes that you make to a selector inan ADF skin after you click the Refresh icon (8).

15. You can also view the source of an ADF skin file.

Tip:

Select Split Document from a context menu that you can invoke from thePreview Pane to render the source and design views of an ADF skin side byside.

16. The Properties window identifies properties that you can configure for the ADFskin. See Working with the Properties Window.

17. The tabs for themes allow you to preview changes that you make for supportedthemes.

The Alta skin (and skins that extend from the Alta skin) do not use themes.

4.3.1 About the Selector TreeThe Selector Tree displays a list of the style classes, global selector aliases, andselectors for which you can configure properties to change the appearance of ADFFaces and ADF Data Visualization components.

Figure 4-4 shows the nodes that the Selector Tree in the selectors editor exposes:

• Style Classes


4-5

A style class defines one or more style properties that you can apply to specificinstances of a component. The selectors editor categorizes the inherited styleclasses into style classes defined for general usage, note windows, and popups.See Working with Style Classes.

• Global Selector Aliases

A global selector alias defines style properties that you apply to one or moreselectors. The selectors editor categorizes the inherited global selector aliases intoselector aliases defined for general usage, icons, and messages. See WorkingWith Global Selector Aliases.

• Grouped Selectors

Identifies style properties grouped into one declaration to apply to more than oneselector. For example, Figure 4-4 shows a grouped selector for the button andlink component's selectors.

• At-Rules

At-rules are a way to define style properties for when an application's pagerenders in a particular environment such as, for example, when using a specificbrowser. See Working with At-Rules.

• Faces Component Selector

Selectors identify the ADF Faces components for which you can configureproperties. The selectors editor displays subcategories for pseudo-elements,component selector aliases, and descendant selectors. For brevity, the ADF Facescomponents node is not expanded. See Working with Component-SpecificSelectors .

• Data Visualizations Component Selectors

Selectors identify the ADF Data Visualization components for which you canconfigure properties. The selectors editor displays subcategories for pseudo-elements, component selector aliases, and descendant selectors. See Workingwith Component-Specific Selectors .


4-6

Figure 4-4 Selector Tree

4.3.2 Interactive Preview in the Selectors EditorThe preview pane in the selectors editor displays an interactive preview of thecomponent that is currently selected in the Selector Tree. Hover your mouse over thispreview to view text that identifies the specific pseudo-element that you need tocustomize to change the appearance of the component. Clicking on parts of thispreview navigates you to the location where you can configure properties to changethe appearance of what you have just clicked on. You can also right-click a pseudo-element to invoke a context menu that displays a hierarchical list of the selectorpseudo-elements that the current pseudo-element contains, as shown in Figure 4-5.


4-7

Figure 4-5 Interactive Preview for the Calendar Component

Clicking an entry in the context menu that appears or clicking a part of the calendarcomponent that uses properties defined in the pseudo-element of another componentselector navigates you to that pseudo-element in the Selector Tree. For example, ifyou click af|button::link in the context menu in Figure 4-5, the component previewnavigates you to the location for the button component selector's pseudo-element inthe Selector Tree of the selectors editor, as shown in Figure 4-6.

Figure 4-6 Button Component's link Pseudo-Element

4.4 Working with the Properties WindowUse the Properties window to set values for CSS properties and ADF skin properties inthe selectors that the ADF skinning framework exposes.Apart from setting values for the above properties, you can also use the window to:

• Copy an image into the project where you develop the ADF skin.

See Working with Images and Color in Your ADF Skin.

Chapter 4Working with the Properties Window

4-8

• Identify the properties that inherit their values from an extended ADF (blue icon)skin and identify the properties that you configured (green icon) in the ADF skin,as shown in Figure 4-7.

• Identify the properties that are associated with at-rules, as shown in Figure 4-7.

For information about at-rules, see Working with At-Rules.

• Present ADF skin properties that you can configure for a selector.

See Properties in the ADF Skinning Framework.

• Navigate to the selector in an extended ADF skin that defines an inherited propertyin your ADF skin (Go to Declaration).

See Navigating ADF Skins.

• Invoke a dialog where you can define the colors for properties that support colorvalue.

Figure 4-7 presents an overview of the various controls that the Properties windowexposes when you edit an ADF skin.

Figure 4-7 Controls in the Properties Window for ADF Skins

Hover your mouse over the icons that indicate a property associated with an at-rule ora property that inherits its value in order to display an information tip, as shown in Figure 4-8. Clicking the link in this information tip navigates you to the source file of theADF skin where the at-rule or inherited property value is defined.

Chapter 4Working with the Properties Window

4-9

Figure 4-8 Information Tip Showing Link to Navigate to Source Declaration

4.5 Navigating ADF SkinsThe ADF skin that you create extends from pre-existing ADF skins and inheritsproperties defined in these skins. Navigate to the extended ADF skins to inspect theinherited properties.When you create an ADF skin, as described in Creating an ADF Skin File, you choosean ADF skin from which to extend. The ADF skin that you choose to extend fromdefines properties that your newly created ADF skin inherits. When you create yourfirst ADF skin, you must choose one of the ADF skins that Oracle ADF provides.

Subsequent ADF skins that you create can extend an ADF skin that you created orone of the ADF skins provided by Oracle ADF. For example, you create your first ADFskin named skinA that extends the simple ADF skin provided by Oracle ADF. You thencreate a second ADF skin named skinB. When creating skinB, you have the choice ofextending from skinA or from any of the ADF skins provided by Oracle ADF. If youchoose to extend skinB from skinA, the inheritance relationship between the ADF skinsis illustrated in Figure 4-9.

For information about the ADF skins that Oracle ADF provides, see InheritanceRelationship of the ADF Skins Provided by Oracle ADF , and ADF Skins Provided byOracle ADF.

Figure 4-9 Example Inheritance Relationship Between ADF Skins

The Extended Skins list in the selectors editor displays the list of ADF skins that thecurrent ADF skin extends. The list also identifies if any of the ADF skins that your skinextends include imported skins. Figure 4-10 shows the list of ADF skins that appears ifyou implement the inheritance relationship described in Figure 4-9. You open anextended ADF skin that you want to view by clicking it in the Extended Skins list.

Figure 4-10 Extended Skins List

Chapter 4Navigating ADF Skins

4-10

Note:

You cannot edit the properties of the selectors in the ADF skins provided byOracle ADF. You can only edit the properties of selectors in extended ADFskins that you created.

Using the Go to Declaration menu that the Properties window exposes, you cannavigate to the location in an extended ADF skin where the extended ADF skindeclares style properties inherited by other ADF skins. For example, assume that theskinA ADF skin defines a background color of Red for the af|button selector's access-key pseudo-element, as shown in Navigating ADF Skins.

Figure 4-11 Declaration of a Property Value

The skinB ADF skin that extends from skinA ADF skin inherits the property values thatare defined in the skinA ADF skin. Navigating ADF Skins shows the skinB ADF skin inthe selectors editor with a value of Red for the background-color property.

Figure 4-12 Inheriting a Property Value from an Extended Skin

To go to the declaration of a property:

1. Identify a property in your ADF skin that inherits its values from an extended ADFskin. A blue upward-pointing arrow, as shown in Figure 4-12, identifies theseproperties.


4-11

2. Click the icon that appears when you hover over the property field to invoke acontext menu where you select Go to Declaration, as shown in Figure 4-13.

Figure 4-13 Go to Declaration Context Menu

The extended ADF skin opens in the source view, as shown in Figure 4-14. If theextended ADF skin is one that you created, you can modify the property valuesdefined in it. The ADF skins provided by Oracle ADF, described inADF Skins Providedby Oracle ADF, are read-only.

Figure 4-14 Property Value Defined in Extended ADF Skin


4-12

5Creating the Source Files for an ADF Skin

Create ADF skins in JDeveloper or import an ADF skin from an ADF Library JAR file.This chapter includes the following sections:

• About Creating an ADF Skin

• Creating an ADF Skin File

• Importing One or More ADF Skins Into the Current ADF Skin

• Adding ADF Skins from an ADF Library JAR

5.1 About Creating an ADF SkinAn ADF skin defines the properties for the selectors that ADF Faces and ADF DataVisualization components expose.Using the editor in JDeveloper, you can create a source file for an ADF skin. As asource file for an ADF skin is a type of CSS file, you could create it without using aneditor. However, when you use the editor, associated configuration files get created(the first time that you create an ADF skin) or modified (when you create subsequentADF skins). For information about these configuration files, see Configuration Files foran ADF Skin.

5.2 Creating an ADF Skin FileCreate an ADF skin file in JDeveloper that defines how ADF Faces and ADF DataVisualization components render at runtime.The ADF skin that you create must extend either one of the ADF skins that OracleADF provides or from an existing ADF skin that you created. The ADF skins thatOracle ADF provides vary in the level of customization that they define for ADF Facesand ADF Data Visualization components. For information about the inheritancerelationship between the ADF skins that Oracle ADF provides, see InheritanceRelationship of the ADF Skins Provided by Oracle ADF . For information about thelevels of customization in the ADF skins provided by Oracle ADF and for arecommendation about the ADF skin to extend, see ADF Skins Provided by OracleADF.

By default, the editors in JDeveloper create ADF skins for theorg.apache.myfaces.trinidad.desktop render kit. A render kit defines how ADF Facescomponents map to component tags that are appropriate for a particular client.

After you create an ADF skin, you can use the design editor and the other providededitors to modify the values for the selectors that the ADF Faces and ADF DataVisualization components expose. Otherwise, the ADF skin that you create defines thesame appearance as the ADF skin from which it extends. See Working withComponent-Specific Selectors .

If you create an ADF skin that extends from the Skyros ADF skin, you enable thedesign editor. This tab provides an overview pane where you can use controls to set

5-1

properties for many frequently-used selectors. For information about using the designeditor, see Working with the ADF Skin Design Editor.

5.2.1 How to Create an ADF Skin in JDeveloperYou can create an ADF skin in JDeveloper.

To create an ADF skin in JDeveloper:

1. In the Applications window, right-click the project that contains the code for the userinterface and choose New.

2. In the New Gallery, expand Web Tier, select JSF/Facelets and then ADF Skin,and click OK.

3. In the Skin File page of the Create ADF Skin dialog, enter the following:

• File Name: Enter a file name for the new ADF skin.

• Directory: Enter the path to the directory where you store the CSS source filefor the ADF skin or accept the default directory proposed by the editor.

• Family: Enter a value for the family name of your skin.

You can enter a new name or specify an existing family name. If you specify anexisting value, you may need to version ADF skins, as described in VersioningADF Skins, to distinguish between ADF skins that have the same value forfamily.

The value you enter is set as the value for the <family> element in thetrinidad-skins.xml where you register the ADF skin that you create. At runtime,the <skin-family> element in an application's trinidad-config.xml file uses thisvalue to identify the ADF skin that an application uses. See Applying an ADFSkin to Your Web Application.

• Use as the default skin family for this project: Deselect this checkbox if youdo not want to make the ADF skin the default for your project immediately. Ifyou select the checkbox, the trinidad-config.xml file is updated, as describedin What Happens When You Create an ADF Skin.

4. In the Base Skin page of the Create ADF Skin dialog, specify the following:

• Show Latest Versions Only: Clear this checkbox to show all availableversions of ADF skins.

• Available Skins: Select the ADF skin that you want to extend. ADF Facesprovides a number of ADF skins that you can extend. The list also includes anyADF skins that you created previously in this project. For a recommendation onthe ADF skin to extend, see ADF Skins Provided by Oracle ADF.

• Skin Id: A read-only field that displays a concatenation of the value you enterin File Name and the ID of the render kit (desktop) for which you create yourADF skin. You select this value from the Extends list if you want to createanother ADF skin that extends from this one.

JDeveloper writes the value to the <id> element in the trinidad-skins.xml file.

5. Click Finish.

Chapter 5Creating an ADF Skin File

5-2

5.2.2 What Happens When You Create an ADF SkinIf you accepted the default value proposed for the Directory field, a file with theextension .css is generated in a subdirectory of the skins directory in your project.

An ADF skin that extends the Alta skin opens in the selectors editor, as illustrated in Figure 5-1. This selectors editor is also available if you create an ADF skin thatextends from the Skyros ADF skin.

Figure 5-1 Newly-Created ADF Skin that Extends from Alta in the SelectorsEditor

An ADF skin that extends the Skyros ADF skin opens in the design editor, asillustrated in Figure 5-2.


5-3

Figure 5-2 Newly-Created ADF Skin that Extends from Skryos in the DesignTab

The trinidad-skins.xml file is modified to include metadata for the ADF skin that youcreate, as illustrated in Example 5-1, which shows entries for an ADF skin that extendsfrom the Skyros family of ADF skins. Example 5-1 also contains values that specify therender kit and the resource bundle associated with this ADF skin. For informationabout resource bundles, see Working With Text in an ADF Skin.

If you select the Use as the default skin family for this project check box in theCreate ADF Skin dialog, the trinidad-config.xml file is modified to make the new ADFskin the default skin for your application. This means that if you run the applicationfrom JDeveloper, the application uses the newly-created ADF skin. See Applying anADF Skin to Your Web Application. The following example shows a trinidad-config.xml file that makes the ADF skin in Example 5-1 the default for an application.

<?xml version="1.0" encoding="windows-1252"?><trinidad-config xmlns="http://myfaces.apache.org/trinidad/config"> <skin-family>skin2</skin-family></trinidad-config>

The source file for the ADF skin contains a comment and namespace references, asillustrated in the following example. These entries in the source file for the ADF skindistinguish the file from non-ADF skin files with the .css file extension. A source file foran ADF skin requires these entries in order to open in the design or selectors editorsfor the ADF skin.


5-4

/**ADFFaces_Skin_File / DO NOT REMOVE**/@namespace af "http://xmlns.oracle.com/adf/faces/rich";@namespace dvt "http://xmlns.oracle.com/dss/adf/faces";

The first time that you create an ADF skin in your project, a resource bundle file(skinBundle.properties) is generated, as illustrated in Figure 5-1. For information aboutusing resource bundles, see Working With Text in an ADF Skin.

Example 5-1 trinidad-skins.xml File

<?xml version="1.0" encoding="windows-1252"?><skins xmlns="http://myfaces.apache.org/trinidad/skin"> .... <skin> <id>skin2.desktop</id> <family>skin2</family> <extends>skyros-v1.desktop</extends> <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id> <style-sheet-name>skins/skin2/skin2.css</style-sheet-name> <bundle-name>resources.skinBundle</bundle-name> </skin></skins>

5.3 Importing One or More ADF Skins Into the Current ADFSkin

Import another ADF skin that is in your JDeveloper project into your ADF skin usingthe @import rule.This makes the style properties defined in the latter ADF skin available to your ADFskin. The following examples demonstrate the valid syntax to import an ADF skin(skinA) into the current ADF skin:

/** Use the following syntax if skinA.css is in the same directory **/@import "skinA.css";@import url("skinA.css");

/** Use the following syntax if skinA.css is in another directory **/@import "../skinA/skinA.css";@import url("../skinA/skinA.css");

The @import rule(s) must follow all @charset rules and precede all other at-rules andrule sets in an ADF skin, as shown in the following example that imports two ADFskins into the current ADF skin:

@charset "UTF-8";

@import url("../skinA/skinA.css");@import url("../skinB/skinB.css");

/**ADFFaces_Skin_File / DO NOT REMOVE**/@namespace af "http://xmlns.oracle.com/adf/faces/rich";@namespace dvt "http://xmlns.oracle.com/dss/adf/faces";

af|inputText{ background-color: Green;}...

Chapter 5Importing One or More ADF Skins Into the Current ADF Skin

5-5

5.4 Adding ADF Skins from an ADF Library JARAdd ADF skins that have been packaged in a JAR file into your JDeveloper project.When you add an ADF skin into your project, it is available to extend from when youcreate a new ADF skin.The recommended type of JAR file to use to package an ADF skin is an ADF LibraryJAR file. For information about how to package an ADF skin into this type of JAR file,see Packaging an ADF Skin into an ADF Library JAR.

5.4.1 How to Add an ADF Skin from an ADF Library JARYou can add ADF skins into your project that have been packaged in a JAR file.

To add an ADF skin from an ADF Library JAR:

1. From the main menu, choose Application > Project Properties.

2. In the Project Properties dialog, select the Libraries and Classpath page and clickAdd JAR/Directory.

3. In the Add Archive or Directory dialog, navigate to the JAR file that contains theADF skin you want to add and click Select.

The JAR file appears in the Classpath Entries list.

4. When finished, click OK.

5.4.2 What Happens When You Import an ADF Skin from an ADFLibrary JAR

The ADF skin(s) that you add from the JAR file appear in the Extends list when youcreate a new ADF skin, as described in Creating an ADF Skin File. After you create anew ADF skin by extending an ADF skin that you added from a JAR file, the ExtendedSkins list in the selectors editor's Preview Pane displays the name of the ADF skin thatyou added. For example, in Figure 5-3 the skin2.css ADF skin has been created byextending the ADF skin, jarredskin.css, that was added into the project from a JARfile.

Figure 5-3 Imported ADF Skin in the Extended Skins List

Properties that have been defined in the ADF skin that you added appear with a blueupward pointing arrow in the Properties window. An information tip about theinheritance relationship displays when you hover the mouse over the property, asillustrated in Figure 5-4.

Chapter 5Adding ADF Skins from an ADF Library JAR

5-6

Figure 5-4 Property Inherited from an Imported ADF Skin

Chapter 5Adding ADF Skins from an ADF Library JAR

5-7

Chapter 5

Adding ADF Skins from an ADF Library JAR

5-8

6Working with Component-SpecificSelectors

Change the appearance of ADF Faces components by specifying properties for theselectors that the ADF skinning framework exposes. Configure properties to apply tomessages, themes to apply to ADF Faces components, and configure ADF skins foraccessibility.This chapter includes the following sections:

• About Working with Component-Specific Selectors

• Changing ADF Faces Components' Selectors

• Changing ADF Data Visualization Components' Selectors

• Changing a Component-Specific Selector

• Configuring ADF Skin Properties to Apply to Messages

• Configuring an ADF Skin for Accessibility

6.1 About Working with Component-Specific SelectorsCustomize the appearance of ADF Faces or ADF Data Visualization components bydefining style properties for the selectors that the components expose.To achieve the appearance you want, you need to become familiar with thecomponent-specific selectors that the ADF Faces and ADF Data Visualizationcomponents expose, plus the global selector aliases and descendant selectors that acomponent-specific selector may reference. The ADF skins that you extend from whenyou create an ADF skin define many global selector aliases and descendantselectors. You also need to become familiar with the component itself and how itrelates to other components. For example, customizing the appearance of the ADFFaces table component shown in Figure 6-1 requires you to define style properties forthe row-header-cell and column-filter-cell selectors exposed by the af:columncomponent in addition to selectors exposed by the ADF Faces table component. Youmay also need to modify the style properties for one or more of the icon or messageglobal selector aliases that the ADF skin you extend defines.

Note:

Consider using the design editor, as described in Working with the ADF SkinDesign Editor, if you want to change the properties of some of the mostfrequently used selectors in an ADF skin that extends from the Skyros ADFskin. This editor appears by default if your ADF skin extends from the SkyrosADF skin. The design editor provides a variety of controls to quickly changeyour ADF skin.

6-1

Figure 6-1 Selectors for an ADF Faces table Component

Use the tools that the selectors editor for ADF skins provides to customize theappearance of the ADF Faces components and ADF Data Visualization components.See Working with ADF Skins in JDeveloper.

Other sources of information that may help you as you change the selectors of ADFFaces and ADF Data Visualization components include the following:

• Images: An ADF skin can reference images that render icons and logos, forexample, in a page. For information about how to work with images in an ADFskin, see Working with Images and Color in Your ADF Skin.

• Text: An ADF skin does not include text strings that render in your page. However,you can specify a resource bundle that defines the text strings you want toappear in the page. See Working With Text in an ADF Skin.

• Global selector aliases: A global selector alias specifies style properties that youcan apply to multiple ADF Faces components simultaneously. For informationabout global selector aliases, see Working With Global Selector Aliases.

• Style Classes: A style class in an ADF skin specifies a number of style propertiesthat an ADF Faces component can reference as a value if it exposes a style-related attribute (styleClass and inlineStyle). For information about style classes,see Working with Style Classes.

Chapter 6About Working with Component-Specific Selectors

6-2

• ADF Faces Rich Client Components Hosted Demo: The Oracle TechnologyNetwork (OTN) web site provides a link to an application that demonstrates howADF skins change the appearance of ADF Faces and ADF Data Visualizationcomponents. Navigate to http://www.oracle.com/technetwork/developer-tools/adf/overview/index.html

6.2 Changing ADF Faces Components' SelectorsChange the runtime appearance of ADF Faces components by editing the propertiesthat each ADF Faces skin selector exposes.ADF Faces components render user interface controls, such as buttons, links andcheck boxes in your web application. ADF Faces components also includecomponents that render calendars, panels to arrange other user interface controls andtables in your web application. For information about ADF Faces components and thefunctionality that they provide, see ADF Faces Components in Developing Web UserInterfaces with Oracle ADF Faces.

The number of selectors that an ADF Faces component exposes varies bycomponent. For example, the ADF Faces components, af:image and af:popup, exposeone selector each. In contrast, the ADF Faces component, af:panelHeader, exposes avariety of selectors that enable you to change the appearance of different parts of theuser interface of that component. There are, for example, selectors that allow you tochange the af:panelHeader component's instruction text, help icons, and titles.

The process to follow to change the runtime appearance of an ADF Faces componentis the same for each component; the only difference is the number of selectors thateach ADF Faces component exposes. Figure 6-2 and Figure 6-3 take the buttoncomponent as an example and illustrate how you can customize the appearance ofthis component using pseudo-elements and the component's selector. Figure 6-2shows the application of the skyros skin on the button component and the componenticon.

Figure 6-2 Button Component Default Appearance with Skyros ADF Skin

Figure 6-3 shows the appearance of the component in the selectors editor after youset values for the following pseudo-elements on the component's selector:

• access-key: The Color property is set to red

• dropdown-icon-style: The Border property is set to 2px solid black

Chapter 6Changing ADF Faces Components' Selectors

6-3

http://www.oracle.com/technetwork/developer-tools/adf/overview/index.html

http://www.oracle.com/technetwork/developer-tools/adf/overview/index.html

Figure 6-3 Button Component with Modified Selectors

Reference information about the selectors that ADF Faces components expose can befound in the Tag Reference for Oracle ADF Faces Skin Selectors.

6.3 Changing ADF Data Visualization Components'Selectors

Change the runtime appearance of ADF Data Visualization components by editing theproperties that each ADF Data Visualization component selector exposes.The ADF Data Visualization components are a set of components that providefunctionality to represent data in graphical and tabular formats. Examples of the ADFData Visualization components include the following: graph, gantt, pivot table, andhierarchy viewer. For information about ADF Data Visualization components and thefunctionality that they provide, see Introduction to ADF Data Visualization Componentsin Developing Web User Interfaces with Oracle ADF Faces.

The number of selectors exposed by an ADF Data Visualization component varies bycomponent.

Figure 6-4 , for example, shows an ADF skin in the selectors editor with the nodesexpanded to show the selectors that you can customize for the ADF Data Visualizationgauge component.

Chapter 6Changing ADF Data Visualization Components' Selectors

6-4

Figure 6-4 ADF Data Visualization Component Selectors

You customize the appearance of ADF Data Visualization components by definingstyle properties for the selectors that each ADF Data Visualization componentexposes. Using the tools provided by JDeveloper's selectors editor for ADF skins, youcustomize the appearance of the ADF Data Visualization components. See Workingwith ADF Skins in JDeveloper.

To achieve the appearance you want, you need to become familiar with the selectorsthat the ADF Data Visualization component exposes, the global selector aliases thatthe component may reference and which are defined in the ADF skin that you extendwhen you create an ADF skin. You also need to become familiar with the componentitself and how it relates to other components. For example, customizing theappearance of the ADF Data Visualization pivotTable component shown in Figure 6-5requires you to define style properties for this selector's pseudo-elements. You mayalso need to modify the style properties for one or more of the global selector aliasesthat the ADF skin you extend defines.

Figure 6-5 ADF Data Visualization pivotTable Component

Many ADF Data Visualization component selectors, such as the selectors for the graphand hierarchyViewer components, expose pseudo-elements for which you configureADF skin properties. These ADF skin properties modify the appearance of the areaspecified by the pseudo-element. The characters -tr- preface the names of ADF skinproperties. For example, Figure 6-6 shows the properties of the hierarchy viewer'slateral-navigation-button selector, all of which are prefaced by -tr-.


6-5

Figure 6-6 Properties for the hierarchyViewer Component lateral-navigation-button Pseudo-Element

In contrast, the gantt component's summary-task-left selector, shown in Figure 6-7,exposes only four ADF skin properties (-tr-rule-ref, -tr-inhibit-, -tr-enable-themes,and -tr-children-theme) as the majority of the properties that you configure for thisselector are CSS properties.

For information about ADF skin properties, see Properties in the ADF SkinningFramework.

Figure 6-7 Properties for the gantt Component summary-task-left Pseudo-Element

Reference information about the selectors, pseudo-elements, and pseudo-classes thatADF Data Visualization components expose can be found in the Tag Reference forOracle ADF Data Visualization Tools Skin Selectors.


6-6

6.4 Changing a Component-Specific SelectorExpand the appropriate node in the Selector Tree of the selectors editor, choose theselector, and set values using the Properties window.The process to change a component-specific selector is the same for both the ADFFaces and ADF Data Visualization components. In the Selector Tree of the selectorseditor, you expand the Faces Components Selectors or Data Visualization Selectorsnode to select the selector of the component you want to modify. You then set valuesfor this selector using the Properties window. You can also set properties for anypseudo-elements, component style classes, component selector aliases, ordescendant selectors that the selector you select references. In addition, you can addpseudo-classes that the component-specific supports. For information about pseudo-classes, see Pseudo-Classes in the ADF Skinning Framework. Figure 6-8 shows aview of the skin selector for the ADF Faces table component in the Selector Tree ofthe selectors editor with the different pseudo-elements that you can configure for thisskin selector.

Figure 6-8 Selector for the table Component

Figure 6-9 shows a runtime view of an ADF Faces table component that renders datausing the style properties provided by the ADF Faces simple skin.

Chapter 6Changing a Component-Specific Selector

6-7

Figure 6-9 ADF Faces table Component Rendered By the simple Skin

6.4.1 How to Change a Component-Specific SelectorYou change a component-specific selector by selecting the selector in the SelectorTree and setting values for the selector, its pseudo-elements, or descendant selectorsin the Properties window. In addition, you can add a pseudo-class if the component-specific selector supports one.

To change a component-specific selector:

1. In the Selector Tree of the selectors editor, choose the appropriate option:

• Expand the Faces Component Selectors node if you want change a selectorfor an ADF Faces component.

• Expand the Data Visualization Selectors node if you want to change aselector for an ADF Data Visualization component.

For example, expand the Faces Component Selectors node, the Column node, thePseudo-Elements node, and select the column-header-cell selector.

2. In the Properties window, specify values for the properties that the selector youselected in Step 1 supports.

For example, in the Common section of the Properties window, specify values forthe following attributes:

• Background Color: Specify the background color that you want to appear inthe header row of the table.

• Color: Specify the color that you want to apply to text that appears in theheader row of the table's column.

3. In the Preview Pane, click the Add Pseudo-Class icon to choose a supportedpseudo-class from the displayed list of supported pseudo-classes that appears.

6.4.2 What Happens When You Change a Component-SpecificSelector

The selectors editor displays the changes that you make to the selector after you clickthe Refresh icon in the Preview Pane. If you add a pseudo-class to the selector, thePreview Pane also displays an entry for the selector with the added pseudo-class. Forexample, Figure 6-10 shows an entry for a selector with the :hover pseudo-classadded.


6-8

Note:

The Preview Pane for the af|document selector only displays one entry even ifyou add a pseudo-class to this selector.

Figure 6-10 Preview Pane with a Component Specific Selector and a Pseudo-Class

The selectors editor also writes the values that you specify for the selectors in theProperties window to the source file for the ADF skin. The following example showsthe changes that appear in the source file after making some of the changes describedin How to Change a Component-Specific Selector.

af|column::column-header-cell{ color: Black; background-color: Olive; font-weight: bold;}

When a web application uses an ADF skin that contains the values shown in theprevious example, header rows in the columns of a table rendered by the ADF Facestable component appear as illustrated by Figure 6-11 where the table uses a skin thatextends the simple skin.


6-9

Figure 6-11 ADF Faces table with a Header Row Skinned

6.5 Configuring ADF Skin Properties to Apply to MessagesApply styles to ADF Faces input components based on whether or not the componentshave certain types of message associated with them.When a message of a particular type is added to a component, the styles of thatcomponent are automatically modified to reflect the new status. If you do not definestyles for the type of message in question, the component uses the default stylesdefined in the ADF skin.

The types of message property are:

• :fatal

• :error

• :warning

• :confirmation

• :info

Figure 6-12 shows an inputText component rendered using the simple ADF skin. In Figure 6-12, the simple ADF skin defines style values for the :warning messageproperty to apply to the inputText component when an end user enters values thatgenerate a warning.

Figure 6-12 inputText Component Displaying Style for :warning MessageProperty

Figure 6-13 shows the same inputText component as in Figure 6-12. In Figure 6-13,the end user entered a value that generated an error. As a result, the inputTextcomponent renders using the style properties configured for the :error messageproperty.

Figure 6-13 inputText Component Displaying Style for :error Message Property

The ADF skinning framework defines a number of global selector aliases that definestyle properties to apply to messages. Figure 6-14 shows a list of global selector

Chapter 6Configuring ADF Skin Properties to Apply to Messages

6-10

aliases under the Message node in the Selector Tree of the selectors editor. ThePreview Pane, on the right of Figure 6-14, shows how the style properties defined forthe global selector alias (.AFFormComponentOutlineFatal:alias) currently selected in theSelector Tree render the component selected from the View as list.

Figure 6-14 Global Selector Aliases for Messages

You can customize the global selector aliases that the ADF skinning frameworkprovides for messages by defining style properties in your ADF skin. The styleproperties that you define for the global selector alias affect all ADF Facescomponents that reference the global selector alias. For example, if you change theborder color for the global selector alias shown in Figure 6-14 to green, all the ADFFaces components shown in the View as list render with a border that is green. Forinformation about global selector aliases, see Working With Global Selector Aliases.

The af|message and af|messages selectors also expose pseudo-elements that enableyou to change the icons that appear in the message dialogs at runtime. In addition,these selectors define resource strings that determine the text to appear in tool tipswhen an end user hovers over a message dialog. You can override these resourcestrings by specifying alternative values in a resource bundle, as described in WorkingWith Text in an ADF Skin. For information about configuring messages for ADF Facescomponents, see Displaying Tips, Messages, and Help in Developing Web UserInterfaces with Oracle ADF Faces.

6.5.1 How to Configure an ADF Skin Property to Apply to a MessageYou add a pseudo-class to the component's selector for the message type that youwant to configure. You then define style properties for the pseudo-class using theProperties window.

To configure an ADF skin property to apply to a message:

1. In the Selector Tree of the selectors editor, expand the Faces ComponentSelectors section and select the selector for the ADF Faces component for whichyou want to configure the style properties to apply to a message.

For example, select the af|inputText selector to configure the style properties toapply to the ADF Faces inputText component.

2. Click the Add Pseudo- Class icon to display a list of the available pseudo-classesfor the selector that you selected in Step 1.


6-11

3. Select the pseudo-class that corresponds to the message for which you want toconfigure style properties. The following pseudo-classes are available for the ADFFaces components:

• fatal

• error

• warning

• confirmation

• info

4. Configure the style properties that you want to apply to the component at runtimewhen the application displays a message with the component.

6.5.2 What Happens When You Configure ADF Skin Properties toApply to Messages

The selectors editor writes the values that you specify for the selector's pseudo-classin the Properties window to the source file for the ADF skin. For example, assume thatyou set the value of the Border property to orange for the content pseudo-element ofthe af|inputText selector's error pseudo-class. Figure 6-15 shows the syntax entriesthat appear in the source file of the ADF skin and the change in the Preview Pane ofthe selectors editor.

Figure 6-15 Style Properties for an inputText Component's Error Message


6-12

6.6 Configuring an ADF Skin for AccessibilityOracle ADF provides application accessibility support to make applications developedusing ADF Faces components usable for persons with disabilities.You can define style properties in your ADF skin specifically for persons withdisabilities as part of efforts to make your application accessible. You preface thesestyle properties with the @accessibility-profile rule.

The @accessibility-profile rule allows you to define style properties for the high-contrast and large-fonts accessibility profile settings that you can specify in thetrinidad-config.xml file. For information about the trinidad-config.xml file, see Configuration Files for an ADF Skin.

Define style properties for the high-contrast accessibility profile where you wantbackground and foreground colors to contrast highly with each other. Define styleproperties for the large-fonts accessibility profile for cases where the user must beallowed to increase or decrease the text scaling setting in the web browser. Defininglarge-fonts does not mean that the fonts are large, but rather that they are scalablefonts or dimensions instead of fixed pixel sizes.

Example 6-1 shows style properties that get applied to the af|column::sort-ascending-icon pseudo-element when an application renders using the high-contrast accessibilityprofile.

For information about developing accessible ADF Faces pages and accessibilityprofiles, see Developing Accessible ADF Faces Pages in Developing Web UserInterfaces with Oracle ADF Faces.

Example 6-1 Style Properties Defined Using the @accessibility-profile

@accessibility-profile high-contrast { af|calendar::calendar-icon-reminder-style, af|calendar::calendar-icon-recurring-style, af|calendar::calendar-icon-recurring-change-style { -tr-inhibit: all; }}

6.6.1 How to Configure an ADF Skin for AccessibilityYou define style properties for the selector or selectoŕs pseudo-elements that you wantto configure and preface these style properties with the @accessibility-profile rule.

To configure an ADF skin for accessibility:

1. Define style properties for the selectors and selectors' pseudo-elements that youwant to configure, as described in Changing a Component-Specific Selector.

2. In the source file for the ADF skin, preface the skinning keys that you configuredwith the @accessibility-profile rule, as illustrated in Example 6-1.

Chapter 6Configuring an ADF Skin for Accessibility

6-13

Chapter 6

Configuring an ADF Skin for Accessibility

6-14

7Working with Images and Color in YourADF Skin

Use images and color in your ADF skin to change the appearance of a Fusion webapplication. Images can be changed using the editors provided by JDeveloper and youcan change the color palette of an ADF skin that extends from Skyros by working withcolor categories.This chapter includes the following sections:

• About Working with Images and Color in Your ADF Skin

• Changing Images and Colors in the ADF Skin Design Editor

• Working with Anchor Colors in an ADF Skin

• Changing an Image for a Component Selector

7.1 About Working with Images and Color in Your ADF SkinThe ADF skins provided by Oracle ADF define color schemes and reference images toprovide a colorful look and feel for applications. Changing these colors and the imagesthat your ADF skin references will make a significant difference to the appearance ofthe application that uses your ADF skin.The simple skin differs from the other skins provided by Oracle ADF in that it containsonly minimal formatting.

Figure 7-1 illustrates this point by showing the same page from an application thatrenders using two different ADF skins (skyros and simple). The skyros skin defines thelook and feel of the application page in the upper part of Figure 7-1. It uses more colorand images than the application page in the lower part that uses the simple skin.

7-1

Figure 7-1 ADF Skin Using Images and Color

Among the selectors in the ADF skins provided by Oracle ADF that reference imagesare those in the following list. A short description of the role that the referenced imagesperforms in skinning the web application also appears.

• af|document::splash-screen-icon

This component-specific selector specifies the icon that appears within a splashscreen when a web applications loads in a browser.

• af|column::sorted-descending-icon-style

This component-specific selector specifies the icon that renders for the sorteddescending indicator in a column.

• .AFFatalIcon:alias

This global selector alias specifies the icon to appear if a fatal error occurs on apage

One example of color that the ADF skins provided by Oracle ADF define isthe .AFHoverPrimaryColor:alias global selector alias. This global selector alias definesthe background color when, for example, a user hovers a cursor over a buttoncomponent. Another example is the .AFBackgroundColor:alias global selector alias thatdefines the background color used for the main content area of your page.

The editor for ADF skins in JDeveloper provides features to help change the colorsand images that your ADF skin uses. The availability of some or all of these featuresdepends on the ADF skin that you extend, as described in the following list:

• If your ADF skin extends the Skyros skin

JDeveloper enables the design editor where you can use various color pickers andother controls to change some of the more frequently used colors and images inan ADF skin. See Changing Images and Colors in the ADF Skin Design Editor.

• If your ADF Skin extends from the Alta skin

Use the selectors editor to change images, as described in Changing an Image fora Component Selector.

Chapter 7About Working with Images and Color in Your ADF Skin

7-2

Note:

Alternatively, use the Theme Editor described in Working with the ThemeEditor, to change the colors and images in an ADF skin that extends from theAlta or Skyros skins.

7.2 Changing Images and Colors in the ADF Skin DesignEditor

Use the design editor to change images and colors referenced and defined in yourADF skin.The design editor appears when you create an ADF skin that extends from the SkyrosADF skin. You access it by clicking the Design tab of the open ADF skin. For anoverview of the design editor, see Working with the ADF Skin Design Editor.

Examples of tasks that you can carry out using this editor include the following:

• Change the default text color in ADF skins that extend from Skyros

• Change the background color that appears to highlight when you hover overcomponents such as the button component

• Replace icons

You can change all or individual icons for components, status, and animation iconsusing the Replace Icons dialog that you invoke when you click one of the StatusIcon, Animations, or Component buttons in the Images area of the General tab.Click Help for information on the Replace Icons dialog.

Figure 7-2 shows an ADF skin that extends from the Skyros ADF skin where thefollowing changes have been made:

• In the General tab

Note:

Red rectangles in Figure 7-2 identify the controls used to make the changes inthe General tab. Red arrows point to a corresponding result in the samplepage.

– Change the main default text color to Fuchsia

This changes the color value of the AFTextColor global selector alias which isan anchor color. This change also affects the global selector aliases (forexample, AFTextPrimaryColor and AFTextSecondaryColor) that set colorproperties which derive their hue value from the AFTextColor global selectoralias. For information about this relationship, see Working with Anchor Colorsin an ADF Skin.

– Change the primary accent color to Black

This changes the color that renders when a cursor hovers over a componentsuch as a button component. The global selector aliases that sets this color

Chapter 7Changing Images and Colors in the ADF Skin Design Editor

7-3

property are AFHoverPrimaryColor and AFButtonGradientStartHoverColor. Otherglobal selector aliases use the AFButtonGradientStartHoverColor global selectoralias to derive the hue value of the color properties that they set. Examples ofglobal selector aliases that derive their color property from theAFButtonGradientStartHoverColor global selector alias includeAFButtonBorderBottomHoverColor and AFButtonBorderHoverColor. For informationabout this relationship, see Working with Anchor Colors in an ADF Skin.

– Change one of the animated icons that indicate connection status

In this example, the animation icon referenced by the af|statusIndicator::idle-icon was changed.

• In the Branding Area tab

– Change the color property that determines the background color for thebranding area (AFBrandingBackgroundColor global selector alias) to transparent.

– Change the image file that is used to render the logo in the branding area.

Figure 7-2 Changing Colors and Icons in ADF Skin Design Editor

7.3 Working with Anchor Colors in an ADF SkinADF skins group colors into categories. The anchor category defines the base colorsfor your ADF skin, so changing these colors quickly changes the appearance of yourweb application.An ADF skin that extends from the Alta or Skyros families of ADF skin defines globalselector aliases that group colors into one of three categories, as illustrated in Figure 7-3. Changing the value of color properties for global selector aliasescategorized as anchor colors can help you to quickly change the color palette that yourADF skin defines.

Chapter 7Working with Anchor Colors in an ADF Skin

7-4

Figure 7-3 Color Categories Skyros's Global Selector Aliases

• Anchor Color: These global selector aliases define the base colors for your ADFskin. For example, the AFButtonGradientStartColor global selector alias defines thestart gradient color for a button.

• Derivative Color: These global selector aliases derive the hue value for their colorproperties from anchor colors. The global selector aliases in Example 7-1 allderive their hue value from the AFButtonGradientStartActiveColor global selectoralias. JDeveloper propagates any change that you make to the anchor color to thederivative color. The derivative colors inherit any change that you make to ananchor color using the editor for ADF skins in JDeveloper.

• Speciality Color: These global selector aliases define color properties that do notderive their hue value from anchor colors and are not anchor colors for othercolors. For example, the AFCarouselFocusBorderColor global selector alias thatdefines the border color when the carousel component has focus.

Figure 7-4 shows the result of changing the default value of theAFButtonGradientStartActiveColor global selector alias to red. The editor for ADF skinsin JDeveloper also updates the values of the derivative colors that derive their huevalue from the anchor color.


7-5

Figure 7-4 Modified Anchor Color and Effect on Derivative Colors

If you change the color property of a derivative color and later make a change to theassociated anchor color, the editor for ADF skins in JDeveloper displays a ConfirmDerivative Color Modification dialog to warn you that the change you make to theanchor color will override the change that you made to the derivative color, asillustrated in Figure 7-5 where a warning aboutthe .AFButtonGradientEndActiveColor:alias appears. Click OK to make the change tothe anchor color and to override the already-defined value for the derivative color.


7-6

Figure 7-5 Overriding a Derivative Color

Example 7-1 shows entries from the Skyros ADF skin (skyros-v1-desktop.css) thatdefine the default values for the AFButtonGradientStartActiveColor global selector aliasand its associated derivative colors. These global selector aliases share the same huevalue (209) but specify different values for the saturation and lightness values.

Example 7-2 shows the same global selector aliases referenced in Example 7-1. In Example 7-2, an ADF skin extends from Skyros and changes the value of the colorproperty of the AFButtonGradientStartActiveColor global selector alias to #6CD5A1. Theeditor for ADF skins in JDeveloper modifies the color properties of the global selectoraliases that derive their color value from the anchor color.

Example 7-1 Global Selector Aliases with Anchor and Derivative Colors inSkyros

/* Anchor, hsl(209, 56%, 63%), #6AA1D5 */.AFButtonGradientStartActiveColor:alias {color: #6AA1D5;} /* Derivative of AFButtonGradientStartActiveColor, hsl(209, 32%, 54%),#648BAF */.AFButtonBorderTopActiveColor:alias {color: #648BAF;} /* Derivative of AFButtonGradientStartActiveColor, hsl(209, 39%, 62%),#789FC4 */.AFButtonBorderActiveColor:alias {


7-7

color: #789FC4;} /* Derivative of AFButtonGradientStartActiveColor, hsl(209, 54%, 79%),#ACCAE6 */.AFButtonGradientEndActiveColor:alias {color: #ACCAE6;}

Example 7-2 Modified Anchor and Derivative Colors

.AFButtonGradientStartActiveColor:alias { color: #6CD5A1; } .AFButtonBorderTopActiveColor:alias { color: #64AF8A; } .AFButtonGradientEndActiveColor:alias { color: #ADE6CA; } .AFButtonBorderActiveColor:alias { color: #79C39E; }

7.4 Changing an Image for a Component SelectorMany ADF Faces and ADF Data Visualization components reference images usingselectors. These images display in the background of the component or render asicons or controls on the component.When you create an ADF skin, the ADF skin that you extend from provides the valuesfor these selectors, such as the relative path to an image and the sizes for height andwidth.

Figure 7-6 shows a runtime view of the table component rendering a control that sortsthe data in a table column in ascending order. The image that renders this control isreferenced by the ADF Faces column component's sort-ascending-icon-style selector.

Figure 7-6 Image Referenced by the sort-ascending-icon-style Selector

Figure 7-7 shows a design-time view where an ADF skin inherits values for the columncomponent's sort-descending-icon-style selector from the extended ADF skin. Thevalues inherited include the file name for the image used as an icon(colSort_asc_ena.png), the height, and the width for the image.

Chapter 7Changing an Image for a Component Selector

7-8

Figure 7-7 Inherited Values for the sort-descending-icon-style Selector

Other examples of ADF Faces and ADF Data Visualization components that exposeselectors which reference images associated with the component include thefollowing:

• ADF Faces progressIndicator component exposes the determinate-empty-icon-style selector.

• ADF Faces panelAccordion component exposes the disclosed-icon-style selector.

• ADF Data Visualization mapToolbar component exposes the zoomin-enable-iconselector.

If you decide that you want to modify the image that is associated with a componentselector, you need to modify the selector in your ADF skin and copy the image into theproject for your ADF skin. You can copy images individually using the procedure in How to Copy an Image into the Project.

After you import an image into your project, the selector that references the imageuses a URL in the source file of the ADF skin to refer to this image. Note that this URLis updated when you deploy your ADF skin (and associated files) in an ADF LibraryJAR, as described in Packaging an ADF Skin into an ADF Library JAR.

Tip:

Associate an image with a global selector alias. If multiple componentselectors reference the global selector alias, you only need to make onechange if you want to use a different image at a later time (change the imageassociated with the global selector alias). See Creating a Global SelectorAlias.

If your ADF skin extends the Skyros ADF skin, you can change some of the morefrequently used images in the design editor, as described in Changing Images andColors in the ADF Skin Design Editor.

7.4.1 How to Copy an Image into the ProjectYou use a context menu to copy an image that an extended ADF skin references intoa directory of the project for your ADF skin. You then make the changes that you wantto the image.

To copy an ADF skin image into your project:

1. In the Selector Tree of the selectors editor, select the selector that references theimage you want to change.


7-9

For example, select the ADF Faces column component's sort-descending-icon-style selector to change the sort ascending icon, as shown in Figure 7-8.

Figure 7-8 Column Component's sort-descending-icon-style Selector

2. In the Properties window, expand the Common section and select Copy Imagefrom the Background Image list, as shown in Figure 7-9.

Figure 7-9 Copy Image Menu to Import an Image into a JDeveloper Project

This copies the image into the project for your ADF skin.

7.4.2 What Happens When You Copy an Image into the ProjectThe image is copied into a subdirectory that is generated in the project of your ADFskin. For example, if you decided to copy the image that the ADF Faces columncomponent's sort-ascending-icon-style selector references, the colSort_asc_ena.pngfile is copied to the following directory:

/public_html/skins/skin1/images/af_column

where af_column refers to the ADF Faces column component.

The relative URL value of the property in the Properties window is modified toreference the new location of the image. Figure 7-10 shows an example.

In addition, the Properties window indicates that the selector no longer inherits theimage from the extended ADF skin by displaying a green icon to the left of the propertylabel. Figure 7-10 shows the Properties window after importing thecolSort_asc_ena.png file into the project for the ADF skin using the Background Imageproperty. Note that the ADF skin still inherits the values for the Height and Widthproperties from the extended ADF skin.


7-10

Figure 7-10 Properties Window After Importing an Image into an ADF Skin

Finally, CSS syntax appears in the source file of your ADF skin. Example 7-3 showsthe CSS syntax that corresponds to the values shown in Figure 7-10.

Example 7-3 CSS Syntax in Source File of ADF Skin After Importing an Image

af|column::sorted-ascending-icon-style{ background-image: url("images/af_column/colSort_des_ena.png");}


7-11

Chapter 7

Changing an Image for a Component Selector

7-12

8Working With Text in an ADF Skin

ADF skins reference resource strings from resource bundles to render in the userinterface of your web application. You can also specify additional resource bundleswith different resource strings for your ADF skin to use.ADF skins reference resourcestrings from resource bundles to render in the user interface of your web application.You can also specify additional resource bundles with different resource strings foryour ADF skin to use.This chapter includes the following sections:

• About Working with Text in an ADF Skin

• Using Text From Your Own Resource Bundle

8.1 About Working with Text in an ADF SkinDefine text for use by ADF Faces components in resource bundles that you registerwith ADF skin project.The source file for an ADF skin does not store any text that ADF Faces componentsrender in the user interface of your application. Applications that render ADF Facescomponents abstract the text that these components render as resource strings andstore the resource strings in a resource bundle. For example, Figure 8-1 shows anADF Faces dialog component that renders buttons with OK and Cancel labels.

Figure 8-1 ADF Faces dialog Component

The text that appears as the labels for these buttons (OK and Cancel) is defined in aresource bundle and referenced by a resource string. If you want to change the textthat appears in the button labels, you create a resource bundle where you define thevalues that you want to appear by specifying alternative text for the following resourcestrings:

• af_dialog.LABEL_OK

• af_dialog.LABEL_CANCEL

8-1

Note:

By default, a resource bundle (skinBundle.properties) is created in yourproject when you create a new ADF skin, as described in Creating an ADFSkin File.

In addition to the resource strings that define the text to appear in the user interface forspecific components, there are a range of resource strings that define text to appearthat is not specific to any particular component. These resource strings are referred toas global resource strings. For information about the resource strings for ADF Facescomponents and global resource strings, see the Tag Reference for Oracle ADFFaces Skin Selectors.

ADF Faces components provide automatic translation. The resource bundle used forthe ADF Faces components' skin is translated into 28 languages. If, for example, anend user sets the browser to use the German (Germany) language, any text containedwithin the components automatically displays in German. For this reason, if you createa resource bundle for a new ADF skin, you must also create localized versions of thatresource bundle for any other languages your web application supports.

For information about creating resource bundles, resource strings, and localizing ADFFaces components, see Manually Defining Resource Bundles and Locales inDeveloping Web User Interfaces with Oracle ADF Faces.

8.2 Using Text From Your Own Resource BundleIf you enter alternative text in a resource bundle to override the default text values thatrender in the user interface of the ADF Faces components in your application, youneed to specify this resource bundle for your application.At runtime, the application renders the alternative text in your resource bundle for theresource strings that you override. For resource strings that you do not override, theapplication renders the text defined in the base resource bundle. For example, Figure 8-4 shows an ADF Faces dialog component where the application developeroverrides the default value for the af_dialog.LABEL_OK resource string from OK to Yaywhile the default value for the af_dialog.LABEL_CANCEL resource string remainsunchanged. That is, the application developer did not define a value for theaf_dialog.LABEL_CANCEL resource string in a resource bundle; the applicationreferences the base resource bundle for this resource string's value.

Figure 8-2 Overridden and Default Values Resource Strings

For information about how to create a resource bundle and how to define string keyvalues, see Manually Defining Resource Bundles and Locales in Developing WebUser Interfaces with Oracle ADF Faces.

Chapter 8Using Text From Your Own Resource Bundle

8-2

8.2.1 How to Specify an Additional Resource Bundle for an ADF SkinYou specify a resource bundle for your ADF skin by adding its name and location as avalue to the bundle-name property in the trinidad-skins.xml file.

To specify an additional resource bundle for an ADF skin:

1. In the Applications window, double-click the trinidad-skins.xml file for yourapplication. By default, this is under the Web Content/WEB-INF node.

2. In the Structure window, right-click the skin node for which you want to add anadditional resource bundle and choose Insert inside skin > bundle-name.

3. In the Properties window, specify the name and location for your resource bundleas a value for the bundle-name property.

For example, the resource bundle that is created by default after you create the firstADF skin in your project, as illustrated in Figure 8-3, specifies the following valuefor the <bundle-name> element:

<bundle-name>resources.skinBundle</bundle-name>

Figure 8-3 Default Resource Bundle for an ADF Skin

8.2.2 What Happens When You Specify an Additional ResourceBundle for an ADF Skin

The trinidad-skins.xml file references the resource bundle that you specified as avalue for the bundle-name property, as shown in the following example.

<skin> <id>skin1.desktop</id> <family>skin1</family> <extends>skyros-v1.desktop</extends> <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id> <style-sheet-name>skins/skin1/skin1.css</style-sheet-name> <bundle-name>resources.skinBundle</bundle-name></skin>


8-3

At runtime, the application renders text values that you specified in your resourcebundle to override the default text values. For example, assume that you defined aresource bundle where you specified Yeah as the value for the af_dialog.LABEL_OKresource sting and Oops as the value for the af_dialog.LABEL_CANCEL. Figure 8-4 showsa dialog component that renders labels using these values.

Figure 8-4 Dialog Rendering Labels Defined in a Custom Resource Bundle


8-4

9Working With Global Selector Aliases

Work with global selector aliases to make a change in one location of your ADF skinthat applies to multiple ADF Faces components used throughout the user interface ofyour Fusion web application.This chapter includes the following sections:

• About Global Selector Aliases

• Creating a Global Selector Alias

• Modifying a Global Selector Alias

• Applying a Global Selector Alias

• Referencing a Property Value from Another Selector

9.1 About Global Selector AliasesA global selector alias defines style properties in one location in the ADF skin that youcan apply to multiple ADF Faces and ADF Data Visualization components. A globalselector alias may also be referred to as a selector alias, or simply a selector.The ADF skins provided by Oracle ADF, described in Inheritance Relationship of theADF Skins Provided by Oracle ADF and ADF Skins Provided by Oracle ADF makeextensive use of global selector aliases to define common style properties for text,messages, icons, colors and different groups of components. Many component-specific selectors inherit the styles defined for these global selector aliases. Forexample, the.AFDefaultFontFamily:alias global selector alias defines a default fontfamily for all ADF Faces components in your application that display text. Any ADFskin that you create by extending from one of the ADF skins provided by Oracle ADFinherits the properties defined in the .AFDefaultFontFamily:alias global selector alias. Figure 9-1 shows how the selectors editor displays that the af|button selector inheritsthe value for font family from the.AFDefaultFontFamily:alias global selector alias.

9-1

Figure 9-1 Component Selector Inheriting Value from Global Selector Alias

Figure 9-1 also shows the different categories of global selector aliases. Eachcategory groups global selector aliases according to their purpose:

• Color: Defines colors used by the ADF skins provided by Oracle ADF. Manyglobal selector aliases that you may want to override appear in this categorybecause they determine most of the colors that appear in a web application.Changes that you make to these global selector aliases have the most effect if youextend the Alta or Skyros ADF skins described in ADF Skin Selectors and IconImages. You can change the color palette of an ADF skin that extends from theseADF skins relatively quickly by changing the global selector aliases that arecategorized as anchor colors. See Working with Anchor Colors in an ADF Skin.

Chapter 9About Global Selector Aliases

9-2

Tip:

As with other global selector aliases, you can view which component-specificselectors inherit the values defined in a specific global selector using the Viewas list.

• Component Group: Button: Defines style properties inherited by selectors formany of the ADF Faces components that render buttons. For example,the .AFButtonAccessKeyStyle:alias global selector alias defines style properties forthe access key rendered by the ADF Faces button and dialog components amongothers.

• Component Group: Form Controls: Defines style properties for form controls.

• Component Group: Link: Defines style properties for many of the componentsthat render links.

• Component Group: Menu: Defines style properties for many of the componentsthat render menus.

• Component Group: PanelBox and Region: Defines style properties for thepanelBox and region components.

• Component Group: PanelHeader: Defines style properties for the panelHeadercomponents.

• Font: Defines style properties for fonts. For example,the .AFDefaultFontFamily:alias global selector alias defines the style propertiesinherited by many of the ADF Faces component selectors.

• Icons: Defines the style properties that apply to icons that render in multiplecomponents.

• Message Selectors: Defines style properties for messages that ADF Faces inputcomponents display when they render different types of messages. See Configuring ADF Skin Properties to Apply to Messages .

• Miscellaneous: Defines global selector aliases that do not fit in the othercategories. For example, the .AFDynamicHelpIconStyle:alias global selector aliasdefines the style to use for the dynamic help icon.

For detailed descriptions of the global selector aliases, see the Tag Reference forOracle ADF Faces Skin Selectors. Global selector aliases that you define appearunder the Global Selector Aliases node, as shown by the entry forthe .UserDefined:alias in Figure 9-1.

The View as list displays the list of components that reference a global selector aliaswhen you select a global selector alias in the Selector Tree. In Figure 9-2, the userselected Panel Window from the list because the panelWindow component referencesthe global selector alias.


9-3

Note:

Sometimes components appear in the View as list for which the styleproperties defined in the global selector alias do not render in the component.This may be because the component initially referenced the global selectoralias in an extended ADF skin and your ADF skin overrides the global selectoralias for that component. Alternatively, it may be because the component itselfoverrides the global selector alias using one of its style-related attributes(styleClass or inlineStyle).

In Figure 9-2, the user has changed the inherited value forthe .AFDefaultFontFamily:alias global selector alias and viewed the resulting changeas it applies to the panelWindow component. All selectors that inherit the value ofthe .AFDefaultFontFamily:alias global selector alias will render at runtime using thefont family defined in the ADF skin. For example, both the dialog and panelWindowcomponents render using this font family.

Figure 9-2 ADF Skin Changing a Global Selector Alias

In addition to the global selector aliases already described, a number of componentselectors define selector aliases that are specific to these components only. Theseselector aliases appear under the nodes for the component selectors in the SelectorTree. Figure 9-3 shows examples from a number of the component selectors thatexpose these types of selector aliases.


9-4

Figure 9-3 Component Selector Aliases

9.2 Creating a Global Selector AliasCreate a global selector alias to define in one location the style properties that youwant a number of selectors to reference.You enter the name of the new global selector alias in the Create Alias Selector dialog.The editor for ADF skins in JDeveloper appends the keyword :alias and prepends . tothe name that you enter in the dialog. For example, if you enter myGlobalSelector asthe name in the dialog, the resulting name that appears in the user interface and in thesource file of the ADF skin is:

.myGlobalSelector:alias

The keyword :alias identifies your global selector alias as a CSS pseudo-class andserves as a syntax aid to organize the CSS code in the source file of your ADF skin.

After you create a global selector alias, you modify it to define the style properties thatyou want it to contain. See Modifying a Global Selector Alias.

9.2.1 How to Create a Global Selector AliasYou can create a global selector alias that defines the style properties that you want anumber of user interface components to use.

To create a global selector alias:

1. In the Selector Tree of the selectors editor, select New Alias Selector from thedropdown list, as illustrated in Figure 9-4.

Figure 9-4 New Alias Selector Option in the Selector Tree

The Create Alias Selector dialog opens.

2. Enter a name for the global selector alias in the Alias Selector Name field.

Chapter 9Creating a Global Selector Alias

9-5

Tip:

Enter a name for the global selector alias that indicates the purpose it serves.For example, MyLinkHoverColor for a global selector alias that is to change thecolor of a link when an end user hovers over the link.

3. Click OK.

4. In the Properties window, set values for the properties that you want to configure inthe global selector alias.

9.2.2 What Happens When You Create a Global Selector AliasThe global selector alias appears under the Global Selector Aliases node in theSelector Tree and a visual representation as it applies to a component appears in thePreview Pane, as illustrated in Figure 9-5, where the outputText component renders.

Figure 9-5 Newly-Created Global Selector Alias

CSS syntax for the global selector alias that you create appears in the source file ofthe ADF skin. The following example shows the entries that appear in the source file ofthe ADF skin in Figure 9-5.

.MyLinkHoverColor:alias{}

9.3 Modifying a Global Selector AliasModifying a global selector alias that appears under the Global Selector Aliases nodein the Selector Tree when you first create the ADF skin means that you override theinherited style properties defined in the parent ADF skin of your ADF skin.You can modify any of the categories of global selector alias described in About GlobalSelector Aliases. Modifying a global selector alias that appears under the GlobalSelector Aliases node in the Selector Tree when you first create the ADF skin meansthat you override the inherited style properties defined in the parent ADF skin of yourADF skin. The parent ADF skin is the ADF skin from which your ADF skin extends.You chose the ADF skin from which to extend when you created an ADF skin, asdescribed in Creating an ADF Skin File. After you modify a global selector alias, thecomponent-specific selectors that inherit the style properties defined in the globalselector alias use the modified values.

Chapter 9Modifying a Global Selector Alias

9-6

Modifying a global selector alias that you create in your ADF skin does not overrideany style properties inherited from the parent ADF skin.

9.3.1 How to Modify a Global Selector AliasYou modify a global selector alias by setting values for it in the Properties window. Youthen verify that the changes you make apply to the component-specific selectors asyou intend.

To modify a global selector alias:

1. In the Selector Tree of the selectors editor, select the global selector alias that youwant to modify.

For example, if you want to modify the global selector alias that defines the defaultfont family, select .AFDefaultFontFamily:alias as illustrated in Figure 9-6.

Figure 9-6 Modifying a Global Selector Alias

2. In the Properties window, set values for the properties that you want to modify.

3. In the selectors editor, click the View as list to select a component-specific selectorthat inherits the property values defined in the global selector alias that you havejust modified.

4. In the selectors editor, verify that the changes render for the component-specificselector as you intend. Repeat Steps 1 to 3 until you achieve the changes you wantfor the component-specific selectors that inherit from the global selector alias.

9.4 Applying a Global Selector AliasAfter you create a global selector alias in your ADF skin, you need to specify the ADFFaces and ADF Data Visualization components that you want to render at runtimeusing the style properties that you defined in the global selector alias.Applying a global selector alias to an ADF Faces or ADF Data Visualizationcomponent requires you to:

• Select the selector, pseudo-element, or pseudo-class for each component that youwant to apply the style properties defined in the global selector alias. If you want to

Chapter 9Applying a Global Selector Alias

9-7

apply the style properties defined in your global selector alias to another globalselector alias, select the target global selector alias.

• Set the global selector alias as a value for the -tr-rule-ref- ADF skin property.

9.4.1 How to Apply a Global Selector AliasYou apply a global selector alias by specifying it as a value for the -tr-rule-ref- ADFskin property.

To apply a global selector alias:

1. In the Selector Tree of the selectors editor, select the item to which you want toapply the global selector alias.

For example, select the inputText component's content pseudo-element if youwant to apply the style properties defined in your global selector alias to the labelfor that component, as shown in Figure 9-7.

2. In the Properties window, expand the Common section and then click the Add iconnext to the -tr-rule-ref- field.

3. Enter the name of the global selector alias. Enter the name between quotes thatyou preface with the selector keyword in the Value field.

For example, if the name of the global selector alias is .MyBackgroundColor:alias,enter selector(".MyBackgroundColor:alias"), as illustrated in Figure 9-7.

Figure 9-7 inputText Component's content Pseudo-Element

4. Click the Refresh icon in the Preview Pane to view the changes.

9.4.2 What Happens When You Apply a Global Selector AliasThe selector to which you applied the global selector alias inherits the style propertiesdefined in the global selector alias. Figure 9-8 shows the content pseudo-element forthe inputText component's selector that inherits the style properties defined inthe .MyBackgroundColor:alias global selector alias. The properties that inherit theirvalues from a global selector alias when you specify the global selector alias as avalue for the -tr-rule-ref ADF skin property update to use the inheritance icon, asshown for the Background Color and Color fields in Figure 9-8.

At runtime, the inputText component's content area renders using the style propertiesdefined in the global selector alias.


9-8

Figure 9-8 Global Selector Alias Applied to inputText Component

9.4.3 What You May Need to Know About Applying a Global SelectorAlias

If you override a global selector alias in an extended ADF skin, component selectorsthat used the –tr-rule-ref ADF skin property to determine the value of a style propertyin the parent ADF skin use the overridden value of the global selector alias. Thefollowing example shows ADF skin B that extends ADF skin A. At runtime, the top of adecorativeBox component renders red for the background-color CSS property becausethe global selector alias in ADF skin B overrides ADF skin A.

/** Skin A **//** ---------------------------------- **/.MyBackColor:alias { background-color: blue} af|decorativeBox::top { -tr-rule-ref: selector(".MyBackColor:alias");} /** Skin B **//** ---------------------------------- **/

.MyBackColor:alias { background-color: Red}

If you specify a style property value in an extended ADF skin where the parent ADFskin also specifies a value for the style property, the ADF skinning frameworkapplies the value in the extended ADF skin. Example 9-1 shows ADF skin C wherethe .myClass style class specifies Red as the value for the background-color CSS


9-9

property. If an application uses ADF skin D (that extends ADF skin C), componentsthat apply the .myClass style class apply Lime for the background-color CSS property.This is because the ADF skinning framework calculates the values of statements thatinclude values in an ADF skin (like –tr-rule-ref) first. The ADF skinning frameworkthen calculates specific properties (for example, background-color) next. As a result,the value for the background-color CSS property in ADF skin D (Lime) overrides thevalue for the –tr-rule-ref ADF skin property (Blue) or inherited values from ADF skinC (Red).

Note:

If you subsequently override the .myClass style class as follows in ADF skin D,the value that the ADF skinning framework applies for the background-colorCSS property is Blue:

.myClass {-tr-rule-ref: selector(".MyBlueColor:alias")}

Consider using tools, such as Firebug for the Mozilla Firefox browser (or similar foryour browser), when you run your application to determine what style property valuethe ADF skinning framework applies to a component selector at runtime. See TestingChanges in Your ADF Skin .

Example 9-1 Overriding a Local Global Selector Alias

/** ADF skin C **//** ---------------------------------- **/.myClass { background-color: Red} /** ADF skin D **//** ---------------------------------- **/.MyBackColor:alias { background-color: Blue;}

.myClass { background-color: Lime; -tr-rule-ref: selector(".MyBackColor:alias")}

9.5 Referencing a Property Value from Another SelectorRather than set a specific style property for each selector to which you want to applythe style property, you can reference the value of a property using the -tr-property-ref ADF skin property.You can configure this ADF skin property for global selector aliases and component-specific selectors. For example, you could define a value for the background-colorproperty in a global selector alias and reference this value from multiple otherselectors. If you decide at a later time to change the value of the background-colorproperty, you change the value in the global selector alias. All selectors that referencethe background-color property using the -tr-property-ref ADF skin property update touse the change you make. The -tr-property-ref ADF skin property can also be usedwith compact CSS properties like, for example, border.

Chapter 9Referencing a Property Value from Another Selector

9-10

9.5.1 How to Reference a Property Value from Another SelectorYou reference the property value that you want to use for a selector using the -tr-property-ref ADF skin property.

To reference a property value from another selector:

1. In the Selector Tree of the selectors editor, select the selector that you want toreference a property value from another selector.

For example, if you want the content area of the panelWindow component toreference a style property defined in another selector, select content under thePseudo-Elements node of the panelWindow component, as illustrated in Figure 9-9.

Figure 9-9 Panel Window Component's content Pseudo-Element

2. In the Properties window, specify the property value that you want to reference as avalue for the selector's property using the -tr-property-ref ADF skin property.

For example, assume that you created the following global selector alias:

.MyColor:alias { color: rgb(255,181,99); font-weight: bold;}

and that you want to reference the color property from this global selector alias forthe background-color property of the content pseudo-element that you selected inStep 1. In this scenario, enter the following value for the background-color propertyof the content pseudo-element,

-tr-property-ref(".MyColor:alias","color");

If you want to use the -tr-property-ref in compact values, enter syntax similar tothe following:

border: 10px solid -tr-property-ref(".AFDefaultColor:alias", "color");

9.5.2 What Happens When You Reference a Property Value fromAnother Selector

The Properties window shows that the property for which you set a value using the -tr-property-ref ADF skin property to reference a value from another selector inheritsits value, as illustrated in Figure 9-10.


9-11

Figure 9-10 Selector Property Referencing a Property Value from Another Selector

Syntax similar to the following example appears in the source file of the ADF skin.

@charset "UTF-8";/**ADFFaces_Skin_File / DO NOT REMOVE**/@namespace af "http://xmlns.oracle.com/adf/faces/rich";@namespace dvt "http://xmlns.oracle.com/dss/adf/faces"; .MyColor:alias { color: rgb(255, 181, 99); font-weight: bold;} .AFDefaultColor:alias { color: Red;} af|panelWindow::content { background-color: -tr-property-ref(".MyColor:alias", "color"); border: 10px solid -tr-property-ref(".AFDefaultColor:alias", "color");}


9-12

10Working with Style Classes

Create style classes in your ADF skin when you want to define styles for specificinstances of ADF components.This chapter includes the following sections:

• About Style Classes

• Creating a Style Class

• Modifying a Style Class

• Configuring a Style Class for a Specific Instance of a Component

10.1 About Style ClassesA style class allows you to specify a number of style properties in one location in anADF skin that you want to apply to specific instances of ADF Faces or ADF DataVisualization components.The style properties that you define for a style class take precedence over the styleproperties that you define for the component's selectors. Application developers canspecify a style class as a value for the styleClass and inlineStyle attributes that manyADF Faces components expose. At runtime, the style properties that you defined inthe style class get applied to the ADF Faces component rather than other styleproperties defined in the ADF skin. Style classes differ from the global selector aliases,described in Working With Global Selector Aliases, which enable you to define styleproperties that you want to apply to multiple ADF Faces components.

Figure 10-1 shows an ADF skin with the nodes expanded for the different categories ofstyle classes.

Figure 10-1 Categories of Style Class

Each category of style class serves a purpose:

• Miscellaneous: Miscellaneous style classes inherited from the extended ADFskins. For example, this category includes the .AFBrandingBar style class that canbe used for a branding bar containers.

• Note Window Selectors: Style classes inherited from the extended ADF skinsthat affect the noteWindow component.

10-1

• Popup: Style classes inherited from the extended ADF skins that affect the popupcomponent.

• Text: Style classes inherited from the extended ADF skins that determine theappearance of various types of text (for example, address fields and instructiontext).

Style classes that you or other users define appear under the Style Classes node asshown by the entry for the .UserDefined style class in Figure 10-1. For detaileddescriptions of the style classes in the ADF skins that Oracle ADF provides, see the Tag Reference for Oracle ADF Faces Skin Selectors.

10.2 Creating a Style ClassYou can create a new style class in your ADF skin or override a style class that yourADF skin inherits from the ADF skin that it extends in order to specify style propertiesfor specific instances of ADF Faces components.After you create a style class, you modify it to define the style properties that you wantit to contain. See Modifying a Style Class.

10.2.1 How to Create a Style ClassYou can create a style class that defines the style properties you want an applicationdeveloper to apply to an ADF Faces or ADF Data Visualization component using thecomponent's styleClass or inlineStyle attribute.

To create a style class:

1. In the Selector Tree of the selectors editor, select New Style Class from thedropdown list, as shown in Figure 10-2.

Figure 10-2 New Style Class Option in the Selector Tree

The Create Style Class dialog opens.

2. Choose the appropriate option:

• Enter a new name if you want to create a new style class that does not inheritstyle properties from an ADF skin that your ADF skin extends.

Tip:

Enter a name for the style class that indicates the purpose it serves.

• Enter the name of a style class that inherits style properties from an ADF skinthat your ADF skin extends and for which you want to override style propertiesin your ADF skin.

3. Click OK.

Chapter 10Creating a Style Class

10-2

10.2.2 What Happens When You Create a Style ClassThe style class appears under the Style Classes node in the Selector Tree and avisual representation as it applies to a component appears in the Preview Pane, asshown in Figure 10-3.

Figure 10-3 Newly-Created Style Class

CSS syntax for the style class that you create appears in the source file of the ADFskin. The following example shows the entries that appear in the source file for theADF skin in Figure 10-3.

.OrderOverdue{}

10.3 Modifying a Style ClassModify a style class to change the style properties that apply to specific instances ofADF Faces components.The process to modify a style class is the same for the different categories of styleclass that appear in the selectors editor. You select the style class in the Selector Treeand use the menus in the Preview Pane to add or remove pseudo-classes to the styleclass or use the Properties window to set or override style properties for the styleclass.

10.3.1 How to Modify a Style ClassYou select the style class under the Style Classes node in the Selector Tree andmodify its properties using the Properties window.

To modify a style class:

1. In the Selector Tree, navigate to the style class that you want to modify.

2. In the Properties window, make changes to the properties that you want toconfigure for the style class.

3. Click the Refresh icon to update the Preview Pane after you make changes to thestyle class.

Chapter 10Modifying a Style Class

10-3

10.4 Configuring a Style Class for a Specific Instance of aComponent

Once you have defined a style class with the style properties that you want to apply,you configure the instance of the ADF Faces component that you want to render usingthese style properties.You can define a style class where you define style properties to apply to a specificinstance of a component. Consider, for example, a panelBox component thatapplication developers use to show or hide content on a page. One page can rendermultiple instances of a panelBox component. You decide to make fuchsia the defaultbackground color for the header text that panelBox components render, as shown in Figure 10-4.

Figure 10-4 Setting Background Color for a panelBox Component

However, you decide that you want to render one or more instances of the panelBoxcomponent without the disclosure link control that allows end users to show and hidethe content in the component. Additionally, you decide that you want the header text ofthese instances of the panelBox component to render with the background color set tored. To achieve this, you define style properties for a style class in the ADF skin. Youthen specify the style class as the value for the styleClass attribute for each instanceof the panelBox component that you want to render using these style properties. Thefollowing example shows the syntax that appears in the source file of the ADF skin toachieve the outcome just described.

.panelBoxInstanceClass af|panelBox::disclosure-link{display:none;}

.panelBoxInstanceClass af|panelBox::header-text {background-color: Red;}

Note:

You cannot configure ADF skin properties in the style classes that you createfor specific instances of a component. ADF skin properties allow you tocustomize the rendering of a component throughout the application, notspecific instances of a component. For information about ADF skin properties,see Properties in the ADF Skinning Framework.

Chapter 10Configuring a Style Class for a Specific Instance of a Component

10-4

10.4.1 How to Configure a Style Class for a Specific Instance of aComponent

You specify the style class as the value for the styleClass attribute for each instance ofa component that you want to render using the style class.

To configure a style class for a specific instance of a component:

1. Create a style class, as described in Creating a Style Class.

2. In JDeveloper, set the component's styleClass attribute to the name of the styleclass you created in step 1.

For information about setting the component's styleClass attribute, see How to Seta Style Class in Developing Web User Interfaces with Oracle ADF Faces.

10.4.2 What Happens When You Configure a Style Class for aSpecific Instance of a Component

At runtime, instances of the component for which you do not specify instance-specificstyle properties using a style class render using the style properties defined in thecomponent-specific selectors and global selector aliases. In Figure 10-5, this is thepanelBox component labeled First Panel Box. Instances of the component for whichyou specify a style class as a value for the styleClass attribute render using the styleproperties defined in this style class. In Figure 10-5, this is the panelBox componentlabeled Second Panel Box.

Figure 10-5 Component Rendering with Style Properties Defined in Style Class

Chapter 10Configuring a Style Class for a Specific Instance of a Component

10-5

Chapter 10

Configuring a Style Class for a Specific Instance of a Component

10-6

11Working with At-Rules

Use at-rules to specify style properties that you want to use when an application pagerenders in a particular environment. At-rules can be interpreted by the ADF skinningframework or by the browser where your application page renders.This chapter includes the following sections:

• About At-Rules in the ADF Skinning Framework

• Working with Server-Side At-Rules

• Working with Client-Side At-Rules

• Creating At-Rules in an ADF Skin

11.1 About At-Rules in the ADF Skinning FrameworkUse CSS at-rules (at-rules) to define style properties for when an application's pagerenders in a particular environment such as, for example, a browser, platform, locale,or device.The ADF skinning framework supports a number of at-rules that allow you to defineproperties for selectors that you want to apply to a particular environment. Forexample, you may need to add some padding in Internet Explorer that you do not needon any other browser or perhaps you want to increase the size of icons if a pagerenders on a touch device. To style a selector for these scenarios, put the styleproperties inside an at-rule.

The ADF skinning framework divides the at-rules that it supports into two categories. Itcategorizes any at-rules that it passes directly to the user agent to interpret as aclient-side at-rule and any at-rules that the ADF skinning framework itself interpretsas a server-side at-rule. For information about these categories, see Working withServer-Side At-Rules and Working with Client-Side At-Rules.

You can use the selectors editor in JDeveloper to create at-rules in your ADF skin, asdescribed in Creating At-Rules in an ADF Skin. At-rules that your ADF skin inherits orat-rules that you define in your ADF skin appear in the Selector Tree under the At-Rules node, as illustrated in Figure 11-5.

11-1

Figure 11-1 At-Rules in the Selector Tree

Apart from the at-rules described in this chapter, you can also use the @import at-ruleto import another ADF skin into your ADF skin. See Importing One or More ADF SkinsInto the Current ADF Skin.

11.2 Working with Server-Side At-RulesThe ADF skinning framework supports a number of server-side at-rules that enableyou to specify style properties to render when your application runs in a specific locale,mode, platform, or user agent.Table 11-1 lists a number of the server-side at-rules that the ADF skinning frameworksupports. The ADF skinning framework interprets these rules and determines the styleproperties to render, as described in What Happens at Runtime: How the ADFSkinning Framework Applies At-Rules.

Table 11-1 Server-Side At-Rules Supported by the ADF Skinning Framework

Name Description

@accessibility-profile Defines styles for high-contrast and large-fonts accessibility profile settingswhen enabled in the trinidad-config.xml file.

For information about the @accessibility-profile rule, see Configuring an ADFSkin for Accessibility.

@locale Specify a locale to define styles only for a particular language and country. Youcan specify either only the language or both the language and the country.

Note that the ADF skinning framework does not support the :lang pseudo class.

@mode Defines styles for when a page renders in a particular mode. This at-rule supportsthe following values:

• quirks

• standards

Chapter 11Working with Server-Side At-Rules

11-2

Table 11-1 (Cont.) Server-Side At-Rules Supported by the ADF Skinning Framework

Name Description

@platform Define platform styles. Supported values are:

• android

• blackberry

• genericpda

• iphone

• linux

• macos

• nokia_s60

• ppc (Pocket PC)• solaris

• unix

• windows

Apart from the rules listed in Table 11-1, one of the most frequently used server-sideat-rules is @agent. The @agent at-rule enables you to define styles to apply to one ormore user agents. The following list specifies the supported values to set an agent-specific style using the @agent at-rule.

• blackberry

• email

• gecko

• genericDesktop

• genericpda

• googlebot

• ie

• konqueror

• mozilla

• msnbot

• nokia_s60

• opera

• oracle_ses

• unknown

• webkit (maps to Safari and Google Chrome)

Using the @agent at-rule, you can:

• Specify styles for any version of Internet Explorer:

@agent ie

• Optionally, specify a specific version of the agent using the and keyword. Forexample, to specify version 9 of Internet Explorer:

@agent ie and (version: 9)


11-3

• Use comma-separated rules to specify styles for a number of agents. Forexample, use the following rule to specify styles for Versions 15 and 17 of MozillaFirefox and for Internet Explorer 9.x:

@agent mozilla and (version: 15.*), mozilla and (version: 17.*), ie and

(version: 9.*)

• Note that the following two syntax examples specify the same rule:

@agent ie and (version: 9.*)

@agent ie and (version: 9)

To specify a rule for styles to apply only to Internet Explorer 9.0.x, write thefollowing:

@agent ie and (version: 9.0.*)

• Use the max-version and min-version keywords to specify a range of versions. Forexample, you can rewrite the following rule:

@agent ie and (version: 9), ie and (version: 10)

as:

@agent ie and (min-version: 9) and (max-version: 10)

to apply styles that you define to all versions of Internet Explorer 9 and 10.

You can also use the @agent rule to determine styles to apply to agents that are touchdevices. The following examples show the syntax that you write in an ADF skin file toconfigure this capability.

@agent (touchScreen) { /* Touchscreen specific styles for all touch devices: both single and multiple touch. */}

@agent (touchScreen:single) { /* Styles specific for a touch device with single touch. */} @agent (touchScreen:multiple) { /* Styles specific for a touch device with multiple touch. */}

Use the @agent (touchScreen:none) at-rule to specify styles that you do not want torender on a touch device. For example, the Alta skin applies this at-rule to selectorsconfigured to use the :hover pseudo class. This is because the :hover pseudo-class isnot appropriate for use on a touch device. The @agent (touchScreen:none) at-rulewraps selectors that use the :hover pseudo-class, as in the following example:

@agent (touchScreen:none){

.AFBrandingBar af|link:hover,

.AFBrandingBar af|goLink:hover,

.AFBrandingBar af|commandLink:hover,

...

Figure 11-2 shows how the Selector Tree displays selectors to which the @agent(touchScreen:none) at-rule is applied.


11-4

Figure 11-2 @agent (touchScreen:none) at-rule in the Selector Tree

For information about creating applications to render in touch devices, see CreatingWeb Applications for Touch Devices Using ADF Faces in Developing Web UserInterfaces with Oracle ADF Faces.

For information about how to create an at-rule in an ADF skin, see Creating At-Rulesin an ADF Skin.

11.3 Working with Client-Side At-RulesUse client-side at-rules when you want your application to render styles appropriate tothe user agent such as, for example, styles to use based on the screen width of theuser’s browser. The ADF skinning framework passes directly to the user agent tointerpret the at-rule.The ADF skinning framework does not evaluate the following list of at-rules:

• @charset

• @document

• @font-face

• @import

• @keyframes

• @media

• @page

• @supports

Chapter 11Working with Client-Side At-Rules

11-5

Instead, it passes the at-rule, and the style properties within the at-rule, directly to theuser agent. The user agent evaluates the at-rule and applies the style properties withinthe at-rule if the condition that the at-rule specifies is satisfied.

Because the style properties inside client-side at-rules get passed directly to the useragent, you cannot use ADF skin properties or global selector aliases inside client-sideat-rules. The ADF skinning framework needs to evaluate these items to determinetheir runtime values. Example 11-1 demonstrates a number of valid usages of client-side at-rules in an ADF skin. In Example 11-1, the @media at-rule specifies the styleproperties to render for an af:button component when a screen has a maximum widthof 1680px. The example also specifies style properties to apply for the af:buttoncomponent when this condition is not met.

Note:

Do not insert ADF skin properties or global selector aliases inside a client-sideat-rule. Unexpected behavior may result when you render a page using theADF skin. The name of an ADF skin property is prefaced by -tr- and a globalselector alias appends :alias. For information, see Properties in the ADFSkinning Framework and About Global Selector Aliases.

Figure 11-3 shows instances of the af:button component that render using theappropriate style properties defined in Example 11-1 based on the maximum width ofthe screen where the components display.

Figure 11-3 Client-Side At-Rule Applied to a Button Component

Client-side at-rules can nest within server-side at-rules. Server-side at-rules can nestwithin client-side at-rules. Example 11-2 demonstrates instances where client-side andserver-side at-rules nest within each other.

The @page and @font-face client-side at-rules are exceptions. These client-side at-rulescannot contain a server-side at-rule because they contain CSS properties whereasother client-side at-rules contain complete styles.

Example 11-1 Client-Side At-Rules in an ADF Skin

...

.myStyleClass { background-color: Yellow;} af|button { -tr-inhibit: background-image; color: Red;} af|button::access-key { background-color: Blue; color: Yellow;}

Chapter 11Working with Client-Side At-Rules

11-6

@media screen and (max-width:1680px) { .myStyleClass { background-color: Red; } af|button { color: Lime; } af|button::access-key { background-color: White; color: Purple; }}...

Example 11-2 Nested Client-Side and Server-Side At-Rules

@agent gecko { @page :first { margin: 2in ; }} @keyframes mymove { @agent gecko { 0% { top: 0; left: 0; } 30% { top: 50px; } 68%, 72% { left: 50px; } 100% { top: 100px; left: 100%; } } @agent ie { 0% { top: 1; left: 1; } 30% { top: 100px; } 100% { top: 200px; left: 100%; } }}

11.4 Creating At-Rules in an ADF SkinYou can create a new at-rule in your ADF skin or override an at-rule that your ADFskin inherits from the ADF skin that it extends. After you create an at-rule, you modify itto define the style properties that you want it to contain.

11.4.1 How to Create an At-RuleYou can create an at-rule to specify that style properties for one or more selectorsrender in a particular way when a condition specified by the at-rule is met.

To create an at-rule:

1. In the Selector Tree of the selectors editor, select New Selector with At-Rule fromthe dropdown list, as illustrated in Figure 11-4.

Chapter 11Creating At-Rules in an ADF Skin

11-7

Tip:

If you know the name of the selector for which you want to configure an at-rule, right-click it in the Selector Tree and, from the context menu, choose NewSelector with At-Rule. This populates the Selector field in the Create At-RuleDeclaration dialog with the name of the selector that you right-clicked.

Figure 11-4 New Selector with At-Rule Menu in the Selector Tree

2. In the Create At-Rule Declaration dialog, select the at-rule that you want toconfigure from the Rule dropdown list.

For information about the at-rules that the ADF skinning framework supports, see Working with Server-Side At-Rules and Working with Client-Side At-Rules.

3. Click OK.

4. In the Selector Tree, select the newly-created at-rule and, in the Properties window,configure the properties that you want this at-rule to apply.

11.4.2 What Happens When You Create an At-RuleThe at-rule appears under the At-Rules node in the Selector Tree and a visualrepresentation as it applies to a component appears in the Preview Pane, as shown in Figure 11-5, where an instance of the af|button component selector renders. CSSsyntax for the at-rule that you create and any properties that you modified also appearin the source file of the ADF skin, as shown in Figure 11-5.


11-8

Figure 11-5 At-Rule in the Selector Tree and Source Editor

In the Properties window for the selector property on which you set an at-rule, an iconappears to indicate that an at-rule is set, as illustrated in Figure 11-6.

Figure 11-6 Properties Window with an At-Rule set on a Property

11.4.3 What Happens at Runtime: How the ADF Skinning FrameworkApplies At-Rules

At runtime, the ADF skinning framework picks the styles with at-rules based on theHTTP request information, such as agent and platform, and merges them with thestyles without rules. Those style properties that match the rules get merged with thoseoutside of any rules. The most specific rules that match a user's environment takeprecedence.


11-9

Example 11-3 shows several selectors in the source file of an ADF skin that will bemerged together to provide the final style.

Example 11-3 Merging of Style Selectors in an ADF Skin

/** For IE and Gecko on Windows, Linux and Solaris, make the color pink. **/@platform windows,linux,solaris{ @agent ie, gecko { af|inputText::content {background-color:pink} }} /** Define default properties for the af|panelFormLayout selector. **/af|panelFormLayout { color: red; width: 10px; padding: 4px}/** Define at-rule for af|panelFormLayout on Internet Explorer (IE). We need to increase the width, so we override the width. We still want the color and padding; this gets merged in. We want to add height in IE. */@agent ie{ af|panelFormLayout {width: 25px; height: 10px}} /** For IE 9 and 10, we also need some margins.*/@agent ie( version:9)and( version:10){ af|panelFormLayout {margin: 5px;}} /** For Firefox 10 (Gecko 10) use a smaller margin.*/@agent gecko( version:10){ af|panelFormLayout {margin: 4px;}}


11-10

12Applying the Finished ADF Skin to YourWeb Application

Once you finish development of your ADF skin, test it, package it, and distribute it inan ADF Library JAR file to the web applications that use it. Configure these webapplications so that they render ADF Faces components using the styles defined inyour ADF skin.This chapter includes the following sections:

• About Applying a Finalized ADF Skin to an Application

• Testing Changes in Your ADF Skin

• Packaging an ADF Skin into an ADF Library JAR

• Applying an ADF Skin to Your Web Application

• Applying an ADF Skin to a Running Web Application

12.1 About Applying a Finalized ADF Skin to an ApplicationBefore you apply an ADF skin to a web application, you package it in an ADF LibraryJAR to distribute it. Test your ADF skin before you distribute it.After you create an ADF skin where you define style properties for one or more ADFskin selectors, you may want to test the changes that you make in the ADF skin. Onceyou complete testing the changes in your ADF skin and are satisfied with the final ADFskin, you can package the ADF skin and associated files (resource bundle, images,and configuration files) into an ADF Library JAR to distribute for inclusion to theapplication projects that use the final ADF skin. Once you have distributed the finalADF skin, you configure the application to apply the ADF skin to it.

12.2 Testing Changes in Your ADF SkinOnce you create an ADF skin and define style properties that you want for selectors,test how these style properties render at runtime in a browser. To do this, apply theADF skin to your application and run a page that renders ADF Faces componentswhich expose the selectors.Consider using tools, such as Firebug for the Mozilla Firefox browser (or similar foryour particular browser), when you run your application. These tools provide usefulinformation that can help you as you iteratively develop your ADF skin. For example, inaddition to inspecting changes that you have already made, these tools can help youidentify the ADF skin selectors that correspond to a particular DOM element.

You can also configure context initialization parameters in the web.xml file of yourapplication that allow you to:

• View changes in an ADF skin without having to restart the application

Set the value of the following context initialization parameter to true:

org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION

12-1

• Display the full uncompressed CSS style class name at runtime

Set the value of the following context initialization parameter to true:

org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION

Note that not all changes that you make to an ADF skin in your web applicationappear immediately if you set the CHECK_FILE_MODIFICATION to true. You must restartthe web application to view changes that you make to icon and ADF skin properties.

For information about context initialization parameters, see ADF Faces Configurationin Developing Web User Interfaces with Oracle ADF Faces.

Figure 12-1 demonstrates how the name of a component selector (for the ADF Facesbutton component) is suppressed. In Figure 12-1, the style class(fndGlobalSearchCategory) that is defined in an ADF skin is applied to the buttoncomponent using the component's styleClass attribute.

Figure 12-1 Compressed CSS from an ADF Skin

Figure 12-2 shows how the browser renders the full uncompressed name of the ADFFaces component when you set the DISABLE_CONTENT_COMPRESSION parameter to true. In Figure 12-2, the uncompressed style class af_button corresponds to the af|buttonselector documented in the Tag Reference for Oracle ADF Faces Skin Selectors.

The uncompressed style classes that correspond to the pseudo-elements that an ADFskin selector exposes can also be identified. For example, the tab-end pseudo-elementexposed by the af|panelTabbed selector (af|panelTabbed::tab-end) translates to theuncompressed af_panelTabbed_tab-end style class at runtime.

Similarly, changes that you make to the appearance of a component when it is in aspecific state can also be identified or inspected using browser tools. For example, the

Chapter 12Testing Changes in Your ADF Skin

12-2

following entry in the source file of an ADF skin allows you to define the style for theADF Faces panelTabbed component when a user selects the right-hand side of thecomponent:

af|panelTabbed::tab:selected af|panelTabbed::tab-end

At runtime, the uncompressed style class name translates to the following:

.af_panelTabbed_tab.p_AFSelected .af_panelTabbed_tab-end

Note that :selected translates to p_AFSelected although sometimes the generated CSSdoes not have a p_AFSelected equivalent because some browsers have built-in supportfor that particular state, as is the case for other pseudo-classes like :hover.

It is recommended that you only customize the ADF skin selectors, pseudo-elements,and pseudo-classes documented in the Tag Reference for Oracle ADF Faces SkinSelectors and the Tag Reference for Oracle ADF Data Visualization Tools SkinSelectors. Customizing other ADF skin selectors may result in unexpected orinconsistent behavior for your application.

Figure 12-2 Uncompressed CSS from an ADF Skin

12.2.1 How to Set Parameters for Testing Your ADF SkinYou set the CHECK_FILE_MODIFICATION and DISABLE_CONTENT_COMPRESSION contextinitialization parameters to true in the web.xml file of your application.

Chapter 12Testing Changes in Your ADF Skin

12-3

To set parameters for testing your ADF skin:

1. In the Applications window, double-click the web.xml file.

2. In the source editor, add the following context initialization parameter entries andset to true:

• org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION

• org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION

3. Save and close the web.xml file.

12.2.2 What Happens When You Set Parameters for Testing YourADF Skin

Entries appear in the web.xml file for your application, as illustrated in the followingexample.

<context-param> <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name> <param-value>true</param-value></context-param><context-param> <param-name>org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION</param-name> <param-value>true</param-value></context-param>

Changes that you make to a selector for an ADF Faces component (other thanchanges to icon and skin properties) render immediately when you refresh a webapplication's page that renders the ADF Faces component. Using Firebug if yourbrowser is Mozilla Firefox or Google Chrome's developer tools, you can see theuncompressed style class names that render at runtime and establish what ADF skinselector it corresponds to. Remember that settingorg.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION to true incurs aperformance cost for your web application so set it to false when you finish testingyour changes.

12.3 Packaging an ADF Skin into an ADF Library JARYou can deploy an ADF skin and associated files (for example, image files,configuration files, and resource bundles) in an ADF Library JAR. This enables you topackage files required to apply an ADF skin to an application.The benefits of packaging ADF skins into an ADF Library JAR as compared tobundling them into the application are the following:

• An ADF skin can be deployed and developed separately from the application. Thisalso helps to reduce the number of files to be checked in case some changesmust be applied to the ADF skin.

• The source files for an ADF skin and images can be separated into their own ADFLibrary JARs. Therefore, you can partition the image base into separate ADFLibrary JARs, so that not all files have to be deployed with all applications.

• An ADF skin in an ADF Library JAR can be applied to an application that isrunning without requiring a restart, as described in Applying an ADF Skin to aRunning Web Application .

Chapter 12Packaging an ADF Skin into an ADF Library JAR

12-4

12.3.1 How to Package an ADF Skin into an ADF Library JARCreate an ADF Library JAR file deployment profile to package the ADF skin into anADF Library JAR.

To create an ADF Library JAR file deployment profile:

1. In the Applications window, right-click the project that contains the ADF skins andchoose Deploy > New Deployment Profile.

2. In the Create Deployment Profile dialog, choose ADF Library JAR File in theProfile Type dropdown list.

3. Enter a name for the deployment profile in the Deployment Profile Name input fieldand click OK.

4. Review the options in the Edit ADF Library JAR Deployment Profile Propertiesdialog that appears. Click Help for additional information.

5. Click OK.

To package an ADF skin into an ADF Library JAR:

1. In the Applications window, right-click the project that contains the ADF skin andchoose Deploy > deployment, where deployment is the name of the ADF LibraryJAR file deployment profile.

2. In the Deploy dialog Deployment Action page, click Deploy to ADF Library JARfile, click Next and then click Finish.

12.3.2 What Happens When You Package an ADF Skin into an ADFLibrary JAR

An ADF Library JAR file is written to the directory specified by the deployment profile.This ADF Library JAR contains the source file for the ADF skin, the trinidad-skins.xmlfile, image files, and any resource bundles that you created to define resource stringsor to override the default strings defined for ADF Faces components. The ADF LibraryJAR file also contains other files from the ADF skin's project not related to skinning.

Example 12-1 shows the directory structure for a project that contains the followingitems for an ADF skin:

• The trinidad-skins.xml file

• An image file (sort_des_ena.png) copied into the JDeveloper project

• The source file for an ADF skin (skin1.css)

• An .sva file (oracle.adf.common.services.ResourceService.sva) that is used toinspect the content of the ADF Library JAR when you import it into a project, asdescribed in Adding ADF Skins from an ADF Library JAR.

• A resource bundle (skinBundle.properties) that contains string values to overridestrings from the default resource bundle

For information about how to specify resource bundles that contain string valuesyou define, see How to Specify an Additional Resource Bundle for an ADF Skin.

Chapter 12Packaging an ADF Skin into an ADF Library JAR

12-5

The directory paths for images in the ADF skin that appear in the ADF Library JAR aremodified to include the directory path from the JDeveloper project. Example 12-2demonstrates an example of the changes that occur:

Example 12-1 Directory Structure for an ADF Library JAR Containing an ADFSkin

ADFLibraryJARRootDirectory+---META-INF| | MANIFEST.MF| | oracle.adf.common.services.ResourceService.sva| | trinidad-skins.xml| || +---adf| | \---skins| | \---skin1| | \---images| | \---af_column| | colSort_des_ena.png| || \---skins| \---skin1| skin1.css|\---resources skinBundle.properties

Example 12-2 Modified Directory Path for Images in a Deployed ADF Skin

// Reference to an image in an ADF skin prior to deployment to an ADF Library JARaf|column::sorted-descending-icon-style{ background-image: url("images/af_column/colSort_des_ena.png"); }

// Reference to an image in an ADF skin after deployment to an ADF Library JARaf|column::sorted-descending-icon-style{ background-image: url("/adf/skins/skin1/images/af_column/colSort_des_ena.png"); }

12.4 Applying an ADF Skin to Your Web ApplicationYou configure an application to use an ADF skin by specifying values in theapplication's trinidad-config.xml file.You specify a value for the <skin-family> element that identifies the ADF skin familythe application uses at runtime. If you created more than one ADF skin in the ADF skinfamily, you can version these ADF skins. If you versioned multiple ADF skins in thesame ADF skin family, use the <skin-version> element in the trinidad-config.xml fileto identify the specific version that you want the application to use.

If you do not identify a specific ADF skin from an ADF skin family by entering a valuefor the <skin-version> element in the trinidad-config.xml file or using the<default>true</default> element in the trinidad-skins.xml file, the application usesthe last skin defined in the trinidad-skins.xml file. For information about versioningADF skins and how this can determine the ADF skin that your application chooses,see Versioning ADF Skins.

Chapter 12Applying an ADF Skin to Your Web Application

12-6

Note that you can configure an application page for your end users to dynamicallyselect the ADF skin that they want the application to use. See Enabling End Users toChange an Application's ADF Skin in Developing Web User Interfaces with OracleADF Faces.

12.4.1 How to Apply an ADF Skin to an ApplicationYou apply an ADF skin to an application by modifying the application's trinidad-config.xml file. You do this by editing the application's trinidad-config.xml file tospecify the ADF skin family to use. Alternatively, you can select the ADF skin familyfrom a list in the ADF View options of JDeveloper's Project Properties dialog.

To apply an ADF skin to an application:

1. In the Applications window, double-click the trinidad-config.xml file. By default,this file is in the Web Content/WEB-INF node.

2. In the source editor, write entries to specify the value of the <skin-family> elementand, optionally, the <skin-version> element as shown in Example 12-3.

12.4.2 What Happens When You Apply an ADF Skin to an ApplicationThe values that you specify for the <skin-family> element and, optionally, the <skin-version> element in the trinidad-config.xml file determine the ADF skin that the webapplication uses at runtime, as shown in Example 12-3.

Example 12-3 trinidad-config.xml File

<?xml version="1.0" encoding="windows-1252"?><trinidad-config xmlns="http://myfaces.apache.org/trinidad/config"> <skin-family>skyros</skin-family> <skin-version>v1</skin-version></trinidad-config>

12.5 Applying an ADF Skin to a Running Web ApplicationUsing Java Management Extensions (JMX), you can apply an ADF skin that ispackaged in an ADF Library JAR to a web application without having to restart theapplication.To do this, you must configure the web application's source files, as described in Howto Configure your Web Application to Accept an Updated ADF Skin. You then useJDeveloper to connect to the MBean server and deploy the ADF Library JARcontaining the ADF skin(s). See How to Deploy an ADF Library JAR to an MBeanServer. This makes all ADF skins contained in the ADF Library JAR available to theweb application.

12.5.1 How to Configure your Web Application to Accept an UpdatedADF Skin

You make the following changes to the web application's ViewController project inJDeveloper so that the application can apply a new ADF skin deployed by a MBeanserver without requiring a restart of the web application:

• Select the Enable Runtime Skin Updates checkbox in the ADF View page of theapplication's ViewController project

Chapter 12Applying an ADF Skin to a Running Web Application

12-7

• Add ADF Faces JMX Runtime 11 to the application's classpath

• (Optional) Add a context initialization parameter to the application's web.xml file

The context initialization parameter enables you to specify a user friendly name toidentify the web application rather than use the application's context root.

Note:

The web application must be deployed in an exploded format, as is the casewhen you run the application in the Integrated WebLogic Server.

To configure your web application to accept an updated ADF skin:

1. In JDeveloper's Applications window, select the ViewController project.

2. From the main menu, choose Application > Project Properties.

3. In the Project Properties dialog, select the ADF View page and then select theEnable Runtime Skin Updates checkbox.

4. Select the Libraries and Classpath page and verify that ADF Faces JMX Runtime11 appears in the Classpath Entries list. If it is not, click Add Library.

5. In the Add Library dialog, select ADF Faces JMX Runtime 11 and click OK.

6. Click OK.

7. Optionally, in the Applications window, double-click the web.xml file located in theWEB-INF directory and add a context initialization parameter where you canspecify an easy to remember name for your application. Otherwise, the defaultbehavior is to use the context root of the application.

In the overview editor, click the Application navigation tab and then click the Addicon next to the Context Initialization Parameters table to add an entry for theoracle.adf.view.rich.SKINNING_MBEAN_NAME parameter and set its value to a namethat you will use to identify the web application to the MBean server.

12.5.2 How to Deploy an ADF Library JAR to an MBean ServerYou deploy the ADF Library JAR that packages the ADF skin(s) to the MBean server.For information about how to create an ADF Library JAR file deployment profile topackage the ADF skin(s), see How to Package an ADF Skin into an ADF Library JAR.

To deploy an ADF Library JAR to an MBean Server:

1. In the Applications window, right-click the project that contains the ADF skin(s) andchoose Deploy > deployment, where deployment is the name of the ADF LibraryJAR file deployment profile.

2. In the Deployment Action page, select Deploy to ADF Skin Managed Bean andthen click Next.

3. In the Skin Connection page, choose the appropriate option:

• Click Add to create a new connection to the MBean server and go to Step 4.

• Choose an existing connection from the Connection dropdown list and go toStep 5.


12-8

4. In the Create JMX Connection dialog, complete the fields to connect to the MBeanserver:

• Connection Name: Enter a name for the connection. The connection namemust be a valid Java identifier, and as the name and connection are globalacross your installation, choose an appropriate and unique name.

• Server Type: The default of Weblogic Server is preselected for connectionswhere you deploy to an ADF Skin Managed Bean.

• Username: Enter the user name to be authorized for access to the MBeanserver.

• Password: Enter the password to be associated with the specified user name.An asterisk (*) appears for each character you type in this field.

• Protocol: JDeveloper uses the t3 protocol to communicate with the MBeanserver.

• Hostname: Enter a value to identify the machine running the MBean server.Use an IP address or a host name that can be resolved by TCP/IP, forexample if the MBean server is on the local machine, use localhost, or127.0.0.1.

• Port: Enter the listen port for the MBean server. The default is whatever thedefault port number of the Integrated Weblogic Server is (often 7101).

• URL Provider Path: Enter the absolute JNDI name of the MBean server. Itmust start with /jndi/ and be followed by one of:

– weblogic.management.mbeanservers.domainruntime

– weblogic.management.mbeanservers.runtime

– weblogic.management.mbeanservers.edit

• Server Install Location: Displays the server install location.

• Test Connection: Click to test the connection.

• Status: A Success! message indicates that JDeveloper has been able toconnect to the MBean server. Any other message indicates that theconnection has failed. Amongst the things you should check before trying TestConnection again are:

– Whether the network is working correctly when the MBean server is notlocal.

– The values entered in this dialog.

5. In the Application Name field, select the name of the web application that youwant to deploy the ADF Library JAR containing the ADF skin(s) to. Click FindRunning Applications to retrieve the list of available applications and to makesure that the application is running.

The name of the application's root context appears unless you specified the nameof the application to be the value that you entered for theoracle.adf.view.rich.SKINNING_MBEAN_NAME parameter, as described in How toConfigure your Web Application to Accept an Updated ADF Skin.

6. Click Next and then click Finish.


12-9

12.5.3 What Happens When You Apply an ADF Skin to a RunningApplication

JDeveloper deploys the ADF Library JAR containing the ADF skin(s) to the webapplication. This ADF Library JAR contains the ADF skin and other associated files(for example, any images that the ADF skin requires). For information about thecontents of the ADF Library JAR, see What Happens When You Package an ADFSkin into an ADF Library JAR. The ADF skins are installed in the root directory of theweb application. The trinidad-skins.xml file of the web application is updated toreference the newly-added ADF skins.

To make the web application use the newly-available ADF skin, you need to updatethe value that the trinidad-config.xml file's <skin-family> element references. You cando this manually, as described in How to Apply an ADF Skin to an Application, or youcan specify an EL expression for the element that updates the value programmatically.For information about this latter option, see Customizing the Appearance Using Stylesand Skins in Developing Web User Interfaces with Oracle ADF Faces.


12-10

13Advanced Topics

The ADF skinning framework supports a number of ways to write URLs that refer toresources in an ADF skin file, a number of configuration files, ready-to-use ADF skins,and options to version ADF skins.This chapter includes the following sections:

• Referring to URLs in an ADF Skin's CSS File

• Configuration Files for an ADF Skin

• ADF Skins Provided by Oracle ADF

• Versioning ADF Skins

13.1 Referring to URLs in an ADF Skin's CSS FileAn ADF skin's CSS file typically uses a URL to refer to a resource that is external tothe file. For example, an image that an application uses to render with an errormessage. You can refer to a URL from an ADF skin's CSS file in a number of differentformats.The supported formats are:

• Absolute

You specify the complete URL to the resource. For example, a URL in thefollowing format:

http://www.mycompany.com/WebApp/Skin/skin1/img/errorIcon.gif

• Relative

You can specify a relative URL if the URL does not start with / and no protocol ispresent. A relative URL is based on the location of the ADF skin's CSS file. Forexample, if the ADF skin's CSS file directory is WebApp/Skin/skin1/ and thespecified URL is img/errorIcon.gif, the final URL is /WebApp/Skin/mySkin/img/errorIcon.gif

• Context relative

This format of URL is resolved relative to the context root of your web application.You start a context relative root with /. For example, if the context relative root of aweb application is:

/WebApp

and the specified URL is:

/img/errorIcon.gif

the resulting URL is:

/WebApp/img/errorIcon.gif

• Server relative

13-1

A server relative URL is resolved relative to the web server. This differs to thecontext relative URL in that it allows you reference a resource located in anotherapplication on the same web server. You specify the start of the URL using //. Forexample, write a URL in the following format:

//WebApp/Skin/mySkin/img/errorIcon.gif

The format of URL that you use may be important if you create a Java Archive (JAR)file to package and distribute your ADF skin and its associated files. See Packagingan ADF Skin into an ADF Library JAR.

13.2 Configuration Files for an ADF SkinADF configuration files let you configure a variety of options for ADF skins, such as theskin your application uses or configure parameters that facilitate testing anddevelopment.The following list describes the configuration files associated with the project for anADF skin. You modify values in these files while you develop your ADF skin or whenyou finish development and want to apply the finished ADF skin to an application.

• trinidad-skins.xml

This file registers the ADF skins that you create, as described in Creating an ADFSkin File. The following example demonstrates how to register a number of ADFskins that extends from a sample of the ADF skins described in Table 13-1.

<skin> <id>yourSkin.desktop</id> <family>yourSkinFamily</family> <extends>alta-v1.desktop</extends> ...</skin> <skin> <id>yourSkin.desktop</id> <family>yourSkinFamily</family> <extends>skyros-v1.desktop</extends> ...</skin>

For information about this file, see Configuration in trinidad-skins.xml inDeveloping Web User Interfaces with Oracle ADF Faces.

• trinidad-config.xml

You configure the <skin-family> element in this configuration file to tell theapplication what ADF skin to use, as described in Applying an ADF Skin to YourWeb Application. The following example demonstrates how to configure your webapplication to use some of the ADF skins listed in Table 13-1.

<skin-family>alta</skin-family> <skin-version>v1<skin-version> <!-- Use the following value in the trinidad-config.xml file if you want your

Chapter 13Configuration Files for an ADF Skin

13-2

application to use the skyros skin. --><skin-family>skyros</skin-family> <skin-version>v1<skin-version>

For information about this file, see Configuration in trinidad-config.xml inDeveloping Web User Interfaces with Oracle ADF Faces.

• web.xml

You can configure context initialization parameters in this file to facilitate thedevelopment and testing of your ADF skin, as described in Testing Changes inYour ADF Skin . You can also configure a context initialization parameter(org.apache.myfaces.trinidad.skin.MAX_SKINS_CACHED) to specify the maximumnumber of unique ADF skins for which you store information in memory about thegenerated CSS files. Using this context initialization parameter can help maintainthe performance of your application if you use many different skins.

For information about the web.xml file and context initialization parameters, see Configuration in web.xml in Developing Web User Interfaces with Oracle ADFFaces.

13.3 ADF Skins Provided by Oracle ADFOracle ADF provides a number of ADF skins from which you can extend when youcreate a new ADF skin. These ADF skins provide a base from which you can startdevelopment of your own ADF skin.Table 13-1 describes the differences between each of these ADF skins. The BaseSkin page of the Create ADF Skin dialog that appears when you create an ADF skin,as described in Creating an ADF Skin File, recommends the appropriate ADF skin toextend from.

You can apply any of the ADF skins listed in Table 13-1 to your web application. See Configuration Files for an ADF Skin. For a diagram that illustrates the inheritancerelationship between the ADF skins, see Inheritance Relationship of the ADF SkinsProvided by Oracle ADF .

Table 13-1 ADF Skins Provided by Oracle ADF

ADF Skin Description

simple Contains only minimal formatting.

skyros-v1 Extends the simple skin. It provides a colorful look and feel to applications that useit.

alta-v1 The alta-v1 skin is the skin that permits web applications to take advantage of theOracle Alta UI system. Use this skin or extend from it if you want your webapplication to take advantage of the enhancements introduced in the Oracle Alta UIsystem. The alta-v1 skin is the default skin for web applications that you createusing this release.

For information about the Oracle Alta UI system, see http://www.oracle.com/webfolder/ux/middleware/alta/index.html.

Chapter 13ADF Skins Provided by Oracle ADF

13-3



13.4 Versioning ADF SkinsYou can specify version numbers for your ADF skins in the trinidad-skins.xml fileusing the <version> element. Use this optional capability if you want to distinguishbetween ADF skins that have the same value for the <family> element in the trinidad-skins.xml file.Note that when you configure an application to use a particular ADF skin, you do so byspecifying values in the trinidad-config.xml file, as described in section Applying anADF Skin to Your Web Application.

13.4.1 How to Version an ADF SkinYou specify a version for your ADF skin by entering a value for the <version> elementin the trinidad-skins.xml file.

To version an ADF skin:

1. In the Applications window, double-click the trinidad-skins.xml file. By default, thisis in the Web Content/WEB-INF node.

2. In the Structure window, right-click the skin node for the ADF skin that you want toversion and choose Insert inside skin > version.

3. In the Insert version dialog, select true from the default list if you want yourapplication to use this version of the ADF skin when no value is specified in the<skin-version> element of the trinidad-config.xml file, as described in Applying anADF Skin to Your Web Application.

4. Enter a value in the name field. For example, enter v1 if this is the first version ofthe ADF skin.

5. Click OK.

13.4.2 What Happens When You Version ADF SkinsExample 13-1 shows an example trinidad-skins.xml that references three ADF skins(skin1.desktop, skin2.desktop, and skin3.desktop). Each of these ADF skins have thesame value for the <family> element (test). The values for the child elements of the<version> elements distinguish between each of these ADF skins. At runtime, anapplication that specifies test as the value for the <skin-family> element in theapplication's trinidad-config.xml file uses skin1.desktop because this ADF skin isconfigured as the default skin in the trinidad-skins.xml file (<default>true</default>).You can override this behavior by specifying a value for the <skin-version> element inthe trinidad-config.xml file, as described in Applying an ADF Skin to Your WebApplication. For example, if you specify v2 as a value for the <skin-version> element inthe trinidad-config.xml file, the application uses skin2.desktop instead ofskin1.desktop that is defined as the default in the trinidad-skins.xml file.

If you do not specify the skin version to pick (using the <skin-version> element in thetrinidad-config.xml file), then the application uses the skin that is defined as thedefault using the <default>true</default> element in the trinidad-skins.xml file. If youdo not specify a default skin, the application uses the last ADF skin defined in thetrinidad-skins.xml file. In Example 13-1, the last ADF skin to be defined isskin3.desktop.

Chapter 13Versioning ADF Skins

13-4

Example 13-1 trinidad-skins.xml File with Versioned ADF Skin Files

<?xml version="1.0" encoding="windows-1252"?><skins xmlns="http://myfaces.apache.org/trinidad/skin"> <skin> <id>skin1.desktop</id> <family>test</family> <extends>skyros-v1.desktop</extends> <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id> <style-sheet-name>skins/skin1/skin1.css</style-sheet-name> <version> <default>true</default> <name>v1</name> </version> </skin> <skin> <id>skin2.desktop</id> <family>test</family> <extends>skin1.desktop</extends> <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id> <style-sheet-name>skins/skin2/skin2.css</style-sheet-name> <version> <name>v2</name> </version> </skin> <skin> <id>skin3.desktop</id> <family>test</family> <extends>skin2.desktop</extends> <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id> <style-sheet-name>skins/skin3/skin3.css</style-sheet-name> <version> <name>v3</name> </version> </skin></skins>

Chapter 13Versioning ADF Skins

13-5

Chapter 13

Versioning ADF Skins

13-6

Developing ADF Skins · 4.3.2 Interactive Preview in the Selectors Editor 4-7 4.4 Working with the...

Documents

Transcript of Developing ADF Skins · 4.3.2 Interactive Preview in the Selectors Editor 4-7 4.4 Working with the...