5 Working with Component-Specific Selectors

This chapter describes how to change the appearance of ADF Faces and ADF Data Visualization components by specifying properties for the selectors that the ADF skinning framework exposes for these components.

5.1 About Working with Component-Specific Selectors

You customize the appearance of an ADF Faces component or ADF Data Visualization component by defining style properties for the selectors that the component exposes. To achieve the appearance you want, you need to become familiar with the component-specific selectors that the ADF Faces and ADF Data Visualization components expose, plus the global selector aliases and descendant selectors that a component-specific selector may reference. The ADF skins that you extend from when you create an ADF skin define many global selector aliases and descendant selectors. You also need to become familiar with the component itself and how it relates to other components. For example, customizing the appearance of the ADF Faces table component shown in Figure 5-1 requires you to define style properties for selectors exposed by the af:column component in addition to selectors exposed by the ADF Faces table component. You may also need to modify the style properties for one or more of the icon or message global selector aliases that the ADF skin you extend defines.

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 to appear in the page. For more information, see Chapter 7, "Working With Text in an ADF Skin."

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

You can change the runtime appearance of ADF Faces components by editing the properties that each ADF Faces skin selector exposes. The number of selectors that an ADF Faces component exposes varies by component. For example, the ADF Faces components, af:image and af:popup, expose one selector each. In contrast, the ADF Faces component, af:panelHeader, exposes a variety of selectors that enable you to change the appearance of different parts of the user interface of that component. There are, for example, selectors that allow you to change the af:panelHeader component's instruction text, help icons, and titles.

The process to follow to change the runtime appearance of an ADF Faces component is the same for each component; the only difference is the number of selectors that each ADF Faces component exposes. Figure 5-2 and Figure 5-3 take the goButton component as an example and illustrate how you can customize the appearance of this component using pseudo-elements and the component's selector. Figure 5-2 shows the application of the default ADF Faces' fusion skin on the goButton component and the component icon.

Figure 5-2 goButton Component Default Appearance with Fusion ADF Skin

Figure 5-3 shows the appearance of the component after you set values for the following pseudo-elements on the component's selector:

You can change the runtime appearance of ADF Data Visualization components by editing the properties that each ADF Data Visualization component selector exposes. The number of selectors exposed by an ADF Data Visualization component varies by component.

Figure 5-4 shows an ADF skin with the nodes expanded to show the selectors that you can customize for the ADF Data Visualization gauge component.

Figure 5-4 ADF Data Visualization Component Selectors

You customize the appearance of ADF Data Visualization components by defining style properties for the selectors that each ADF Data Visualization component exposes. Using the tools provided by the ADF Skin Editor, you customize the appearance of the ADF Data Visualization components. For more information, see Chapter 3, "Working with the Oracle ADF Skin Editor."

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

Figure 5-5 ADF Data Visualization pivotTable Component

Many ADF Data Visualization component selectors, such as the selectors for the graph and hierarchyViewer components, expose pseudo-elements for which you configure ADF skin properties. These ADF skin properties modify the appearance of the area specified by the pseudo-element. The characters -tr- preface the names of ADF skin properties. For example, Figure 5-6 shows the properties of the hierarchy viewer's lateral-navigation-button selector, all of which are prefaced by -tr-.

In contrast, the gantt component's summary-task-left selector, shown in Figure 5-7, exposes only two ADF skin properties (-tr-rule-ref and -tr-inhibit-) as the majority of the properties that you configure for this selector are CSS properties.

5.4 Changing a Component-Specific Selector

The process to change a component-specific selector is the same for both the ADF Faces and ADF Data Visualization components. In the Selector Tree, you expand the Faces Components Selectors or Data Visualization Selectors node to select the selector of the component you want to modify. You then set values for this selector using the Property Inspector. You can also set properties for any pseudo-elements, component style classes, component selector aliases, or descendant selectors that the selector you select references. In addition, you can add pseudo-classes that the component-specific supports. For more information about pseudo-classes, see Section 2.2, "Pseudo-Classes in the ADF Skinning Framework."Figure 5-8 shows a view of the skin selector for the ADF Faces table component in the Selector Tree with the different items that you can configure for this skin selector.

Figure 5-8 Selector for the table Component

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

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

5.4.1 How to Change a Component-Specific Selector

You change a component-specific selector by selecting the selector in the Selector Tree and setting values for the selector, its pseudo-elements, or descendant selectors in the Property Inspector. In addition, you can add a pseudo-class if the component-specific selector supports one.

To change a component-specific selector:

In the Selector Tree of the visual editor, choose the appropriate option:

Expand the Faces Component Selectors node if you want change a selector for an ADF Faces component.

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

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

In the Property Inspector, specify values for the properties that the selector you selected in step 1 supports.

