Online Help for the ADF UIX Look and Feel Sample Application

What does this sample show

ADF UIX lets you change the appearance or look and feel of an application without having to rewrite the UIX code that implements the application's user interface. UIX provides two parent look and feels, Base Look and Feel and Simple Look and Feel, which you can extend to provide custom look and feels for your applications. By default a custom look and feel inherits the appearance of its parent look and feel. When you wish to modify the appearance of a component, you simply provide custom style definitions, custom icons, or a custom Renderer for that component.

This sample demonstrates how to create a simple ADF UIX look and feel, extending the Simple Look and Feel, that can replace the default Oracle Browser Look and Feel (BLAF) with Oracle JDeveloper 10g. For the easy of reading we will be referring to the look and feel with the term SKIN.

Why is this important

With ADF UIX you can apply a certain look or design to a component without adding code to the actual application during design-time. The new "design" will be applied when the component is used at runtime freeing the developer from even thinking about applying templates to the application. If a change is made to a particular component it will show immediately at runtime. No work for the application developer.

So how can we make this possible? The ADF UIX Components are based on a fundamental split:

UINodes - provide a logical representation of components
Renderers - provide a physical (e.g. HTML) implementation of component.

This split allows a page description to be defined independently of any markup, or even markup language. This allow us to write one component that can handle multiple agents e.g. different browsers, mobile devices. This also allows us to write new renderes - skins - for different agents separately from the actual development of our applications.

Prerequisites

In order to build this new ADF Skin you need the Oracle JDeveloper 10g production release - optionally you may need a image editor of you want to create and replace images provided by this sample.

ADF UIX Default Page Layout and Look and Feel

ADF UIX provides two main look and feels which are provided for you to use "as is" in your applications - Oracle Browser Look and Feel (BLAF) and Minimal Look and Feel (MLAF). It is not recommended that you change these two look and feels. The default look and feel for your application is set to BLAF, which conform to Oracle's UI standards for applications.

UIX also provides the following parent look and feel implementations, which you can use to provide custom look and feels:

Base Look and Feel - This is the root look and feel. All look and feels provided by UIX are extended from this Base Look and Feel.
Simple Look and Feel (SLAF) - This is an extension of the Base Look and Feel that exposes even more customization capabilities than the Base Look and Feel.

Checking out the ADF UIX sample project

There are several files needed in order to set and create a skin some of witch are mandatory and some optional.

ADF Skin specific files included in this sample

sample.xss - An XML stylesheet file that contains styles needed for our new ADF Skin. This sample.xss file extends the simple-desktop.xss file mentioned earlier.
pageLayout.uit - This is an ADF UIX template and is simply replacing the default renderer for the ADF UIX pageLayout component.
sidBar.uit - This is an ADF UIX template that replaces the default renderer for the ADF UIX sideBar component.
sample-laf.xml - This is the configuration file for the new ADF Skin. In this file we define what ADF Skin to override, what renderer to replace, and what custom icons to use for e.g. Tabs and ContentContainers.

Generic ADF UIX files

main.uix - A regular UIX XML file that contains some basic components. This file will be used to confirm the new ADF Skin.
uix-config.xml - This is the ADF UIX configuration file. This is where you set all parameters for the ADF UIX runtime e.g. debug, compression, and which look and feel to use.

Examine the code of the main.uix file

This is the main file - main.uix - that is used to illustrate changes to the application. You can, of course, add your own UIX XML files to this project and use them to test the new skin, but there is no guarantee that the skin provided with this sample will have all styles needed to render a consistent look and feel for all components used within your application.

Open the main.uix file in the visual editor. It should look like this:
Click on the Source tab at the bottom in order to change to the code view
Examine the code and make sure there are no styles applied to the page.
Here is an example of how a component using a style class would look like:

<messageStyledText styleClass="sampleLinkTable" text="My text"/>
As you can see there are no styles applied to the page, and there is only one image added - 10gwelcome.jpg - which is the current logo of this page.

Register the sample skin

Before an application can use a new skin there are changes to be made to the UIX configuration file - uix-config.xml. It is in this file you register the look and feel to use with a particular application.

How to register a skin

Locate the uix-config.xml file.
Open the file
First we need to register the sample-laf.xml file as our new skin.
At the top of the <application-configuration> section you will find the following comment and the registered sample look and feel.

<look-and-feels>
<look-and-feel-config>WEB-INF/sample-laf.xml</look-and-feel-config>
</look-and-feels>

Before we can use this custom skin we need to register a configuration for this new skin

At the bottom of the uix-config file you will find the following comment

<configuration name="sample">
<look-and-feel>sample</look-and-feel>
</configuration>

This will allow us to refer to the custom skin as "sample". The new Sample Skin is now registered and ready to be used.
In the <default-configuration> section set the <look-and-feel> configuration as follows:

Replacing the following statement:

<look-and-feel>blaf</look-and-feel>

With this statement

