28 Customizing the Appearance Using Styles and Skins

This chapter describes how you customize the appearance of your application by changing component style attributes or by using ADF skins.

This chapter includes the following sections:

28.1 About Customizing the Appearance Using Styles and Skins

You can customize the appearance of ADF Faces and ADF Data Visualization components using an ADF skin that you apply to the application or by applying CSS style properties directly to an ADF Faces or ADF DVT component if the component exposes a style-related property (styleClass or inlineStyle). Choosing the latter option means that you override style properties defined in your application's ADF skin for the component. You might do this when you want to change the style for an instance of a component on a page rather than for all components throughout the application or you want to programmatically set styles conditionally. For example, you want to display text in red only under certain conditions. For more information, see Section 28.2, "Changing the Style Properties of a Component."

An ADF skin is a type of CSS file where you define CSS style properties based on the Cascading Style Sheet (CSS) specification for the component for which you want to customize the appearance. The ADF skin defines rules that determine how to apply CSS style properties to specific components or groups of components. The end user's browser interprets these rules and overrides the browser's default settings. Figure 28-1 and Figure 28-2 demonstrate the result that applying ADF skins can have on the appearance of the ADF Faces and ADF Data Visualization components that appear in your application. Figure 28-1 shows a page from the File Explorer application with the simple ADF skin applied.

Figure 28-1 Index Page Using the Simple Skin

Simple Skin in the File Explorer Application

Figure 28-2 shows the same page from the same application with the fusion ADF skin applied.

Figure 28-2 Index Page Using the Fusion ADF Skin

Index Page Using the Fusion ADF Skin

The File Explorer application provides several ADF skins to customize the appearance of the application. You can view the source files for these ADF skins and the File Explorer application. For more information, see Section 2.1, "About the ADF Faces Demonstration Application."

It is beyond the scope of this guide to explain the concepts of CSS. For extensive information on style sheets, including the official specification, visit the World Wide Web Consortium's web site at:

http://www.w3.org/

You can use the ADF Skin Editor to create ADF skins for your application. It is beyond the scope of this guide to describe how to create or apply ADF skins to your application. For more information, see the Oracle Fusion Middleware Skin Editor User's Guide for Oracle Application Development Framework.

If you create multiple ADF skins, you can configure your application so that end users choose the ADF skin that they want the application to use. For more information, see Section 28.3, "Enabling End Users to Change an Application's ADF Skin."

28.1.1 Customizing the Appearance Use Cases and Examples

You can customize an ADF skin to serve a number of purposes. For example, you might define properties in an ADF skin so that the application highlights a data row rendered by an ADF Faces table component after an end user selects it to provide feedback, as illustrated in Figure 28-3.

Figure 28-3 ADF Skin Properties in an ADF Table Component

ADF Skin Properties in an ADF Table Component

Use ADF skin properties to define behavior and appearance that you cannot specify using only CSS or that is dependent on component properties and, as a result, is not feasible to define using CSS. For example, ADF Faces supports animation in browsers where CSS 3 animations are not available. If you want to configure the duration of an animation, use an ADF skin property to do so. Example 28-1 shows how an ADF skin property defines the duration that an ADF Faces carousel component displays the spin animation to be 500 milliseconds long.

Example 28-1 Using an ADF Skin Property to Specify Length of Spin Animation

af|carousel {
  -tr-spin-animation-duration: 500;
}

28.1.2 Additional Functionality for Customizing the Appearance

You may find it helpful to understand other ADF Faces features and non-ADF Faces features before you decide to customize the appearance of your application. The following links provide more information that may be useful to know:

  • Using parameters in text: You can use the ADF Faces EL format tags if you want the text displayed in a component to contain parameters that will resolve at runtime. For more information, see Section 3.5.2, "How to Use the EL Format Tags."

  • Internationalization and localization: The ADF skin that you create to apply to your application can be customized as part of a process to internationalize and localize ADF Faces pages. For more information about this process, see Chapter 29, "Internationalizing and Localizing Pages."

  • Accessibility: The ADF skin that you create to apply to your application can be customized as part of a process to make your ADF Faces pages accessible. For more information about this process, see Chapter 30, "Developing Accessible ADF Faces Pages."

28.2 Changing the Style Properties of a Component

