Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

19 Customizing the Appearance Using Styles and Skins

This chapter describes how to change the appearance of your application by changing style properties using Oracle ADF Faces skins and component style attributes.

This chapter includes the following sections:

19.1 Introduction to Skins, Style Selectors, and Style Properties

The default look and feel of ADF Faces components has been defined using BLAF Plus, a set of user interface standards for applications known as Oracle Browser Look and Feel. JDeveloper supports two options for applying style information to your ADF Faces components:

ADF Faces components delegate the functionality of the component to a component class, and the display of the component to a renderer. By default, all tags for ADF Faces combine the associated component class with an HTML renderer, and are part of the HTML render kit. HTML render kits are included with ADF Faces for display on both desktop and PDA. You cannot customize ADF Faces renderers. However, you can customize how components display using skins.

If you do not wish to change ADF Faces components throughout the entire application, you can choose to change the styles for the instance of a component on a page. You can also programmatically set styles conditionally. For example, you may want to display text in red only under certain conditions. For more information, see Section 19.4, "Changing the Style Properties of a Component".

It is beyond the scope of this guide to explain the concept of CSS. For extensive information on style sheets, including the official specification, visit the W3C web site at:

http://www.w3c.org/

19.1.1 Oracle ADF Faces Skins

A skin is a style sheet based on the CSS 3.0 syntax specified in one place for an entire application. Instead of providing a style sheet for each component, or inserting a style sheet on each page, you can create one skin for the entire application. Every component automatically uses the styles as described by the skin. No design-time code changes are required.

Oracle ADF Faces provides three skins for use in your applications:

  • blafplus-rich : Defines the default styles for ADF Faces components. This skin extends the blafplus-medium skin.

  • blafplus-medium : Provides a modest amount of styling. This style extends the simple skin.

  • simple : Contains only minimal formatting.

Skins allow you to globally change the appearance of ADF Faces components within an application. By default, ADF Faces applications use the blafplus-rich skin. Components in the visual editor, as well as in the web page, are displayed using the settings for this skin. Figure 19-1 shows the default blafplus-rich skin applied to the File Explorer Application index page.

Note:

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

Figure 19-1 Index Page Using the blafplus-rich Skin

Page with Oracle formatting.

ADF Faces also provides the simple skin, shown in Figure 19-2 as applied to the File Explorer Application index page.

Figure 19-2 Index Page Using the Simple Skin

Page with simple formatting.

Skins provide more options than setting standard CSS styles and layouts. The skin's CSS file is processed by the skin framework to extract skin properties and icons and register them with the Skin object. In the skin file, you can also do the following:

  • Define platform styles using @platform and browser styles using @agent.

    Set a platform-specific style with a value of windows, macos, linux, solaris, or pcc, and set a browser agent-specific style with a value of netscape, that is, mozilla, gecko, webkit (maps to Safari), or ice. In this example, the content area of the af:inputText component is set to the color pink for Internet Explorer, and set to gecko on Windows and Linux platforms:

    @platform window, linux {
      @agent ie, gecko {
       af|inputText::content {background-color:pink
       }
      }
    }
    
  • Define @accessibility-profile, which defines styles for high-contrast and large-fonts accessibility profile settings from the trinidad-config.xml file. The high-contrast value would be for cases where background and foreground colors need to be highly contrasted with each other. The large-fonts value would be 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.

    <!-- Enable both high-contrast and large-fonts content -->
      <accessibility-profile>high-contrast large-fonts</accessibility-profile>
    
  • Suppress skin styles with the -tr-inhibit skin property.

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

  • Merge styles with the -tr-rule-ref property.

    Create your own alias and combine it with other style selectors using the -tr-rule-ref property. For more information, see Section 19.3.5, "How to Create a Custom Alias".

  • Use the :rtl pseudo-class to create a style or icon definition when the browser is displaying a right-to-left language. For more information, see Section 19.1.2, "Skin Style Selectors".

During development, after you made changes to the skin, you can see your CSS changes without restarting the server by setting the web.xml file parameter org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION to true, as shown in Example 19-1. However, you must always restart the server to see icon and skin property changes.

Example 19-1 web.xml Parameter to Check Skin Changes

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

19.1.2 Skin Style Selectors

