As Published In November/December 2011

TECHNOLOGY: Oracle ADF

Put on a Friendly Face

Build a custom look and feel for your Oracle ADF Faces applications.

An ancient Chinese proverb says, “He who does not have a friendly face should not run a business.” An application’s look and feel can be the friendly face your company shows its customers to help generate a positive impression of the business. Oracle ADF Faces—the Oracle Application Development Framework (Oracle ADF) view technology based on JavaServer Faces (JSF)—provides an integrated framework for styling user interface components to fit your corporate branding and UI standards.

Oracle ADF Faces skinning enables developers to change an application’s look and feel—including color scheme, font size and style, component borders, default label text, images, and more—without changing the application’s UI code. This column provides an overview of skinning and explains the workflow for putting a fresh smile on your applications by using the Oracle ADF Faces skin editor, introduced in Oracle JDeveloper 11g Release 11.1.2. Then, as an exercise, you’ll create a new skin for a sample application.

To begin, download the Summit ADF Project application and schema and unzip the SummitADFV1_0_08072011.zip file. Ensure that you’re using the studio edition of Oracle JDeveloper 11g Release 11.1.2 (or later), available as a free download from Oracle Technology Network. In Oracle JDeveloper, open the Summit_Schema.jws project, located in the Schema folder in the SummitADFV1_0_08072011 folder. In the Application Navigator, expand the Database node’s Resources folder, and double-click build_summit_schema.sql. On the SQL Worksheet tab, click the Run Script button (or press the F5 key). When prompted to select a database connection, select a connection for a user who has the privileges necessary to create a new user and schema and click OK to run the script. (If you do not have a connection in Oracle JDeveloper for such a user, click the plus sign in the Select Connection dialog box, create a new connection for an appropriately privileged user—such as SYSTEM—and select that new connection.) When the script finishes, close the Summit_Schema project.

Oracle ADF Faces Skinning 101

Skinning uses the standard Cascading Style Sheets (CSS) language to specify colors, fonts, icons, and images for Oracle ADF Faces components. The style definitions are decoupled from the generated HTML component output, which makes custom look-and-feel definitions easy to write and maintain. The style definitions are dynamically added to the generated HTML page output at runtime.

When used for conventional Web page development, CSS uses selectors to address HTML elements on a page. Similarly, Oracle ADF Faces skinning uses specific skin selectors to address Oracle ADF Faces components (such as af:inputText) or areas within a component (such as the label or data portion). The most-common selectors are 

• Global selector aliases. Global skin selectors apply CSS definitions to all or a group of components. Global selector names are suffixed with the :alias string, as in .AFDefaultFont:alias.

• Component type selectors. Component selectors apply to all instances of a specific component type, such as af:inputText or af:commandButton. The component type selector name is similar to the tag name of the component that it skins. The difference is that the type selector uses a pipe symbol, whereas the component tag name has a colon. For example, the component type selector for the af:inputText component tag is af|inputText.

• Component pseudo-elements. Pseudo-elements point to specific areas in a component. For example, to style the data portion of a text input field, you use the af|inputText::content selector and element.

• Descendant selectors. To style a component based on its location on a page, you use descendant selectors. For example, to apply a different style to an af:goButton located in a toolbar, you use the af|toolbar af|goButton descendant selector.

• Pseudo-classes. To visually indicate component state (such as disabled) or behavior state (such as mouse hover), you use standard CSS pseudo-classes. The skin editor helps you discover and style pseudo-classes for the component you are skinning.

• Resource selectors. In addition to changing a component’s look and feel, you can change its default labels. In this instance, Oracle ADF Faces skinning goes beyond what is possible in traditional CSS. For example, to change the OK label in af:dialog to Accept, you add af_dialog .LABEL_OK : Accept to the resource properties file.

See the Oracle ADF Faces skin tag documentation (part of the Oracle Fusion Middleware API documentation) at bit.ly/nNImZC for a complete list of components and their resource selectors. 

To respond to differences in how browsers render CSS, Oracle ADF Faces skinning provides the @agent, @version, and @platform selectors. For example, to add padding to text component labels only when they are displayed in Mozilla Firefox 3.6 on Microsoft Windows, you use the following style construct:

@platform windows{
  @agent gecko and (version: 3.6*){
    af|inputText::label{ padding-right:2px;}
  }
}

