An Oracle JDeveloper How To Document
Written by Jonas Jacobi
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.
This session covers the following tasks:
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 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:
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.
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.
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
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.
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.
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.
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.
<!-- Register a custom look and feel -->
Before we can use this custom skin we need to register a configuration for this new skin
<!-- Register a configuration for each custom LAF -->
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:
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.
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.
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.
<!-- Change the dark core color from green to darkblue -->
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.
<!-- Add your code between this comment ... -->
<!-- And this comment -->
<image width="10" height="1" source="images/laf/sample/spacer.gif"/>
<messageTextInput columns="15" name="q" id="query"/>
<messageStyledText styleClass="sampleSearch" text="Use Google to Search"/>
<image width="10" height="1" source="images/laf/sample/spacer.gif"/>
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:
<!-- Register a custom sideBar 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.
<!-- Provide some tabBar icons -->
The icons section will add images where needed e.g. for the tab bars, logos, contentContainers
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.