Style sheet rules include a style selector, which identifies an element, and a set of style properties, which describe the appearance of the components. ADF Faces components include two categories of skin style selectors:

  • Global selectors

    Global selectors determine the style properties for multiple ADF Faces components. If the global selector name ends in the :alias pseudo-class, then the selector is most likely included in other component-specific selectors and will affect the skin for more than one component. For example, most, if not all, components use the .AFDefaultFontFamily:alias definition to specify the font family. If your skin overrides this selector with a different font family, that change will affect all the components that have included it in their selector definition. Example 19-2 shows the global selector for the default font family for ADF Faces components in an application.

    Example 19-2 Global Selector for Default Font Family

    .AFDefaultFontFamily:alias {
           font-family: Tahoma, Verdana, Helvetica, sans-serif;
    }
    
  • Component selectors

    Component-specific selectors are selectors that can apply a skin to a particular ADF Faces component. Example 19-3 shows the selector set to red as the background color for the content area of the af:inputText component.

    Example 19-3 af:inputText Component Selector

    af|inputText::content {
             background-color: red;
    }
    

Each category may include one or more of these types of ADF Faces skin selectors:

  • Standard selectors

    Standard selectors are those that directly represent an element that can have styles applied to it. For example, af|body represents the af:body component. You can set CSS styles, properties, and icons for this type of element.

  • Selectors with pseudo-elements

    Pseudo-elements are used to denote a specific area of a component that can have styles applied. Pseudo-elements are denoted by a double colon followed by the portion of the component the selector represents. For example, af|chooseDate::days-row provides the styles and properties for the appearance of the dates within the calendar grid.

  • Icon selectors

    Some components render icons (<img> tags) within them using a set of base icons. These icons can have skins applied even though they are not rendered with CSS in the same way as the background-image CSS property. Instead, the icons are registered with the Skin object for use by the renderer. Icon selectors are denoted by -icon for component selectors and Icon:alias for global selectors. For example, the af:inputDate component has a changed icon that can have a skin using the selector af|inputDate::changed-icon. The changed icon can also be globally set for all components using that icon with the global selector .AFChangedIcon:alias. For more information, see Section 19.3.2, "How to Apply Skins to Icons".

  • Resource strings

    The text rendered by ADF Faces components is translatable. The text is abstracted as a resource string that has skins applied. For example, af_dialog.LABEL_OK is a resource string for the text label of an af:dialog component when the OK button has been configured. Resource strings do not have skins in the CSS skin file, but in a resource bundle referenced from the skin definition file in the trinidad-skins.xml file using the <bundle-name> parameter. You can also use the <translation-source> parameter for an EL binding to point to a Map or ResourceBundle. For more information, see Section 19.3.1, "How to Apply Skins to Text".

  • Selectors with style properties

    Skin style properties allow you to customize the rendering of a component throughout the application. A CSS property is stored with a value in the Skin object and is available when the component is being rendered. For example, in af|breadCrumbs{-tr-show-last-item: false}, the skin property -tr-show-last-item is set to hide the last item in the af:breadCrumbs navigation path.

The CSS specification defines pseudo-classes such as :hover and :active that can apply to almost every component. ADF Faces provides additional pseudo-classes for specialized functions. Pseudo-classes are denoted in the selector by a colon followed by the class definition. The following are common pseudo-classes used by ADF Faces style selectors:

  • Alias - The :alias pseudo-class sets styles for more than one component or more than one portion of a component. You can create your own alias classes that you can then include on other selectors.

    By changing the alias, you can change all components that reference that alias. For example, three form components style their label the same color using the .AFLabel:alias:

    af|inputText::label,
            af|inputChoice::label,
            af|selectOneChoice::label,{-tr-rule-ref: ".AFLabel:alias"}
            .AFLabel:alias { color: blue }
    

    The .AFLabel:alias pseudo-class has color set to blue, but you can change all the component's label color to red by simply changing .AFLabel:alias:

    .AFLabel:alias {color: red}
    

    For more information, see Section 19.3.5, "How to Create a Custom Alias".

  • Drag and drop - The two pseudo-classes available are :drag-source applied to the component 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 considered states of the component. This same concept is used in applying skins to components. Components can have states like read-only or disabled. When states are combined in the same selector, the selector applies only when all states are satisfied.

  • Right-to-left - Use this pseudo-class to set a style or icon definition when the browser is in a right-to-left language. Another typical use case is asymmetrical images. You will want the image to be flipped when setting skin selectors that use the 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. For example, the end image of the panelBox component will be the panelBoxStart.gif file when the browser is set to right-to-left. The panelBox end image in right-to-left is the same as the flipped left-to-right panelBox start image.

    af|panelBox::medium af|panelBox::top-end:rtl {
              background-image: url(/skins/purple/images/panelBoxStart.gif);
              width:8px; 
              height:8px
    }
    

    You can also use :rtl to apply to skin icons. For more information, see Section 19.3.2, "How to Apply Skins to Icons".

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

  • Message - This pseudo-class is used to set component-level message styles using CSS pseudo-classes of :fatal, :error, :warning, :confirmation, and :info. For more information, see Section 19.3.3, "How to Apply Skins to Messages".