You can adjust the look and feel of any component at design time by changing the component's style-related properties, inlineStyle and styleClass, both of which render on the root DOM element. Any style-related property (inlineStyle or styleClass) you specify at design time overrides the comparable style specified in the application's ADF skin for that particular instance of the component. Any value you specify for a component's inlineStyle property overrides a value set for the styleClass attribute.

The inlineStyle attribute is a semicolon-delimited string of CSS styles that can set individual attributes, for example, background-color:red; color:blue; font-style:italic; padding:3px. The styleClass attribute is a CSS style class selector used to group a set of inline styles. The style classes can be defined using an ADF public style class, for example, .AFInstructionText, sets all properties for the text displayed in an af:outputText component.

Given a specific selector, you can get style properties for a custom component by creating a class for a renderer. For more information, see Section 31.4.7, "How to Create a Class for a Renderer."

WARNING:

Do not use styles to achieve stretching of components. Using styles to achieve stretching is not declarative and, in many cases, will result in inconsistent behavior across different web browsers. Instead, you can use the geometry management provided by the ADF Faces framework to achieve component stretching. For more information about layouts and stretching, see Section 9.2.1, "Geometry Management and Component Stretching."

28.2.1 How to Set an Inline Style

Set an inline style for a component by defining the inlineStyle attribute. You can use inline style to specify the style of a component for that instance of the component. For more information, see Section 9.3, "Arranging Contents to Stretch Across a Page."

Before you begin:

It may be helpful to have an understanding of how the inlineStyle attribute relates to other attributes. For more information, see Section 28.2, "Changing the Style Properties of a Component."

You may also find it helpful to understand functionality that can be added using other ADF Faces features. For more information, see Section 28.1.2, "Additional Functionality for Customizing the Appearance."

To set an inline style:

  1. Set the inlineStyle attribute of the component to the inline style you want to use.

  2. If you use the Property Inspector to set a style, you can select the style features you want from dropdown lists, as shown in Figure 28-4.

    Figure 28-4 Setting an inlineStyle Attribute

    Setting an inlineStyle Attribute

    JDeveloper adds the corresponding code for the component to the JSF page. Example 28-2 shows the source for an af:outputText component with an inlineStyle attribute.

    Example 28-2 InlineStyle in the Page Source

    <af:outputText value="outputText1"
                   inlineStyle="color:Red; text-decoration:overline;"/>
    
  3. You can use an EL expression for the inlineStyle attribute itself to conditionally set inline style attributes. For example, if you want the date to be displayed in red when an action has not yet been completed, you could use the code similar to that in Example 28-3.

    Example 28-3 EL Expression Used to Set an inlineStyle Attribute

    <af:outputText value="#{row.assignedDate eq  
        null?res['srsearch.unassignedMessage']:row.assignedDate}"
                  inlineStyle="#{row.assignedDate eq null?'color:rgb(255,0,0);':''}"/>
    
  4. The ADF Faces component may have other style attributes not available for styling that do not register on the root DOM element. For example, for the af:inputText component, set the text of the element using the contentStyle property, as shown in Example 28-4.

Example 28-4 Using the contentStyle Property

<af:inputText value="outputText1"
          contentStyle="color:Red;"/>

28.2.2 How to Set a Style Class

You can define the style for a component using a style class. You create a style class to group a set of inline styles. Use the styleClass attribute to reference the style class.

Before you begin:

It may be helpful to have an understanding of how the styleClass attribute relates to other attributes. For more information, see Section 28.2, "Changing the Style Properties of a Component."

You may also find it helpful to understand functionality that can be added using other ADF Faces features. For more information, see Section 28.1.2, "Additional Functionality for Customizing the Appearance."

To set a style using a style class:

  1. Set the styleClass attribute of the component to the style class you want to use.

    Example 28-5 shows an example of a style class being used in the page source.

    Example 28-5 Page Source for Using a Style Class

    <af:outputText value="Text with a style class" 
                   styleClass="overdue"/>
    
  2. You can also use EL expressions for the styleClass attribute to conditionally set style attributes. For example, if you want the date to be displayed in red when an action has not yet been completed, you could use code similar to that in Example 28-3.

28.3 Enabling End Users to Change an Application's ADF Skin

You can configure your application to enable end users select an alternative ADF skin. You might configure this functionality when you want end users to render the application's page using an ADF skin that is more suitable for their needs. For example, you want your application to use an ADF skin with features specific to a Japanese locale when a user's browser is Japanese. An alternative example is where you want your application to use an ADF skin that is configured to make your application's pages more accessible for users with disabilities.