Similarly, the @locale selector uses the browser locale setting on the client to specify look-and-feel changes. For example, you can use this style construct to change the af:infputText component’s colors only for the Germany (de) locale:

@locale de{
  af|inputText::label{background-color:yellow;}
  af|inputText::content{background-color:black; color:red;}
}

The skin displayed in an Oracle ADF application is configured in the trinidad-config.xml file, located in the WEB-INF folder of the ViewController project. By default, the <skin-family> XML element in this configuration file is set to one of the skins shipped with Oracle JDeveloper.

The skins an application can use must be defined in the trinidad-skins.xml configuration file—either in the application itself or referenced from an Oracle ADF library.

Oracle ADF Faces Skin Editor Overview

The Oracle ADF Faces skin editor, shown in Figure 1, hides the CSS configuration details from the skin designer by exposing a visual and declarative development environment.

Figure 1: Oracle ADF Faces skin editor

In the skin editor, you edit style definitions via the Property Inspector (Ctrl-Shift-I). Properties with a blue arrow icon on their left, such as the Background Image property in Figure 1, inherit their style definitions. When you move the mouse over the icon, a tool tip shows information about the parent skin CSS file.

A green icon, such as the one to the left of the Background Color property in Figure 1, indicates that a property value in the custom skin overrides an inherited value. Using the context menu in the Property Inspector, you can reset a property to its inherited value.

The main area of the Oracle ADF Faces skin editor shows a preview of how a style added to a skin selector—for example, af|inputText::content in Figure 1—renders for different component states and themes. Clicking one of these areas—for example, af|inputText::content:busy—enables you to change colors for the selected component area and state in the Property Inspector.

Themes—indicated by several theme tabs—are attribute selectors for distinguishing nested layout components of the same type. For example, to visually separate two nested af:panelBox components, you set the theme attribute to a different value for one of them. Themes are inherited by components contained in those layout areas, which is why the skin editor shows the theme tabs for all components.

The component tree on the left-hand side of the skin editor in Figure 1 shows the available components and selector aliases that developers can change in a skin. You expand the component entry to see the component selector, available pseudo-elements, style classes, and descendant selectors.

You can switch the component tree view between the Available Selectors view and the Updated Selectors view. The plus sign next to the view switcher enables you to create custom :alias classes or new CSS style classes.

Skinning Workflow

A basic workflow for building custom skins using the Oracle ADF Faces skin editor is as follows: 

1. Create a skin project. Because skins are reusable components, they should be created in their own project or workspace.

2. Create a new skin by extending an existing skin. Oracle ADF Faces provides simple default skins that are specifically designed to be extended by custom skins.

3. Analyze the application for the components to skin. Identify the components on a page that you want to skin, and map them to skin selectors with the skin editor.

4. Identify global selector aliases to skin first. Selector aliases do the proverbial 20 percent of the work that affects 80 percent of the components in an application.

5. Define custom :alias definitions. Custom :alias definitions simplify maintenance of style definitions used on multiple components. You apply custom :alias definitions via the -tr-rule-ref selector.

6. Generate images and icons. Use the skin editor to generate custom colored versions of Oracle ADF Faces component images and icons.

7. Edit the skin CSS file with the skin editor. Use the skin editor to discover skin selectors for the components and behavior you want to skin, and apply the changes via the Property Inspector.

8. Deploy the skin in an Oracle ADF library. Skins can and should be reused. For this purpose, create an Oracle ADF library deployment profile from the skin project and deploy the skin in a Java Archive (JAR) file.

9. Frequently test your custom skin in a browser. Reference the skin JAR file from the ViewController project of the target application. Set the custom skin family name in the <skin-family> element of the target application’s trinidad-config.xml file.

10. Deploy the skin as a shared library to Oracle WebLogic Server. Optionally, if a custom skin is shared among applications, deploy the skin Oracle ADF library JAR file as a shared library to Oracle WebLogic Server and edit the application’s weblogic-application.xml file to reference it. 

Hands-On Skinning Exercise

Now that you have an overview of skinning and the skin editor, you’re ready for some hands-on practice. In a simple exercise, you’ll skin the Oracle ADF Summit sample application to give it a new color scheme.

