(For more resources related to this topic, see here.)

Controlling appearance

An ADF Faces application is a modern web application, so the technology used for controlling the look of the application is Cascading Style Sheets (CSS).

The idea behind CSS is that the web page (in HTML) should contain only the structure and not information about appearance. All of the visual definitions must be kept in the style sheet, and the HTML file must refer to the style sheet. This means that the same web page can be made to look completely different by applying a different style sheet to it.

The Cascading Style Sheets basics

In order to change the appearance of your application, you need to understand some CSS basics. If you have never worked with CSS before, you should start by reading one of the many CSS tutorials available on the Internet.

To start with, let’s repeat some of the basics of CSS.

The CSS layout instructions are written in the form of rules. Each rule is in the following form:

selector { property: value; }

The selector function identifies which part of the web page the rule applies to, and the property/value pairs define the styling to be applied to the selected parts.

For example, the following rule defines that all <h1> elements should be shown in red font:

h1 { color: red; }

One rule can include multiple selectors separated by commas, and multiple property values separated by semicolons. Therefore, it is also a valid CSS to write the following line of code to get all the <h1>, <h2>, and <h3> tags shown in large, red font:

h1, h2, h3 { color: red; font-size: x-large; }

If you want to apply a style with more precision than just every level 1 header, you define a style class, which is just a selector starting with a period, as shown in the following line of code:

.important { color: red; font-weight: bold }

To use this selector in your HTML code, you use the keyword class inside an HTML tag. There are three ways of using a style class. They are as follows:

• Inside an existing tag: <h1>
• Inside the special <span> tag to style the text within a paragraph
• Inside a <div> tag to style a whole paragraph of text

Here are examples of all the three ways:

<h1 class="important">Important topic</h1>
You <span class="important">must</span> remember this.
<div class="important">Important tip</div>

In theory, you can place your styling information directly in your HTML document using the <style> tag. In practice, however, you usually place your CSS instructions in a separate .css file and refer to it from your HTML file with a <link> tag, as shown in the following line of code:

<link href="mystyle.css" rel="stylesheet" type="text/css">

Styling individual components

The preceding examples can be applied to HTML elements, but styling can also be applied to JSF components. A plain JSF component could look like the following code with inline styling:

<h:outputFormat value="hello" style="color:red;"/>

It can also look like the line of code shown using a style class:

<h:outputFormat value="hello" styleClass="important"/>

ADF components use the inlineStyle attribute instead of just style as shown in the following line of code:

<af:outputFormat value="hello" inlineStyle="color:red;"/>

The styleClass attribute is the same, as shown in the following line of code:

<af:outputFormat value="hello" styleClass="important"/>

Of course, you normally won’t be setting these attributes in the source code, but will be using the StyleClass and InlineStyle properties in the Property Inspector instead.

In both HTML and JSF, you should only use StyleClass so that multiple components can refer to the same style class and will reflect any change made to the style. InlineStyle is rarely used in real-life ADF applications; it adds to the page size (the same styling is sent for every styled element), and it is almost impossible to ensure that every occurrence is changed when the styling requirements change—as they will.

Building a style

While you are working out the styles you need in your application, you can use the Style section in the JDeveloper Properties window to define the look of your page, as shown in the following screenshot. This section shows six small subtabs with icons for font, background, border/outline, layout, table/list, and media/animation. If you enter or select a value on any of these tabs, this value will be placed into the InlineStyle field as a correctly formatted CSS.

When your items look the way you want, copy the value from the InlineStyle field to a style class in your CSS file and set the StyleClass property to point to that class. If the style discussed earlier is the styling you want for a highlighted label, create a section in your CSS file, as shown in the following code:

.highlight {background-color:blue;}

Then, clear the InlineStyle property and set the StyleClass property to highlight. Once you have placed a style class into your CSS file, you can use it to style the other components in exactly the same way by simply setting the StyleClass property.

We’ll be building the actual CSS file where you define these style classes.