Figure 28-5 shows how you might implement this functionality by configuring a component (for example, af:commandMenuItem) to allow end users to change the ADF skin the application uses at runtime. Configure the component on the JSF page to set a scope value that can later be evaluated by the skin-family property in the trinidad-config file.

Figure 28-5 Changing an Application's ADF Skin

Changing an Application’s ADF Skin

28.3.1 How to Enable End Users Change an Application's ADF Skin

You enable end users change an application's ADF skin by exposing a component that allows them to update the value the skin-family property in the trinidad-config file.

Before you begin:

It may be helpful to have an understanding of how the changes that you make can affect functionality. For more information, see Section 28.3, "Enabling End Users to Change an Application's ADF Skin."

You may also find it helpful to understand functionality that can be added using other ADF Faces features. For more information, see Section 28.1.2, "Additional Functionality for Customizing the Appearance."

To enable end users change an application's ADF skin:

  1. Open the main JSF page where you want to configure the component(s) that you use to set the skin family.

  2. Configure a number of components (for example, af:commandMenuItem components) that allow end users to choose one of a number of available ADF skins at runtime, as shown in Figure 28-5.

    Example 28-6 shows how you configure af:commandMenuItem components that allow end users to choose available ADF skins at runtime, as shown in Figure 28-5. Each af:commandMenuItem component specifies a value for the actionListener attribute. This attribute passes an actionEvent to a method (skinMenuAction) on a managed bean named skins if an end user clicks the menu item.

    Example 28-6 Using a Component to Set the Skin Family

    <af:menu text="Change Skin" id="skins" binding="#{backing_ChangeSkin.skins}">
            <af:commandMenuItem text="blafplus-rich" id="skin1"
                                binding="#{backing_ChangeSkin.skin1}" type="radio"
                                actionListener="#{skins.skinMenuAction}"
                                selected="#{skins.skinFamily}"/>
            <af:commandMenuItem id="skin2" text="blafplus-medium" type="radio"
                                actionListener="#{skins.skinMenuAction}"
                                selected="#{skins.skinFamily=='blafplus-medium'}"/>
            <af:commandMenuItem id="skin3" text="fusion" type="radio"
                                actionListener="#{skins.skinMenuAction}"
                                selected="#{skins.skinFamily=='fusion'}"/>
            <af:commandMenuItem id="skin4" text="fusion-projector" type="radio"
                                actionListener="#{skins.skinMenuAction}"
                                selected="#{skins.skinFamily=='fusion-projector'}"/>
            <af:commandMenuItem id="skin5" text="simple" type="radio"
                                actionListener="#{skins.skinMenuAction}"
                                selected="#{skins.skinFamily=='simple'}"/>
            <af:commandMenuItem id="skin6" text="skin1" type="radio"
                                actionListener="#{skins.skinMenuAction}"
                                selected="#{skins.skinFamily=='skin1'}"/>
        </af:menu>
    
  3. Write a method (for example, skinMenuAction) on a managed bean named skins to store the value of the ADF skin selected by the end user. Example 28-7 shows a method that takes the value the end user selected and uses it to set the value of skinFamily in a managed bean. The method in Example 28-7 also invokes a method to reload the page after it sets the value of skinFamily.

    Example 28-7 Managed Bean Method to Change ADF Skin

     public void skinMenuAction(ActionEvent ae)
     {
         RichCommandMenuItem menuItem = (RichCommandMenuItem)ae.getComponent();
         
         // Invoke another managed bean method to set the value of skinFamily
         setSkinFamily(menuItem.getText());
         
         // Invoke a method to reload the page. The application reloads the page
         // using the newly-selected ADF skin.
         reloadThePage();
     }
    
  4. In the Application Navigator, double-click the trinidad-config.xml file.

  5. In the trinidad-config.xml file, write an EL expression to dynamically evaluate the skin family:

    <skin-family>#{skins.skinFamily}</skin-family>

28.3.2 What Happens at Runtime: Changing an Application's ADF Skin

At runtime, the end user uses the component that you exposed to select another ADF skin. In our example, this is one of a number of af:commandMenuItem components. This component submits the value that the end user selected to a managed bean that, in turn, sets the value of a managed bean property (skinFamily). At runtime, the <skin-family> property in the trinidad-config file reads the value from the managed bean using an EL expression.