The selectors used to apply skins to the ADF Faces components are defined in the "Skin Selectors for Fusion's ADF Faces Components" and "Skin Selectors for Fusion's Data Visualization Tools Components" topics in JDeveloper's online help located in Reference > Oracle ADF Faces.

You can also apply themes as a way to implement look and feel at the component level. For information about themes, see Section 19.3.4, "How to Apply Themes to Components".

For information about defining skin style properties, see Section 19.3, "Defining Skin Style Properties".

19.1.3 Component Style Properties

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

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.

For information about applying component style properties, see Section 19.4, "Changing the Style Properties of a Component".

19.2 Applying Custom Skins to Applications

Custom skins can change the colors, fonts, and even the location of portions of ADF Faces components to represent your company's preferred look and feel. You build the skin by defining style selectors in a CSS file. After you create your custom style sheet, register it as a valid skin in the application, and then configure the application to use the skin.

By default, ADF Faces components use the blafplus-rich skin. Custom skins can extend to any of the ADF Faces skins, blafplus-rich, blafplus-medium, or simple. To create a custom skin, you declare selectors in a style sheet that override or inhibit the selectors in the style sheet being extended. Any selectors that you choose not to override will continue to use the style as defined in that skin.

Extending the simple skin does not require inhibiting as many properties as you would if you extended the BLAF Plus skins. For example, the BLAF Plus skins use many different colors for style properties, including text, background, and borders. The simple skin uses the :alias pseudo-class, as in .AFDarkBackground:alias, instead of specific colors. Changing a color scheme would require overriding far fewer global skin selectors than component skin selectors that specify multiple colors.

The text used in a skin is defined in a resource bundle. As with the selectors for the blafplus-rich skin, you can override the text by creating a custom resource bundle and declaring only the text you want to change. After you create your custom resource bundle, register it with the skin.

You can create and apply multiple skins. For example, you might create one skin for the version of an application for the web, and another for when the application runs on a PDA. Or you can change the skin based on the locale set on the current user's browser. Additionally, you can configure a component, for example an af:selectOneChoice component, to allow a user to switch between skins.

While you can bundle the custom skin resources and configuration files with the application for deployment, you can also store skin definitions in a Java Archive (JAR) file and then add it to the deployed application. The advantages to using a JAR file are that the custom skin can be developed and deployed separately from the application, improving consistency in the look and feel, and that skin definitions and image files can be partitioned into their own JAR files, reducing the number of files that may have to be deployed to an application.

The steps to apply a custom skin to your application are the following:

  1. Add a custom skin to your application. For details, see Section 19.2.1, "How to Add a Custom Skin to an Application".

  2. Register the custom skin. For details, see Section 19.2.2, "How to Register a Custom Skin".

  3. Configure the application to use the custom skin. For details, see Section 19.2.3, "How to Configure an Application to Use a Custom Skin".

  4. Deploy a custom skin in a JAR file. For details, see Section 19.2.4, "How to Deploy a Custom Skin in a JAR file".

19.2.1 How to Add a Custom Skin to an Application

To add a custom skin to your application, create a CSS file within JDeveloper, which will place the CSS in a project's source file for deployment with the application.

To create a CSS:

  1. In JDeveloper, ensure that CSS Level 3 and ADF Faces are selected. From the main toolbar, choose Tools > Preferences > CSS Editor. For Support Level, choose CSS Level 3 from the dropdown menu, and for Supported Components, select ADF Faces Extension.

  2. In the Application Navigator, right-click the project that contains the code for the user interface and choose New from the context menu.

  3. In the New Gallery under Categories, expand Web Tier and select HTML.

  4. Double-click the CSS File option.

  5. In the Create Cascading Style Sheet dialog, enter a name and path for the CSS.

  6. Click OK.

You can now open the CSS in the CSS editor and define styles for your application. For information about setting ADF Faces component style selectors, see Section 19.3, "Defining Skin Style Properties".

You can also create a CSS outside the context of Oracle JDeveloper and package the CSS with the skin resources into a JAR file. For information about this recommended option, see Section 19.2.4, "How to Deploy a Custom Skin in a JAR file".