InlineStyle and ContentStyle

Some JSF components (for example, outputText) are easy to style—if you set the font color, you’ll see it take effect in the JDeveloper design view and in your application, as shown in the following screenshot:

Other elements (for example, inputText) are harder to style. For example, if you want to change the background color of the input field, you might try setting the background color, as shown in the following screenshot:

You will notice that this did not work the way you reasonably expected—the background behind both the label and the actual input field changes. The reason for this is that an inputText component actually consists of several HTML elements, and an inline style applies to the outermost element. In this case, the outermost element is an HTML <tr> (table row) tag, so the green background color applies to the entire row.

To help mitigate this problem, ADF offers another styling option for some components: ContentStyle. If you set this property, ADF tries to apply the style to the content of a component—in the case of an inputText, ContentStyle applies to the actual input field, as shown in the following screenshot:

In a similar manner, you can apply styling to the label for an element by setting the LabelStyle property.

Unravelling the mysteries of CSS styling

As you saw in the Input Text example, ADF components can be quite complex, and it’s not always easy to figure out which element to style to achieve the desired result. To be able to see into the complex HTML that ADF builds for you, you need a support tool such as Firebug. Firebug is a Firefox extension that you can download by navigating to Tools | Add-ons from within Firefox, or you can go to http://getfirebug.com.

When you have installed Firebug, you see a little Firebug icon to the far right of your Firefox window, as shown in the following screenshot:

When you click on the icon to start Firebug, you’ll see it take up the lower half of your Firefox browser window.

Only run Firebug when you need it

Firebug’s detailed analysis of every page costs processing power and slows your browser down. Run Firebug only when you need it. Remember to deactivate Firebug, not just hide it.

If you click on the Inspect button (with a little blue arrow, second from the left in the Firebug toolbar), you place Firebug in inspect mode. You can now point to any element on a page and see both the HTML element and the style applied to this element, as shown in the following screenshot:

In the preceding example, the pointer is placed on the label for an input text, and the Firebug panels show that this element is styled with color: #0000FF. If you scroll down in the right-hand side Style panel, you can see other attributes such as font-family: Tahoma, font-size: 11px, and so on.

In order to keep the size of the HTML page smaller so that it loads faster, ADF has abbreviated all the style class names to cryptic short names such as .x10. While you are styling your application, you don’t want this abbreviation to happen. To turn it off, you need to open the web.xml file (in your View project under Web Content | WEB-INF). Change to the Overview tab if it is not already shown, and select the Application subtab, as shown in the following screenshot:

Under Context Initialization Parameters, add a new parameter, as shown:

• Name: org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION
• Value: true

When you do this, you’ll see the full human-readable style names in Firebug, as shown in the following screenshot:

You notice that you now get more readable names such as .af_outputLabel. You might need this information when developing your custom skin.

Conditional formatting

Similar to many other properties, the style properties do not have to be set to a fixed value—you can also set them to any valid expression written in Expression Language (EL). This can be used to create conditional formatting.

In the simplest form, you can use an Expression Language ternary operator, which has the form <boolean expression> ? <value if true > : <value if false>. For example, you could set StyleClass to the following line of code:

#{bindings.Job.inputValue eq 'MANAGER' ? 'managerStyle' :
  'nonManagerStyle'}

The preceding expression means that if the value of the Job attribute is equal to MANAGER, use the managerStyle style class; if not, use the nonManagerStyle style class. Of course, this only works if these two styles exist in your CSS.

Skinning overview

An ADF skin is a collection of files that together define the look and feel of the application. To a hunter, skinning is the process of removing the skin from an animal, but to an ADF developer it’s the process of putting a skin onto an application.

All applications have a skin—if you don’t change it, an application built with JDeveloper 12c uses some variation of the skyros skin.

When you define a custom skin, you must also choose a parent skin among the skins JDeveloper offers. This parent skin will define the look for all the components not explicitly defined in your skin.

Skinning capabilities