Before you can start the skinning project, you must migrate the Oracle ADF Summit application to Oracle JDeveloper 11g Release 11.1.2. In Oracle JDeveloper, open the SummitADF.jws workspace, located in the Application folder in the SummitADFV1_0_08072011 folder. Click Next to accept the migration changes suggested by Oracle JDeveloper, and click Finish to save them.

Start by taking a look at the Oracle ADF Summit application’s current look and feel, shown in Figure 2. In the Application Navigator, expand the ViewController project and double-click the index.jspx file in the Web Content folder to open it in the design view. Right-click in the page design, and choose Preview in Browser. The Preview in Browser option shows the page in a layout-only view with no data queried from the business services and without starting Oracle WebLogic Server. (If you want to see the page with live data, as in Figure 2, choose the Run option instead.)

Figure 2: Oracle ADF Summit sample application with fusionFx look and feel

After you complete the skinning exercise, the Oracle ADF Summit application will have the new custom look shown in Figure 3.

Figure 3: Custom look and feel applied to the Oracle ADF Summit application

Back in Oracle JDeveloper, begin to create a new skin project by choosing File -> New. Select the All Features tab. Under Categories, choose General -> Projects. Under Items, select Custom Project and click OK.

In the open dialog box, enter OraBlogsRedSkin as the Project Name and shuttle the ADF Faces library entry from the list of available libraries to the list of selected libraries. This automatically also adds the Java, JSF, JavaServer Pages and servlets, Trinidad, and XML library dependencies to the list of selected libraries. Click Next to access the dialog box for configuring Java settings. Leave its values unchanged, and click Finish.

In the Application Navigator, right-click the OraBlogsRedSkin project node and choose New. On the New Gallery dialog box’s Current Project Features tab, select Web Tier -> JSF/Facelets and then ADF Skin. Click OK to open the Create ADF Skin File dialog box. Enter OraBlogsRedSkin.css in the File Name field, as shown in Figure 4, to configure it as the skin definition file that will hold the skin selector and styling information. The skin Family name automatically changes to the same base name as the CSS file’s.

Figure 4: Skin creation dialog box

If it’s not selected by default, select fusionFx-simple-v2.desktop from the Extends list. The fusionFx simple skin is a default skin that is specifically designed as a starting point for new skin-development projects. In contrast to the full fusionFx skin, the fusionFx simple skin uses fewer color definitions on the individual UI components and has fewer global alias selectors to override.

Click OK to close the skin creation dialog box, after which Oracle JDeveloper

1. Creates the trinidad-skins.xml configuration file in the skin project’s WEB-INF directory. The new skin is configured in this file.

2. Updates the trinidad-config.xml file for the <skin-family> element to reference the OraBlogsRedSkin skin family name.

3. Creates a skinBundle.properties file to enable you to change the default component label strings if necessary.

4. Adds the OracleBlogsRedSkin.css file to the Web Content folder.

5. Opens the skin editor (shown in Figure 1) so that you can edit the CSS file with your custom style definitions. (If you closed the skin editor, you can reopen it by double-clicking the CSS file.) 

The next step is to configure the global component selectors aliases according to the color scheme for the OraBlogsRedSkin skin, which is inspired by the look of the blogs.oracle.com/jdevotnharvest site.

If you don’t own the color scheme for a site, you can use tools such as the I Like Your Colors tool at redalt.com to generate one. The scheme then needs to be refined and mapped to the colors and the global selector aliases of the fusionFx simple skin.

Figure 5 shows the fusionFx colors and the replacement colors used by the OraBlogsRedSkin skin. The hex-code values are the color codes of the OraBlogsRedSkin color scheme.

Figure 5: Mapping of fusionFx selector alias colors to custom colors

To skin global selectors according to the color scheme shown in Figure 5, expand the Global Selector Aliases -> Color entry in the skin editor, as shown in Figure 6. Locate each of the selector names listed in Figure 5, and use the Property Inspector to apply the color hex code to the Background Color property for background selector aliases or the Color property for foreground selector aliases. Text and label selector aliases are located in Global Selector Aliases -> Text, and link selector aliases are in Component Group -> Links. The skin editor preview screen refreshes for each change of a style property, even if there is no immediate change to show in the preview.

Figure 6: Skin editor and Property Inspector view for configuring global component selectors