For example, in the Common section of the Property Inspector, specify values for the following attributes:

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

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

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

5.4.2 What Happens When You Change a Component-Specific Selector

The visual editor displays the changes that you make to the selector after you click the Refresh icon in the Preview Pane. If you add a pseudo-class to the selector, the Preview Pane also displays an entry for the selector with the added pseudo-class. For example, Figure 5-10 shows an entry for a selector with the :hover pseudo-class added.

Note:

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

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

When a web application uses an ADF skin that contains the values shown in Example 5-1, header rows in the columns of a table rendered by the ADF Faces table component appear as illustrated by Figure 5-11 where the table uses a skin that extends the simple skin.

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

5.5 Configuring ADF Skin Properties to Apply to Messages

You can apply styles to ADF Faces input components based on whether or not the input components have certain types of message associated with them. When a message of a particular type is added to a component, the styles of that component are automatically modified to reflect the new status. If you do not define styles for the type of message in question, the component uses the default styles defined in the ADF skin.

The types of message property are:

:fatal

:error

:warning

:confirmation

:info

Figure 5-12 shows an inputText component rendered using the simple ADF skin. In Figure 5-12, the simple ADF skin defines style values for the :warning message property to apply to the inputText component when an end user enters values that generate a warning.

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

The ADF skinning framework defines a number of global selector aliases that define style properties to apply to messages. Figure 5-14 shows a list of global selector aliases under the Message node in the Selector Tree. The Preview Pane, on the right of Figure 5-14, shows how the style properties defined for the global selector alias currently selected in the Selector Tree render the component selected from the View as list.

Figure 5-14 Global Selector Aliases for Messages

You can customize the global selector aliases that the ADF skinning framework provides for messages by defining style properties in your ADF skin. The style properties that you define for the global selector alias affect all ADF Faces components that reference the global selector alias. For example, if you change the border color for the global selector alias shown in Figure 5-14 to green, all the ADF Faces components shown in the View as list render with a border that is green. For more information about global selector aliases, see Chapter 8, "Working With Global Selector Aliases."

For more information about configuring messages for ADF Faces components, see the "Displaying Tips, Messages, and Help" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

5.5.1 How to Configure an ADF Skin Property to Apply to a Message

You add a pseudo-class to the component's selector for the message type that you want to configure. You then define style properties for the pseudo-class using the Property Inspector.

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

In the Selector Tree of the visual editor, expand the Faces Component Selectors section and select the selector for the ADF Faces component for which you want to configure the style properties to apply to a message.

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

Click the Add Pseudo- Class icon to display a list of the available pseudo-classes for the selector that you selected in step 1.

Select the pseudo-class that corresponds to the message for which you want to configure style properties. The following pseudo-classes are available for the ADF Faces components:

fatal

error

warning

confirmation

info

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

5.5.2 What Happens When You Configure an ADF Skin Property to Apply to a Message

The visual editor writes the values that you specify for the selector's pseudo-class in the Property Inspector to the source file for the ADF skin. For example, assume that you set the value of the Border Color property to Red for the af|inputText selector's error pseudo-class. Figure 5-15 shows the change that appears in the source file and in the Preview Pane of the ADF skin.

If you want to define style properties to appear when the component displays an error message, use the error pseudo class. For example, set the content pseudo element's background color property for the af:inputText component's to Red when an error occurs as follows:

af|inputText::content:error
{
background-color:Red
}

5.5.3 What You May Need to Know About Configuring an ADF Skin Property to Apply to a Message

The visual editor does not support the addition or the configuration of the pseudo-classes for message types to a selector's pseudo-element. Use the source editor for the ADF skin if you want to add a pseudo-class for a message type to a selector's pseudo-element. Example 5-2 demonstrates the syntax to write if you want to define red as the background color for the af|inputText selector's content pseudo-element

Example 5-2 Adding a Message Pseudo-Class to a Pseudo-Element

af|inputText::content:error
{
background-color:Red
}

5.6 Applying Themes to ADF Faces Components

Themes are a way of implementing a look and feel at a component level. A theme's purpose is to provides a consistent look and feel across multiple components for a portion of a page. A common usage for themes is in a JSF page template where certain areas have a distinct look. For example, a page may have a branding area at the top with a dark background and light text, a navigation component with a lighter background, and a main content area with a light background.

A component that sets a theme exposes that theme to its child components and therefore the theme is inherited. Themes can be set (started or changed) by the af:document and af:decorativeBox components.

The Fusion ADF skins support the following themes:

dark

medium

light

None (default)

You can also create your own theme by entering syntax similar to the following in the source file of an ADF skin:

af|document[theme=UserCreated] {}

