Creating a Theme for the Woodstock Components

5 Creating a Theme

5.1 Cloning an Existing Theme with themes/build.xml

5.2 More than One Theme Jar in WEB-INF/lib

6 Configuring WEB-INF/web.xml

6.1 The com.sun.webui.theme.DEFAULT_THEME init-param

5 Creating a Theme

Creating a theme is a very difficult and time consuming task. There are a large number of CSS selectors, images, Javascript files, and HTML templates that are all interrelated. A change to one can have undesirable effects on another. For example a CSS selector definition and Javascript may be dependent on the HTML used to represent a component. It might be that the only way to effect a particular look is to change the HTML in addition to the CSS. This can be problematic for many of the Woodstock components because the HTML exists in JSF renderers written in Java. The HTML is written to the response programmatically. To change the rendered HTML, a subclass of the component's Renderer must be created and configured in the JSF render kit, and associated to a particular component. The details necessary for performing this level of customization is beyond the scope of this document.

Some components are rendered using "widget" renderers which depend on an HTML template file that defines the HTML for the component. But many of these templates are sparse and generic and most of the document construction happens programmatically in Javascript, which depends on the HTML structure in the template. Changing these templates is beyond the scope of this document. However the techniques described in this document can be used to "override" the default HTML template, if only cosmetic changes to the template are needed and do not interfere with the logic implemented in Javascript.

There are a large number of images that are tightly bound to colors used in the CSS selector definitions. A seemingly simple color change to a CSS selector definition, may not be sufficient since there may be an image defined as part of that selector that needs to be modified to reflect the new color.

Even changing font size may result in layout problems because the branding design of the HTML may not have considered a change in font size.

Some effort has been made to organize the theme resources in such a way that a "new branding" is possible. For example many selectors are named based on the components that reference them. CSS style sheets have been organized as "layout", "colorAndMedia", and "typography". However there are many implicit dependencies that may result in undesirable effects if a change is made to only one of these style sheets.

It is recommended that theme changes for an application be made as discussed previously. If a new theme is absolutely required the following sections will try and descibe how to attempt it.

Disclaimer: It must be understood that the content of a theme is tightly bound to the version of the Woodstock components. No guarantee can be made that a theme created based on a given version of the components can be used WITHOUT MODIFICATION with a later version of the components.

5.1 Cloning an Existing Theme with themes/build.xml

If creating a new theme is absolutely the only means necessary to accomplish the desired goal then the approach is to clone the base theme defined in webui-jsf-suntheme.jar and modify files and properties as necessary. It is highly recommended that only the "skin" be modified. This includes only those properties that affect color and typography. If images need changing then the sizes should be maintained. Any changes to layout cannot be guaranteed to be effective unless Java code and or Javascript is adjusted to accommodate the new layout.

The themes/build.xml ANT script can be used to create a clone of the "suntheme". A clone means that the contents will be exactly the same as the "suntheme" except that the "suntheme" name will be changed to the new theme name. All paths will be redefined as well. To configure a new cloned theme, a properties file is used to specify the new values. In the following table the properties in bold type must be specified in the properties file, and those not in bold type are optional.

