How To create a Look and Feel for ADF UIX

An Oracle JDeveloper How To Document
Written by Jonas Jacobi
April 2004

Content

Introduction

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

For more information and HowTos, please, refer to the JDeveloper HowTo documents on Oracle Technology Network (OTN). For this simple application we are using ADF UIX, Struts, and ADF Business Components.

Tasks

This session covers the following tasks:

Prerequisites

In order to follow this HowTo and 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 HowTo. You also need to download this project - ADFUIX_LAF_sample -  that contains a simple ADF UIX page that we will use through the HowTo to show the effect the new LAF will have on a ADF UIX application.

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:

The below picture illustrates the BLAF skin that is applied by default and also the default page layout:

Structure of page

From left to right we have at the top a Corporate logo added by the developer that built this page, underneath we have what is called PageHeaders - JDeveloper 10g Production and JDeveloper 10g Preview. Below the PageHeader we have the sideBar, which is the menu that contains our links. In the center section we have the actual page contents. To the right from the top down we have GlobalButtons (a link for Feedback), underneath there are three tabs - Home, Collateral, and Sales. The last piece is the contentContainer that in this layout is rendered to the right of the main content.

Apart from changing the color and images of the application we can also re-organize the actual layout of the page, or any component for that matters.

New Skin

The below image illustrates how our application, from above, will look when we are done with this How To.

As you can see we have moved around pieces, removed what should not be there, and added components that is not part of the actual application. The GlobalButton (Feedback) has moved to above the Corporate logo, tabs have been pushed to the right. We have also removed the logo added by the developer and replaced it with a new logo. There is also a new section in the right upper corner that will be used for searching the Internet.

Nothing of the above has been hard coded in to the actual application. The clean separation of the UI and the actual application allow developers to concentrate on the actual content of the page rather then the look of the page. You can easily change skin by changing the UIX configuration file - uix-config.xml.

Getting started

Before we go on the path to create our first look and feel we need to download and the extract the ADFUIX_LAF_sample zip file. Extract the file in your working directory - e.g. C:\mywork 

Open an existing Application Workspace

  1. Open an existing Application workspace (File -> Open)


     
  2. Select the ADFUIX_LAF_sample.jws file located in you work directory.
  3. Click OK.
    Info: You can use the Edit Templates... button to change the names of your projects and define the technology scope for each project.)

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. This project contains some already predefined files that we will use and extend to meet our ADF Skin goals.

ADF Skin specific files included

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

Running the Sample Application

This How To contains all files that are need to change the default look and feel to something else. There are pieces missing that we will add during the progress of this HowTo. But, first let us run the application with the default settings to make sure that everything works, and then we will change the configuration so that it uses the new sample skin.

Examine the code of the main.uix file

This is the main file - main.uix - that will be 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.

  1. Open the main.uix file in the visual editor. It should look like this:


     
  2. Click on the Source tab at the bottom in order to change to the code view
  3. Examine the code and make sure there are no styles applied to the page.
    Here is an example of a component using a style class:

    < messageStyledText styleClass="sampleLinkTable" text="My text"/>
     
  4. 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.
  5. Run the page by right clicking on the page in the Navigator Window, and select Run

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

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

    <!-- Register a custom look and feel -->

  1. Copy and paste the below statement underneath the comment

<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

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

<!-- Register a configuration for each custom LAF -->

  1. Copy and paste the following configuration underneath the 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: 

  1. Replacing the following statement:

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

  1. With this statement

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

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

Your application should look like the picture below, and as you can see there are several pieces missing in order for this application to look at least as good as with the Oracle BLAF skin.

What we can see in this picture is that the logo added to the main.uix page has been overriden and replaced with a new logo.

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 HowTo we will create a custom look and feel that extends the Simple Look And Feel, the custom styles that we define are layered on top of the Simple Look and Feel.

  1. 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 some basic styles that are needed in this HowTo.
  2. Add the following Styles to the sample.xss file.

<!-- Change the dark core color from green to darkblue -->
<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>

  1. Save your work and Run your application.
    There should now be some improvements to the page.

Modifying the Page Layout

This lesson will illustrate how you can use ADF UIX templates to write simple but powerful renderers for particular components. Most of the work has been done already, but there is a piece missing, which is the Search area all our applications should have per default.

  1. Open the pageLayout.uit file located in the template folder
  2. In the file locate a section that says the following:

<!-- Add your code between this comment ... -->

<!-- And this comment -->

  1. In this section copy the following code that will add a Search field to all applications using this skin.

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

  1. Save your work and Run the application

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 order for our application to be complete we need to add the following sections to the configuration file:

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

    <!-- Register a custom sideBar Renderer -->
    <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.

  1. In the <icons> section add the following:

<!-- Provide some tabBar icons -->
<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

  1. Save your work and Run your application
    Your application should now look like this:

 

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:

In this How To 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.

false ,,,,,,,,,,,,,,,