19.2.2 How to Register a Custom Skin

Registering a skin involves creating a file named trinidad-skins.xml and populating it with a list of tags that identify the skin's ID, family, location, and the custom resource bundle if you are using one.

To register a custom skin:

  1. In the Application Navigator, right-click the WEB-INF folder in a project belonging to the application to which you will apply a skin, and choose New from the context menu.

  2. Under the General node in the New Gallery, select XML File.

  3. Select XML Document and click OK.

  4. In the File Name field, enter the file name trinidad-skins.xml.

  5. In the Directory Name field, enter the path to the location where the file should be sorted, or accept the default. The file must be stored in the WEB-INF folder.

  6. Click OK to create the file.

  7. Replace the code with the code in Example 19-4.

    Example 19-4 Default Code for a trinidad-skins.xml File

    <?xml version="1.0" encoding="windows-1252" ?>
    <skins xmlns="http://myfaces.apache.org/trinidad/skin">
      <skin>
        <id>myskin.desktop</id>
        <family>myskin</family>
        <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
        <style-sheet-name>css/myskin.css</style-sheet-name>
      </skin>
    </skins>
    
    
  8. In the source editor, enter the tags required to register a skin:

    • <id>

      A skin is required to have a unique ID. You can also use an EL expression to reference the skin ID. For example, if you want to have different skins for different locales, create an EL expression that will select the correct skin based on its ID. The convention is to put a "desktop" or ".pda" or ".portlet" at the end of the ID, such as "blafplus-medium.desktop".

    • <family>

      You configure an application to use a particular family of skins. This allows you to group skins together for an application, based on the render kit used.

      For example, you can define the blafplus-rich.desktop skin and the blafplus-rich.pda skin to be part of the richDemo family and the system will automatically choose the right skin based on the render-kit-id.

      <skin>       <id>richdemo.desktop</id>       <family>richDemo</family>       <extends>blafplus-rich.desktop</extends>       <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>       <style-sheet-name>skins/richdemo/richdemo.css</style-sheet-name></skin><skin>       <id>richdemo.pda</id>       <family>richDemo</family>       <extends>blafplus-rich.pda</extends>       <render-kit-id>pda</render-kit-id>       <style-sheet-name>skins/richdemo/richdemo.css</style-sheet-name></skin> 
      
    • <extends>

      You extend a custom skin by using this element. The default value for this element is simple.desktop. However, you can extend any skin by using this element.

      You can easily change the font of the entire skin by extending the skin and creating a CSS with the font alias. For example, extend the blafplus-rich.desktop family as follows:

      <extends>blafplus-rich.desktop</extends>
      <style-sheet-name>skins/skins/myStyle/mystyle.css</style-sheet-name>
      

      In the CSS, set the alias to change the font for the entire skin:

      .AFDefaultFontFamily:alias {font-family: Tahoma}.AFDefaultFont:alias {font-size: 16px}
      
    • <render-kit-id>

      This value determines which render kit to use for the skin. You can enter one of the following:

      • org.apache.myfaces.trinidad.desktop: The skin will automatically be used when the application is rendered on a desktop.

      • org.apache.myfaces.trinidad.pda: The skin will be used when the application is rendered on a PDA.

    • <style-sheet-name>

      This is the URL of the custom style sheet. The style sheet name file is retrieved as a URL object using the following methods:

      • For nonstatic URLs, those that could change after the server has started, the URL is created by calling new java.new.URL(style-sheet-name) if style-sheet-name starts with http:, https:, file:, ftp:, or jar:. Otherwise, the URL is created by calling <FacesContext> <ExternalContext> getResource<style-sheet-name>. It will add a slash (/) to delimit the URL parts if it is not already present. For example, the slash is added between skins/bigfont/bigfont.css.

      • If still not retrieved, the URL is created using the <ClassLoader> getResource in a style-sheet-name format similar to META-INF/purpleSkin/styles/myPurpleSkin.css. Once the URL is converted to this format, it can be searched for in JAR files that may contain the style sheet.

    • <bundle-name>

      This is the resource bundle created for the skin. If you did not create a custom bundle, then you do not need to declare this element. For more information, see Section 19.3.1, "How to Apply Skins to Text".

      Note:

      If you have created localized versions of the resource bundle, then you need to register only the base resource bundle.
    • <translation-source>

      This is an EL binding that can point to a Map or a ResourceBundle. You can use this instead of the bundle name if you would like to be more dynamic in your skin translations at runtime. The <bundle-name> tag takes precedence.

    Example 19-5 shows the entry in the trinidad-skins.xml file for the mySkin skin.

    Example 19-5 Skin Entry in the trinidad-skins.xml File

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <skins xmlns="http://myfaces.apache.org/trinidad/skin">
        <skin>
            <id>
                mySkin.desktop
            </id>
            <family>
                mySkin
            </family>
            <extends>blafplus-rich.desktop</extends>
            <render-kit-id>
                org.apache.myfaces.trinidad.desktop
            </render-kit-id>
            <style-sheet-name>
                skins/mySkin/mySkin.css
            </style-sheet-name>
            <bundle-name>
                myBundle
            </bundle-name>
            <translation-source>
                
            </translation-source>
        </skin> 
    </skins>
    
  9. Save the file.