<look-and-feel>sample</look-and-feel>

We are now ready to test our application.
Save your work and Run your application.

Modifying the XSS stylesheet

There are multiple ways of defining a style for your application, you can create a regular CSS or XSS file and set the class attribute on your components directly in the page, or you can modify the base-desktop.xss and/or simple-desktop.xss file so that components automatically will pick up the style applied. Even though the previous options will work the recommended way is to extend the simple-desktop.xss file and not directly apply changes to the component/application or to the by JDeveloper provided XSS files - base-desktop.xss or simple-desktop.xss. This will provide a clean cut between the look and feel of your application and the actual application it self, allowing you to at any point change the Look and Feel of your application without touching the actual application code.

This section is just going to cover how to modify the custom XSS file - sample.xss - that extend the simple-desktop.xss.

Overriding styles in the simple-desktop.xss file

Each look and feel can define its own custom style sheet. The styles defined by the look and feel's custom style sheet are automatically layered on top of the styles defined by the parent look and feel. In this sample we created a custom look and feel that extends the Simple Look And Feel, the custom styles that we defined are layered on top of the Simple Look and Feel.

In the View project open the sample.xss file unless already open. The file is located in the pubic_html\sampleStyles\ directory.
The file is already populated with the basic styles that are needed in this sample.

<style name="DarkBackground">
<property name="background-color">#4c6c8f</property>
</style>

<style name="DarkAccentBackground">
<property name="background-color">#294563</property>
</style>

<style name="LightBackground">
<property name="background-color">#cfdced</property>
</style>

Modifying the Page Layout

This section illustrates how you can use ADF UIX templates to write simple but powerful renderers for particular components.

Open the pageLayout.uit file located in the template folder. This template overrides the default pageLayout component.
In the file locate a section that says the following:

<rowLayout>
<contents>

<cellFormat>
<contents>
   <image width="10" height="1" source="images/laf/sample/spacer.gif"/>
</contents>
</cellFormat>

<cellFormat>
<contents>
   <rowLayout>
    <contents>
     <messageTextInput columns="15" name="q" id="query"/>
     <spacer width="10"/>
     <submitButton text="Search"/>
    </contents>
   </rowLayout>
   <messageStyledText styleClass="sampleSearch" text="Use Google to Search"/>
</contents>
</cellFormat>

<cellFormat>
<contents>
<image width="10" height="1" source="images/laf/sample/spacer.gif"/>
</contents>
</cellFormat>

</contents>
</rowLayout>

This section adds a new area to the pageLayout component that will provide any pages using the pageLayout component with a Search field connected to Googles search engine.

Modifying the Look and Feel configuration file

This is the last piece of the puzzle, and this file contains all skin specific items that can be used to create a new skin - e.g. XSS file, Renderes, and Icons:

In the Navigator locate the sample-laf.xml file. The file can be found in the WEB-INF folder in the View project
Open the file.
In the <renderers> section note the following:

<renderer name="sideBar">
    <template name="templates/laf/sample/sideBar.uit"/>
    </renderer>

The above section adds a new renderer for our menu. The component that constructs the menu is called sideBar and in the project there is UIX template that modifies the renderer for this component.

In the <icons> section note the following:

<icon name="tabBarEnabledStart">
<context-image uri="images/laf/sample/tbes.gif"/>
</icon>

<icon name="tabBarSelectedStart">
<context-image uri="images/laf/sample/tbss.gif"/>
</icon>

<icon name="tabBarEnabledEnd">
<context-image uri="images/laf/sample/tbee.gif"/>
</icon>

<icon name="tabBarSelectedEnd">
<context-image uri="images/laf/sample/tbse.gif"/>
</icon>

<icon name="tabBarEnabledJoin">
<context-image uri="images/laf/sample/tbej.gif"/>
</icon>

<icon name="tabBarSelectedEnabledJoin">
<context-image uri="images/laf/sample/tbsej.gif"/>
</icon>

<icon name="tabBarEnabledSelectedJoin">
<context-image uri="images/laf/sample/tbesj.gif"/>
</icon>

<icon name="tabBarEnabledBackground">
<context-image uri="images/laf/sample/tbeb.gif"/>
</icon>

The icons section will add images where needed e.g. for the tab bars, logos, contentContainers

Packaging of a ADF UIX Skin

ADF UIX can locate resources that are installed as part of the web application, or locate them on the class path. As a result, you can deploy a custom look and feel in one of two ways:

As loose files embedded within a web application
As a self-contained JAR file

In this sample we have been using the first route with files embedded in the actual application project. This is done to better illustrate the capabilities of ADF UIX look and feel customization. The preferred and recommended way is to store your new skin in a self-contained JAR file. Creating a look and feel JAR file may be useful if you plan to deploy your look and feel across multiple web applications.

For more information about ADF UIX and ADF UIX Look and Feel, please refer to the online documentation available from the OTN JDeveloper website.