ANT Property	Suntheme value	Description
theme.name	suntheme	The Theme name. "suntheme" must not be used.
theme.src	src/suntheme	The directory to build when the buildTheme target is used.
theme.clone-src	src/suntheme	The root of the theme resources to clone.
theme.build-dir	build/suntheme	The temporary build destination for theme files.
theme.l10n-dir	./src/suntheme/translatedFiles	The directory that contains locale dependent resources. The subdirectory structure reflects the directory structured of src/suntheme with respect to the resource paths. For example for a "ja" locale there would be a "messages/messages_ja.properties" file under this directory. Only under rare circumstances are resources, other than messages.properties localized.
theme.jar	dist/webui-jsf-suntheme.jar	The destination path including the jar name for the theme jar.
theme.version	@THEMEVERSION@	The theme version as reported by the ThemeService implementation. This value must be the same as the theme that is being cloned.
theme.package	com.sun.webui.jsf.suntheme	The resouce's package path, any paths are derived from this value, i.e com/sun/webui/jsf/suntheme. "com.sun.webui.jsf.suntheme" must not be used.
theme.css-name	_sun4	An identifier that effects a name space for all CSS selectors. "_sun4" must not be used.
theme.service-class	SunthemeThemeService	The Java class name of the ThemeService SPI implementation. SunthemeThemeService must not be used.
theme.service-class-template	src/suntheme/com/sun/webui/jsf/suntheme/SunthemeThemeService.java	The name of a Java file to use a template to create the implementation of ThemeService. META-INF/services/SunthemtThemeService.java is the default template, if this property is not specified.
theme.service-properties-template	src/suntheme/com/sun/webui/jsf/suntheme/suntheme.properties	The name of the Java ResourceBundle Properties file to use as a template that defines the infomation about the theme and is returned by the ThemeService implementation. META-INF/services/suntheme.properties is the default template, if this property is not specified.
theme.clone-dir	No equivialent value.	The destination directory for the root of cloned theme files.
theme.clone-filter	No equivialent value.	If this value is true the cloned files will be filtered and tokens will be replaced with values. For example the "@THEME_CSS@" token in the style sheets will be replaced with the value of theme.css-name property. It is not recommended to set this value to true. Substitution will take place when the theme is built. Leaving the tokens unresolved in the clone allows comparisons to be made more easily to new versions of the suntheme, easing the port to a newer theme.
theme.clone-overwrite	No equivialent value.	If this value is true an existing clone at theme.clone-dir will be overwriiten when the cloneTheme target is called with the same properties file in effect. Only files that differ from the files being cloned will be overwritten. It is advised that this property be set to false or not specified, to prevent losing edits unintentionally.

The following is the contents of the themes/theme-name.properties.sample ANT properties file.

Once this properties file is created it is named after the new theme name with the "properties" suffix. ant is then invoked with the -D option defining the theme.name property. This is a little redundant in that the theme.name property in the properties file is technically not necessary. For example

Assume the theme-name.properties.sample properties file was renamed
to "mojave.properties".

% ant -Dtheme.name=mojave cloneTheme buildTheme buildJsTheme

This command will create the clone at "/tmp/theme/src/mojave", build
the theme in "/tmp/theme/build/mojave" and generate the theme jar
/tmp/theme/dist/webui-jsf-mojave.jar.

% ant -Dtheme.name=mojave

5.2 More than One Theme Jar in WEB-INF/web.xml

Theme resources are delivered in a jar file. This requires that the jar file appear on an application's class path. Since the jar file resides in the application's WEB-INF/lib directory it does appear on the class path. However there is no specified order of the jars that are found on an application's class path.

When more than one theme jar file or a component jar file that contains an implmentation of ThemeService appears on an application's class path it cannot be determined which theme resources will be in effect when running the application. The choice is determined by the ThemeFactory implementation. The default implementation is the SPIThemeFactory class. In brief, its policy, when a specific theme is not requested, is to provide a list of theme resources ordered based on the order of responses to its requests for ThemeService SPI. Essentially the first ThemeService implementation to respond to a call for this service, becomes the "default" theme and its resources are used by the Woodstock components. The actual policy is a little more involved than this. See SPIThemeFactory for more details.

However internally in the ThemeUtilities class, used by all Woodstock components, a specific version is always spefied in calls to getTheme. (As of this writing it is "@THEMEVERSION@"). Therefore, the first theme that satisfies the version requirement is used by the components.

6 Configuring WEB-INF/web.xml

Similar to the discussion in Configuring WEB-INF/web.xml an application can affect the theme chosen by the SPIThemeFactory and therefore determine the Theme used by the Woodstock components.

6.1 The com.sun.webui.theme.DEFAULT_THEME context-param

The com.sun.webui.theme.DEFAULT_THEME context-param is used to define theme preferred theme by name that should be loaded by the ThemeFactory. The value of this parameter is stored in the ThemeContext and is referenced by the ThemeFactory for theme requests that do not explicitly request a theme name. The Woodstock components do not explicitly specify a theme name in its calls to getTheme.

If an application has the cloned theme "mojave" as produced in Cloning an Existing Theme with themes/build.xml in its WEB-INF/lib directory it could name that theme as the "default" theme for its application, as follows

    <context-param>
	<param-name>com.sun.webui.theme.DEFAULT_THEME<param-name>
	<param-value>mojave<param-value>
    <context-param>