19.2.3 How to Configure an Application to Use a Custom Skin

You set an element in the trinidad-config.xml file that determines which skin to use, and if necessary, under what conditions.

Note:

If you do not see the skin, check to see whether or not the af:document tag has been added to the page. The af:document tag initializes the skin framework to create the CSS and link it to the page.

To configure an application to use a skin:

  1. Open the trinidad-config.xml file.

  2. Replace the <skin-family> value with the family name for the skin you wish to use.

    Example 19-6 shows the configuration to use for the mySkin skin family.

    Example 19-6 Configuration to Use a Skin Family

    <trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
      <skin-family>mySkin</skin-family>
    </trinidad-config>
    
  3. To conditionally set the value, enter an EL expression that can be evaluated to determine the skin to display.

    For example, if you want to use the German skin when the user's browser is set to the German locale, and to use the English skin otherwise, you would have the following entry in the trinidad-config.xml file:

    <skin-family>#{facesContext.viewRoot.locale.language=='de' ? 'german' : 'english'}</skin-family>
    
  4. Save the file.

19.2.4 How to Deploy a Custom Skin in a JAR file

You may want to store skin definitions in a Java Archive (JAR) file and then add it to the deployed application. The benefits of packaging skins into a JAR file as compared to bundling them into the application are the following:

  • A skin can be deployed and developed separately from the application. This also helps to reduce the number of files to be checked in case some changes need to be applied to the skin. Foremost is that using a skin definition contained in a JAR file improves consistency in the look and feel of the application.

  • Skin definitions and images can be separated into their own JAR files. Therefore, you can partition the image base into separate JAR files, so that not all files have to be deployed with all applications.

To deploy a skin into a JAR file, follow these rules:

  • The trinidad-skins.xml file that defines the skin and that references the CSS file must be within the META-INF directory.

  • All image resources and CSS files must also be under the META-INF directory. The images must be in a directory that starts with an adf root directory or any directory name that is mapped in the web.xml file for the resource servlet, as shown in Example 19-7.

  • The JAR file must be placed in the WEB-INF/lib directory of the ViewLayer project of the application to deploy (or use a shared library at the application-server level).

Example 19-7 web.xml File with Paths