Note that the skin editor doesn’t yet show the AFLabelTextForeground:alias selector. To skin this selector, click the Source tab at the bottom of the skin editor and add the following definition:

.AFLabelTextForeground:alias{ color: #4b4b4b; }

Click the Design tab to return to the visual editor view.

The Oracle ADF Summit application contains components, such as af:panelTab, that use images to render component-specific shapes, such as rounded edges or tab items. To skin those images, you can provide your own images or use the Oracle ADF Faces skin editor to add default images to the skin project.

To generate images according to the color definitions added to the global selector aliases, open the OraBlogsRedSkin.css file in the skin editor and select the Images tab at the bottom of the editor to open the image-generator view.

Click the Apply To Skin button above the image preview, as shown in Figure 7, to create the images and copy them to your custom skin project. The Oracle ADF Faces skin editor also adds the skin selector changes to the skin CSS file so that the components use the custom images instead of the default images.

Figure 7: Skin editor image and icon generation dialog box

Click the Source tab at the bottom of the Oracle ADF Faces skin editor to see the actual skin selector changes defined for this custom skin.

Click the Design tab to see the skin preview. Select the af|inputText -> Pseudo-Elements -> content node to see a preview of the applied skin changes for the af:inputText component. In the Property Inspector, move the mouse over the blue arrow icon next to the Color property to see where the foreground color is inherited from.

Test the Skin

So far you’ve customized only global selector alias settings and created new images. This is a good time to check how the new skin looks in a browser, but before testing the skin, you need to deploy it as an Oracle ADF library to the ViewController project of the Oracle ADF Summit application.

In the Application Navigator, double-click the OraBlogsRedSkin project node and select Deployment in the Project Properties dialog box. Click New to create a new Oracle ADF library JAR file. Enter OraBlogsRedSkin as the deployment profile name, and click OK. Then click OK in the opened Library Dependencies dialog box without editing any properties. Click OK again to exit the project properties.

In the Application Navigator, right-click the OraBlogsRedSkin project node and choose Deploy -> OraBlogsRedSkin. Click Next and Finish to create the JAR file in the file system.

Next, expand the ViewController project and double-click the trinidad-config.xml file, located in the Web Content -> WEB-INF folder. In the file source, change the <skin-family> element value from fusion to OraBlogsRedSkin. This setting will apply the custom skin when you run the application.

To ensure that the custom skin is found at design time and runtime, you need to reference the skin Oracle ADF library from the View Controller library settings. In the Application Navigator, double-click the ViewController project and select Libraries and Classpath in the Project Properties dialog box. Click Add JAR/Directory, and navigate to the OraBlogsRedSkin -> Deploy folder. Expand the folder, select the OraBlogsRedSkin.jar file, click Select,and click OK.

In the Application Navigator, expand the Web Content folder in the ViewController project and double-click the index.jspx file to open it in the design view. You should see the new skin colors when the design renders. To runtime-test the custom skin in a browser, right-click the index.jspx page in the design view and choose either Preview in Browser or Run.

If your skin is behaving correctly, you can refine the OraBlogsRedSkin definition now—for example, by adding styles to individual component selectors. (If you haven’t successfully completed the exercise, you can download and use the completed Oracle ADF Summit sample application.) When making further refinements, be sure to redeploy the OraBlogsRedSkin skin Oracle ADF library before testing the changes in the ViewController project.

Conclusion

This column has shown you how easy it is to put a fresh smile on your Oracle ADF Faces application by using the Oracle ADF Faces skinning framework and the declarative Oracle ADF Faces skin editor in Oracle JDeveloper 11g Release 11.1.2.

The skin editor is also available in a standalone version, for the benefit of developers who want to build a custom look and feel for Oracle JDeveloper 11g Release 11.1.1.x applications. The standalone skin editor enables you to select an Oracle JDeveloper target version when you create a skin. (Note that because some of the default skins available in Oracle JDeveloper 11g Release 11.1.2 are not available in previous Oracle JDeveloper versions, the skin editor hides the default skins that are unavailable in a target version.)

Frank Nimphius is a senior principal product manager for Oracle JDeveloper and Oracle Application Development Framework. He is a coauthor of Oracle Fusion Developer Guide: Building Rich Internet Applications with Oracle ADF Business Components and Oracle ADF Faces (McGraw-Hill, 2010).