There are a few options to change the style of the individual components through their properties. However, with your own custom ADF skin, you can globally change almost every visual aspect of every instance of a specific component.

To see skinning in action, you can go to http://jdevadf.oracle.com/adf-richclient-demo. This site is a demonstration of lots of ADF features and components, and if you choose the Skinning header in the accordion to the right, you are presented with a tree of skinnable components, as shown in the following screenshot:

You can click on each component to see a page where you can experiment with various ways of skinning the component.

For example, you can select the very common InputText component to see a page with various representations of the input text components. On the left-hand side, you see a number of Style Selectors that are relevant for that component. For each selector, you can check the checkbox to see an example of what the component looks like if you change that selector. In the following example, the af|inputText:disabled::content selector is checked, thus setting its style to color: #00C0C0, as shown in the following screenshot:

As you might be able to deduce from the af|inputText:disabled::content style selector, this controls what the content field of the input text component looks like when it is set to disabled—in the demo application, it is set to a bluish color with the color code #00C0C0. The example application shows various values for the selectors but doesn’t really explain them. The full documentation of all the selectors can be found online, at http://jdevadf.oracle.com/adf-richclient-demo/docs/skin-selectors.html. If it’s not there, search for ADF skinning selectors.

On the menu in the demo application, you also find a Skin menu that you can use to select and test all the built-in skins. This application can also be downloaded and run on your own server. It could be found on the ADF download page at http://www.oracle.com/technetwork/developer-tools/adf/downloads/index.html, as shown in the following screenshot:

Skinning recommendations

If your graphics designer has produced sample screens showing what the application must look like, you need to find out which components you will use to implement the required look and define the look of these components in your skin.

If you don’t have a detailed guideline from a graphics designer, look for some guidelines in your organization; you probably have web design guidelines for your public-facing website and/or intranet.

If you don’t have any graphics guidelines, create a skin, as described later in this section, and choose to inherit from the latest skyros skin provided by Oracle. However, don’t change anything—leave the CSS file empty. If you are a programmer, you are unlikely to be able to improve on the look that the professional graphics designers at Oracle in Redwood Shores have created.

The skinning process

The skinning process in ADF consists of the following steps:

1. Create a skin CSS file.
2. Optionally, provide images for your skin.
3. Optionally, create a resource bundle for your skin.
4. Package the skin in an ADF library.
5. Import and use the skin in the application.

In JDeveloper 11g Release 1 ( 11.1.1.x) and earlier versions, this was very much a manual process. Fortunately, from 11g Release 2, JDeveloper has a built-in skinning editor.

Stand-alone skinning

If you are running JDeveloper 11g Release 1, don’t despair. Oracle is making a stand-alone skinning editor available, containing the same functionality that is built into the later versions of JDeveloper. You can give this tool to your graphic designers and let them build the skin ADF library without having to give them the complete JDeveloper product.

ADF skinning is a huge topic, and Oracle delivers a whole manual that describes skinning in complete detail. This document is called Creating Skins with Oracle ADF Skin Editor and can be found at http://docs.oracle.com/middleware/1212/skineditor/ADFSG.

Creating a skin project

You should place your skin in a common workspace. If you are using the modular architecture, you create your skin in the application common workspace. If you are using the enterprise architecture, you create your enterprise common skin in the application common workspace and then possibly create application-specific adaptations of that skin in the application common workspaces.

The skin should be placed in its own project in the common workspace. Logically, it could be placed in the common UI workspace, but because the skin will often receive many small changes during certain phases of the project, it makes sense to keep it separate. Remember that changing the skin only affects the visual aspects of the application, but changing the page templates could conceivably change the functionality. By keeping the skin in a separate ADF library, you can be sure that you do not need to perform regression testing on the application functionality after deploying a new skin.

To create your skin, open the common workspace and navigate to File | New | Project. Choose the ADF ViewController project, give the project the name CommonSkin, and set the package to your application’s package prefix followed by .skin (for example, com.dmcsol.xdm.skin).