Figure 5-16 shows how the visual editor renders tabs where you can configure style properties for each theme provided by the Fusion ADF skins in addition to a user-created theme.

In addition to the themes listed previously, there is one other theme (contentBody) that the af|decorativeBox selector uses, as shown in Figure 5-18. The af:decorativeBox component is the only component that ever renders using the style properties defined for this theme.

Figure 5-18 Themes for the decorativeBox Selector

In your application, you start the theme by specifying it as an attribute of the af:document component in the JSF page, as shown in the following example:

By default, themes are not set for components or their child components. Because themes are inherited, the following values are supported when a component has a theme attribute that is not set:

not given - If no theme is given, the theme is inherited, as in <af:decorativeBox>...

#{null}- The theme is inherited; same as not given.

inherit - The theme is inherited; same as null.

default - The theme is removed for the component and its child components.

empty string - If the theme is set to a blank string, it has the same behavior as default. For example, <af:decorativeBox theme=""> will remove the theme for the component and its child components.

Because the themes are added to every HTML element of a component that supports themes and that has style classes, there is no need for containment-style CSS selectors for themes. With the exception of :ltr and :rtl, all theme selectors should always appear on the last element of the selector. For example, the selector to apply a dark theme to each step of an af:breadCrumbs component is:

af|breadCrumbs::step:disabled[theme="dark"] {
color:#FFFFFF;
}

Color incompatibility may occur if a component sets its background color to a color that is not compatible with its encompassing theme color. For example, if a panelHeader component is placed in a dark theme, the CSS styles inside the panelHeader component will set its component background to a light color without changing its foreground color accordingly. The result is a component with a light foreground on a light background. Many other components also set their foreground color to a light color when placed in a dark theme.

If color incompatibility occurs, you can resolve color incompatibility between parent and child components by setting a value for the -tr-children-theme property. For components that do not have a parent-child relationship, you can manually set the component's theme color to a color that is compatible with the surrounding theme color. You do this by inserting the panelGroupLayout or panelStretchLayout component inside the component and by setting the panelGroupLayout or panelStretchLayout theme to a compatible color.

5.6.1 How to Enable Themes for Components

You enable themes on a per-component basis in an ADF skin. Enabling themes on a per-component basis means that you do not generate unnecessary HTML attributes that the ADF skin will not use.

To enable themes for components:

In the source editor, enter syntax for the component's selector to enable themes for the component in the ADF skin. For example, to enable theme support in an ADF skin for the outputLabel component, enter the following:

af|outputLabel {
-tr-enable-themes: true;
}

5.6.2 How to Set Theme Properties for a Component in an ADF Skin

You set theme properties for a component using the tab in the visual editor that corresponds to the theme you want to configure.

To set theme properties for a component in an ADF skin:

In the Selector Tree of the visual editor, expand the appropriate node for which you want to set theme properties.

You can configure items under the Style Classes, Faces Component Selectors, Data Visualization Component Selectors, and Other nodes.

Click the tab that corresponds to the theme for which you want to set properties.

For example, if you want to set a property for the dark theme, click Dark Theme, as shown in Figure 5-19.

Figure 5-19 Dark Theme in Visual Editor

In the Property Inspector, set values for the properties that you want to configure for the selected theme.

Example 5-3 shows the entry that appears in the source file of an ADF skin if you set the background-color property of the af:panelTabbed component's dark theme to Red.

Example 5-3 Defining a Theme for a Component in an ADF Skin

af|panelTabbed[theme="dark"] {
background-color: Red;
}

5.6.3 How to Prevent a Component Inheriting a Theme from a Parent Component

If you do not want a child component to inherit modifications made to a parent component in a JSF page, set a value for the -tr-children-theme property in the source file of the ADF skin. For example, you do not want the af:panelTabbed child component to inherit the dark theme defined for the af:document parent component in the JSF page. Set the -tr-children-theme property in the source file for the ADF skin as shown in Example 5-4.

Note that if you do not want a component to inherit modifications for a specific theme, you must specify the themed version. In Example 5-4, this is the dark theme. If you wanted to prevent the inheritance of modifications for the medium theme, you also set the -tr-children-theme property in the source file for the medium theme.

Example 5-4 Child Component Preventing Inheritance of a Theme from a Parent Component

af|panelTabbed[theme="dark"] {
-tr-children-theme: default;
}

5.7 Configuring an ADF Skin for Accessibility

Oracle ADF provides application accessibility support to make applications developed using ADF Faces components usable for persons with disabilities. You can define style properties in your ADF skin specifically for persons with disabilities as part of efforts to make your application accessible. You preface these style 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 the trinidad-config.xml file. For more information about the trinidad-config.xml file, Section 11.3, "Configuration Files for an ADF Skin."

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

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