<servlet-mapping>
      <servlet-name>resources</servlet-name>
      <url-pattern>/adf/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
      <servlet-name>resources</servlet-name>
      <url-pattern>/afr/*</url-pattern>
 </servlet-mapping>

To deploy a skin in a JAR file:

  1. Create a directory structure similar to the following:

    c:\temp\META-INF\adf\oracle\skin\images
                  META-INF\skins\oracleblaf.css
                  META-INF\trinidad-skins.xml
    
  2. Confirm that the directory in the META-INF directory starts with "adf". The images directory contains all the images used within the oracleblaf.css skin. The CSS reference to the images should have a path similar to this:

    af|inputColor::swatch-overlay-icon:rtl {
            content:url(../adf/oracle/skin/images/cfsortl.gif);
            width: 12; height: 12;
            left:-7px;
            position:relative;
            right:-7px;
            top:5px;
    }
    

    Note the two leading periods in front of the image path ../adf/oracle/skin/images/cfsortl.gif. This allows the search for the META-INF root to start one directory above the META-INF\skin directory in which the CSS is located.

  3. Check that the trinidad-skins.xml file is located in the META-INF directory and that it contains content in a format similar to this:

    <?xml version="1.0" encoding="ISO-8859-1"?>
          <skins xmlns="http://myfaces.apache.org/trinidad/skin">
            <skin>
              <id>oracleblaf.desktop</id>
              <family>oracleblaf</family>
              <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
              <style-sheet-name>skins/oracleblaf.css</style-sheet-name>
            </skin>
          </skins>
    

    This example defines the skin as oracleblaf.desktop in the oracleblaf family. The trinidad-skins.xml file can have more than one skin definition. The oraclebalf.css file (or your custom CSS file) is referenced from the style-sheet-name element.

  4. To create the JAR file, issue the following command from the c:\temp directory:

    jar -cvf customSkin.jar META-INF/
    
  5. Copy the resulting customSkin.jar file to the WEB-INF/lib directory of the consuming ADF project. Configure the trinidad-skins.xml file located on the WEB-INF directory of the ADF project.

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

    Because the skin can be discovered at runtime, you do not need to code the skin family name.

Note:

The skin definition in the JAR file is not displayed in the JDeveloper visual editor. You may see a message in the log window that the skin family could not be found. You can ignore this message.

19.3 Defining Skin Style Properties

The ADF Faces skin style selectors support multiple options for applying skins to a component to create a custom look and feel to your application. The af:goButton component skin style selectors are described in Table 19-1.

Table 19-1 af:goButton Component Style Selectors

Name Description

af|goButton

Style on the root element of the af:goButton component. You can use any valid CSS-2.1 pseudo-class, like :hover, :active, or :focus, as well as :disabled, to style the component for different states. Note that for buttons, the :active and :focus pseudo-classes do not work in Internet Explorer 7 (IE7). IE7 also does not allow disabled buttons to be styled. You should use the .AFButton*:alias selectors as a shortcut to apply a skin to all button components in the same manner.

af|goButton::icon-style

Style on the button icon, if the icon attribute is set on the af:goButton.

af|goButton::access-key

Style on the text of the button. This includes the .AFButtonAccessKeyStyle:alias style.


Figure 19-3 shows the application of the default blafplus-rich skin on the af:goButton component and the component icon.

Figure 19-3 af:goButton Component Default Appearance

af:goButton component default appearance.

Figure 19-4 shows the new appearance of the button and icon by setting the following style properties in a custom skin:

af|goButton::access-key {color: red;}
af|goButton::icon-style {border: 1px solid black;}

Figure 19-4 af:goButton Component with Custom Skin Applied

af:goButton component using custom skin.

The ADF Faces skin style selectors used by the default skin are defined in the "Skin Selectors for Fusion's ADF Faces Components" and "Skin Selectors for Fusion's Data Visualization Tools Components" topics in JDeveloper's online help. They are located in Reference > Oracle ADF Faces.

JDeveloper provides coding support while editing your CSS files. You can invoke the CSS code editor when editing your file directly or when editing an ADF Faces component in the JSP source editor. Code support is available for the following:

19.3.1 How to Apply Skins to Text

In addition to using a CSS file to determine styles, skins also use a resource bundle to determine the text within a component. The text that ADF Faces components render can be translated and abstracted as a resource string. For example, af_chooseDate.LABEL_SELECT_YEAR is the resource string for the label of the field used to select the year using an af:chooseDate component. All the ADF Faces skins use the same resource bundle.

To apply a skin to the text in ADF Faces components, create a custom resource bundle and override the default resource string values. Then, set the <bundle-name> property for your custom resource bundle in the trinidad-skins.xml file.

Note:

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

See Chapter 20, "Internationalizing and Localizing Pages" for more information.

To create and register a custom resource bundle:

  1. In JDeveloper, create a new simple Java class:

    • In the Application Navigator, right-click where you want the file to be placed and choose New to open the New Gallery.

    • In the Categories tree, select Simple Files, and in the Items list, select Java Class.

    • Enter a name and package for the class. The class must extend java.util.ListResourceBundle.

  2. Add any keys to your bundle that you wish to override and set the text as needed. Example 19-8 shows the SkinBundle custom resource bundle.

    Example 19-8 Resource Strings Set in Custom SkinBundle

    public class SkinBundle extends ListResourceBundle {
            @Override
            public Object[][] getContents() {
              return _CONTENTS;
            }
          
            static private final Object[][] _CONTENTS = {
              {"af_tableSelectMany.SELECT_COLUMN_HEADER", "Select A Lot"},
              {"af_tableSelectOne.SELECT_COLUMN_HEADER", "Select Just One"},
              {"af_showDetail.DISCLOSED_TIP", "Click to Hide"}
            };
     }
    
  3. Set the name of your custom resource bundle in the <bundle-name> parameter of the trinidad-skins.xml file. Example 19-9 shows the custom SkinBundle set in the trinidad-skins.xml file.

    Example 19-9 Custom SkinBundle Set in trinidad-skins.xml

    <skin>
            <id>
                purple.desktop
            </id>
            <family>
                purple
            </family>
            <render-kit-id>
                org.apache.myfaces.trinidad.desktop
            </render-kit-id>
            <style-sheet-name>
                skins/purple/purpleSkin.css
            </style-sheet-name>
            <bundle-name>
                org.apache.myfaces.trinidaddemo.resource.SkinBundle
            </bundle-name>
     </skin>
    
    

Another option for applying skins to text is to use the <translation-source> parameter instead of <bundle-name>. The <translation-source> parameter is an EL binding that points to a Map or a ResourceBundle. The benefit of this option is that you can automatically change the translation value based on any logic that you want at runtime. The <bundle-name> tag takes precedence if both are set. Example 19-10 shows the code for using an EL expression to set the <translation-source> parameter in a bundle map.

Example 19-10 Custom Resource Bundle Map

public class SkinTranslationMapDemo
{
  /* Test a skin's translation-source EL pointing to a Map */
  public Map<String, String> getContents()
  {
    return _CONTENTS;
  }
 
  static private final Map<String, String> _CONTENTS = new HashMap<String, String>();
  static 
  {
    _CONTENTS.put("af_inputDate.LAUNCH_PICKER_TIP", "Launch PickerMap");
    _CONTENTS.put("af_showDetail.DISCLOSED_TIP", "Hide Tip Map");
    _CONTENTS.put("af_showDetail.DISCLOSED", "Hide Map");
 
  }
}

