The Theme and Woodstock Web Applications - Version @THEMEVERSION@

1 Introduction

This document will try to introduce the features and capabilities of the Woodstock Theme implementation. The expectation is that the developer will be able to perform the following tasks with the help of this document. But this document is not intended to be the only resource needed to successfully perform these tasks. For example creating a component jar with theme support or creating a theme will most likely require more intimate knowledge of the theme implementation including reading java documentation and source code.

Modify theme characteristics at the application level.
Understand how theme properties for components can be defined and delivered in a jar file or application
Understand how to create a new theme distinct from webui-jsf-suntheme.jar. This is a very difficult task and this document cannot guarantee that a successful alternate theme can be created that drastically alters the theme implementation from the standard webui-jsf-suntheme.jar implementation.

Some History and Setting Expectations

Software begins its life attempting to satisfy a specific set of requirements. Over time those requirements change and the software is sometimes used in environments or with expectations that are not addressed by the original requirements. It is then modified as time and resources allow to try and meet the needs of the new requirements.

The Woodstock Theme is such software. It began as a mechanism to encapsulate a "brand" and to allow brand changes to be accommodated with as little change as possible to component implementations. The intent was to ensure that all applications using the components expressed a particular brand. An application could express a new brand, by replacing the old theme jar with the new one; no recompilation was necessary and in some cases the web application did not have to be redeployed or re-released. This is a different problem than allowing an application to be "skinned" and allowing the "skin" to be changed at will. Such a feature needs a sophisticated level of abstraction and data organization to make it effortless to utilize and create alternate "skins".

It is important to set expectations about the Theme so that effort is not wasted trying to accomplish very difficult tasks. Some theme modifications can be accomplished fairly easily and some require herculean efforts. For example changing a particular image from one file to another is simple and straight forward but changing the location of that image within a complex component is not as simple and straight forward.

1.1 What is a Theme ?

Logically speaking, the Woodstock Theme is a set of characteristics that express a consistent look across the set of Woodstock components. For example the theme implemented in webui-jsf-suntheme.jar expresses the current SUN brand as defined by the SWAED (Sun Web Application Experience Design) 4.0 guidelines.

The definition of the theme is purposely restricted to "look" or "skinnable" characteristics to set expectations appropriately given the current theme implementation. In reality the brand includes layout and interaction as well, but it requires much more effort to include that set of characteristics as "skinnable", since the work required is more than just a change to a property value.

1.2 The Theme Resources

The Woodstock Theme is implemented as a set of properties defined in Java ResourceBundle Properties files that represent the following categories:

Image properties that define an image file, width, height and alt text.
Message properties for button text, tool tips, etc, and in some cases data (mostly because we didn't create a "data.properties") and in most cases these data properties are not translated, unlike textual properties.
CSS properties that define "style classes" or CSS selectors and CSS style sheet files that must be included in an application page.
Javascript properties which define Javascript name spaces and Javascript files that must be included in an application page.
Template properties that define an HTML file or the literal HTML used as a template for components that are implemented as Javascript "widgets".

All categories of characteristics can be localized as necessary, meaning that any theme property can have a different value based on locale.

1.3 The Theme Infrastructure

The " Theme Infrastructure" is a "catch all" phrase for the Java classes and in some cases Javascript code that implements the behavior that provides the values of the theme properties to web applications and the Woodstock components at runtime.

This behavior is defined by interfaces and concrete classes defined and implemented in the com.sun.webui.theme package. These classes define how Theme properties are found and delivered to the web application and Woodstock components at runtime.

The ThemeServlet which is used to provide theme resources like image files, css files, etc. to the browser client.
The ThemeContext which is a class that attempts to encapsulate the runtime theme environment for web applications and components.
An implementation of ThemeFactory SPIThemeFactory.

1.4 To Give Feedback

Feedback can be provided by sending email to the following alias. woodstock-dev@sun.com.