About Packaging a Custom Look and Feel

A custom look and feel implementation can include a variety of resources, such as:

A look and feel XML configuration file (required)
Java classes
UIX XML templates
Images (icons)
Style sheets (.xss documents)

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

The ability of UIX to locate look and feel resources on the class path enables you to package all of your resources (including the look and feel configuration file, style sheet, images, and Renderers) in a single 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. It is, however, not required that you package your look and feel in a JAR file.

Depending on the resource type, UIX uses different ways to locate resources. Use the following sections (which describe the resource types and how UIX finds each type) to determine how you want to package your custom look and feel.

Look and Feel configuration file
Style sheets
Images
Renderers

Look And Feel configuration file

The path to the look and feel's configuration file is specified via the <look-and-feel-config> element in the UIX configuration file (uix-config.xml). UIX first interprets this specified path relative to the web application's context root. For example, if a custom look and feel is registered as follows:

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

UIX will first look for the for the mycompany-laf.xml configuration file under the web application's WEB-INF directory.

If UIX is unable to locate the look and feel configuration file under the servlet context root directory, UIX will also check to see if the look and feel is available on the class path. The reason for this behavior is to allow custom look and feels to be packaged as self-contained JAR files.

To take advantage of this functionality, the look and feel configuration file should be packaged in a JAR file and installed on the web application's class path. For example if the mycompany-laf.xml configuration file is installed in the org.example.laf.custom package, you register the custom look and feel by specifying the following path in the uix-config.xml file:

<look-and-feel-config>org/example/laf/custom/mycompany-laf.xml</look-and-feel-config>

Style sheets

The location of the look and feel's style sheet is specified via the style-sheet-name attribute of the <look-and-feel> element in the look and feel configuration file. UIX searches for styles sheets in three locations:

Under the UIX style sheet directory (/cabo/styles)
Under the web application's context root
On the web application's class path

If you wish to install your style sheet alongside UIX's own styles in the /cabo/styles directory, simply specify the file name. For example, if the mycompany.xss style sheet is installed under the /cabo/styles directory, the look-and-feel element should look like this:

<look-and-feel style-sheet-name="mycompany.xss" ... />

If you prefer to install the style sheet in a subdirectory under the context root, simply specify a path relative to the context root. For example, if the mycompany.xss style sheet is installed under the web application's /laf/styles directory, the style-sheet-name attribute should be set as follows:

<look-and-feel style-sheet-name="/laf/styles/mycompany.xss" ... />

Finally, if you prefer to package the custom look and feel in a JAR file, simply specify the path to the style sheet on the class path. For example, if the mycompany.xss style sheet is installed in a JAR file in the org.example.laf.custom.styles package, set the style-sheet-name attribute as shown below:

<look-and-feel style-sheet-name="org/example/laf/custom/styles/mycompany.xss" ... />

Images

The look and feel's images are specified using UIX's customizable icon architecture. Where UIX looks for the image files depends on the type of icons that are used when registering the images in the look and feel configuration file. UIX supports the following icon types, and looks for them in the appropriate locations:

<config-image> icon type - For images that are installed under the /cabo/images directory
<context-image> icon type - For images that are installed under the web application's context root

UIX also supports the <resource-image> icon type, which allows for icons to be packaged in the look and feel's JAR file. UIX looks for images that are registered using the <resource-image> icon type on the web application's class path. So, for example, if a custom "required" icon is placed in a JAR file under the org.example.laf.custom.images package, the following entry can be added to the look and feel configuration file to register such an image:


<icon name="required">
  <resource-image uri="org/example/laf/custom/images/required.gif"/>
</icon>

Then UIX will automatically locate the image on the class path and make it available to the browser.

Renderers

UIX supports two types of Renderers: Java-based Renderers and UIX XML template-based Renderers (i.e., .uit files). Java-based Renderers are loaded directly off of the web application's class path. For template-based Renderers, UIX first looks for them under the web application's context root, and then on the class path. For example, if your custom look and feel contains a custom template-based Renderer customPageLayout.uit for the pageLayout component, you would use the following entry to register the custom template in the look and feel configuration file:


<renderer name="pageLayout">
  <template name="/laf/templates/customPageLayout.uit"/>
</renderer>

And UIX will look for the template under the web application's /laf/templates directory. If the template is not found, UIX will also search the laf.templates package on the class path.

If you want to package the template in the org.example.laf.custom.templates package in your look and feel JAR file, you can specify the following entry to register the custom template:


<renderer name="pageLayout">
  <template name="org/example/laf/custom/templates/customPageLayout.uit"/>
</renderer>

Application Directory Structure

A typical application directory structure using custom resources could look like this:

|.....
|||+------<oc4j_install>/j2ee/home/applications
||||+-------myUIXApp
|||||+--------cabo
|...............[images, jsLibs, jsps, styles]
|...............[.xss files located in styles]
|||||+--------lib
|...............[look and feel JAR files]
|||||+--------META-INF
|...............application.xml
|||||+--------WEB-INF
|...............web.xml
|...............uix-config.xml
|||||+--------UIXWebApp1
|---------------[*.uix]
|||||||+--------cabo
|.................[auto generated during runtime]
|||||||+--------images
|||||||+--------includes
|||||||+--------jsLibs
|.................[JavaScript libraries]
|||||||+--------source
|.................[.java files]
|||||||+--------templates
|.................[*.uit]
||||||+---------WEB-INF
|.................[.xml look and feel configuration file]
|||||||+----------classes
|...................[any private classes]
|||||||+----------lib
|...................[any private JAR files used by the application]
|.................web.xml
|.................uix-config.xml
|.....

Note: If the custom look and feel resources are packaged in a JAR, you must add the JAR file to the class path in order for the application to use the custom resources. This can be accomplished locally for each application, or globally if you install the JAR file on the class path of the servlet engine.