Example 19-11 shows setting the <translation-source> parameter for the resource map in the trinidad-skins.xml file.

Example 19-11 Custom Resource Bundle Map Set in trinidad-skins.xml

<skin>
        <id>
            purple.desktop
        </id>
        <family>
            purple
        </family>
        <render-kit-id>
            org.apache.myfaces.trinidad.desktop
        </render-kit-id>
        <style-sheet-name>
            skins/purple/purpleSkin.css
        </style-sheet-name>
        <translation-source>#{skinTranslationMap.resourceBundle}</translation-source>
    </skin>

19.3.2 How to Apply Skins to Icons

You can apply skins to the default icons associated with ADF Faces components by specifying the URL path to the icon image in the icon style selector.

Note that CSS syntax like pseudo-classes (:hover, and so forth) and descendant selectors and composite class selectors does not work with icon selectors.

Note:

If you are overriding a selector for an icon, use a context-relative path for the URL to the icon image (that is, start with a leading slash (/)), and do not use quotation marks.

Also, you must include the width and the height for the icon.

Example 19-12 shows a selector for an icon.

Example 19-12 Selector for an Icon

.AFErrorIcon:alias {
      content:url(/adf/images/error.png);
      width:7px; height:18px
 }

Icons and buttons can both use the rtl pseudo-class. This defines an icon or button for use when the application displays in right-to-left mode. Example 19-13 shows the rtl pseudo-class used for an icon.

Example 19-13 Icon Selector Using the rtl Pseudo-Class

.AFErrorIcon:alias:rtl {
      content:url(/adf/images/error.png);
      width:16px; height:16px
 }

19.3.3 How to Apply Skins to Messages

You can apply style to ADF Faces input components based on whether or not they have certain levels of messages 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 styles are not defined for the status in question, then the default styles are used.

In order to define styles for your input components based on message levels that are tied to them, you would append a style pseudo-class to your component definition. For example, to define the base style for the content region of the af:inputText component to a background color of purple, use the style selector af|inputText::content{background-color:purple}. To define the content region of the component when an error message is present, use the skin style selector af|inputText:error::content.

The valid message properties are :fatal, :error, :warning, :confirmation, and :info.

19.3.4 How to Apply Themes to Components

Themes are a way of implementing a look and feel at a component level. The 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.

While the tonal style classes .AFDarkTone, .AFMediumTone, .AFLightTone and .AFDefaultTone are still available, themes are the default style. Themes are easier to author than tonal styles, they rely on fewer selectors, and they avoid CSS containment selectors. For these reasons, they are less prone to problems. Due to the limitation on the number of selectors in one CSS file, tonal styles and themes both cannot be supported in the same application.

To continue to use tonal styles in your application:

  1. Open your project's web.xml file in the source editor.

  2. Set this context initialization parameter if it is not already set:

    <context-param>
      <param-name>oracle.adf.view.rich.tonalstyles.ENABLED</param-name>
      <param-value>true</param-value>
    </context-param>
    
  3. Save the file.

Themes are the default. You do not need to modify the web.xml file to use themes.

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 following components:

  • af:document

  • af:decorativeBox

  • af:panelStretchLayout

  • af:panelGroupLayout

The BLAF Plus skins, blafplus-rich and blafplus-medium, support the following themes:

  • Dark

  • Medium

  • Light

  • None (default)

To set the theme for a component, specify a theme attribute in the skin selector. For example, the selector to change the text color under an af:panelTabbed component to a dark theme is:

af|panelTabbed[theme="dark"] {
  color: red;
}

In the JSPX page, the theme is started by the af:document component, as in:

<af:document theme="dark">
  <af:panelTabbed>...</af:panelTabbed>
</af:document>

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. 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 would be:

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 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 setting the panelGroupLayout or panelStretchLayout theme to a compatible color.

<af:panelHeader text="Header Level 0"> 
            <af:panelGroupLayout layout="vertical" theme="default"> 
              ... 
            </af:panelGroupLayout>
</af:panelHeader> 

19.3.4.1 What You May Need to Know About Theme Inheritance

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.

19.3.5 How to Create a Custom Alias

You can create your own alias that you can then include on other selectors.

To create a custom alias:

  1. Create a selector class for the alias. For example, you can add an alias to set the color of a link when a mouse cursor hovers over it:

    .MyLinkHoverColor:alias {color: #CC6633;}
    
  2. To include the alias in another selector, add a pseudo-element to an existing selector to create a new selector, and then reference the alias using the -tr-rule-ref:selector property.

    For example, you can create a new selector for the af|menuBar::enabled-link selector to style the hover color, and then reference the custom alias, as shown in Example 19-14.

    Example 19-14 Referencing a Custom Alias in a New Selector

    af|menuBar::enabled-link:hover
    {
      -rt-rule-ref:selector(".MyLinkHoverColor:alias");
    }
    

19.3.6 How to Configure a Component for Changing Skins Dynamically

To configure a component to dynamically change the skin, you must first configure the component on the JSF page to set a scope value that can later be evaluated by the configuration file. You then configure the skin family in the trinidad-config file to be dynamically set by that value.

To conditionally configure a component to set the skin family:

  1. Open the main JSF page (such as the index.jspx or a similar file) that contains the component that will be used to set the skin family.

  2. Configure the page to display the skin family by using the sessionScope component.

    Example 19-15 shows an af:selectOneChoice component that takes its selected value, and sets it as the value for the skinFamily attribute in the sessionScope component on the index.jspx page.

    Example 19-15 Using a Component to Set the Skin Family

    <af:selectOneChoice label="Choose Skin:" value="#{sessionScope.skinFamily}" autoSubmit="true">
        <af:selectItem value="blafplus-rich" label="blafplus-rich"/>
        <af:selectItem value="blafplus-medium" label="blafplus-medium"/>
        <af:selectItem value="simple" label="simple"/>
        <af:selectItem value="richDemo" label="richDemo"/>
        <af:selectItem value="mySkin" label="mySkin"/>
    </af:selectOneChoice>
    

    The Refresh button on the page resubmits the page. Every time the page refreshes, the EL expression is evaluated and if there is a change, the page is redrawn with the new skin.

To conditionally configure a component for changing skins at runtime:

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

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

19.4 Changing the Style Properties of a Component

ADF Faces components use the CSS style properties based on the Cascading Style Sheet (CSS) specification. Cascading style sheets contain rules, composed of selectors and declarations, that define how styles will be applied. These are then interpreted by the browser and override the browser's default settings.

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 framework to achieve component stretching. For more information about layouts and stretching, see Section 8.3, "Arranging Contents to Stretch Across a Page".

19.4.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 informatino, see Section 8.3, "Arranging Contents to Stretch Across a Page".

To set an inline style:

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

    • 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 19-5.

      Figure 19-5 Setting an inlineStyle

      Setting inlineStyle attribute with Property Inspector

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

      Example 19-16 InlineStyle in the Page Source

      <af:outputText value="outputText1"
                     inlineStyle="color:Red; text-decoration:overline;"/>
      
    • 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 19-17.

      Example 19-17 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);':''}"/>
      

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 in:

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

19.4.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.

To set a style using a style class:

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

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

    Example 19-18 Page Source for Using a Style Class

    <af:outputText value="Text with a style class" 
                   styleClass="overdue"/>
    

    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 19-17.