Customizing Theme Properties

2 Configuring WEB-INF/web.xml

2.1 The com.sun.webui.theme.THEME_RESOURCES context-param

3 Creating Theme Properties Files

3.1 Java ResourceBundle Theme Properties Files

3.2 Javascript Theme Properties Files

3.3 Localization

3.3.1 Theme Resources Defined in ResourceBundle Properties Files

3.3.2 Theme Resources Defined in Javascript Files

4 Theme Properties

4.1 Application Page Theme Properties

4.2 Component Theme Properties

2 Configuring WEB-INF/web.xml

The ThemeContext interface defines several properties that affect the runtime environment of the Woodstock theme. These properties are supported by the ServletThemeContext concrete class and its JSF specialized subclass JSFThemeContext.

JSFThemeContext (which is used internally by the Woodstock components as the "default" ThemeContext implementation) implements the properties as context-param elements that can be declared in an application's web.xml file. The values of these context-param elements affect the runtime behavior of the theme. There are several parameters that can be defined that control different aspects of the theme behavior including, additional theme resource files, the default theme name, preferred theme version, default locale, theme factory implementation, and the theme servlet context. This chapter will discuss the com.sun.webui.theme.THEME_RESOURCES parameter which allows the application to define resources bundles. The theme properties defined in these resource bundles take precedence over the theme's definitions of these property values.

2.1 The com.sun.webui.theme.THEME_RESOURCES context-param

The com.sun.webui.theme.THEME_RESOURCES context-param is used to define theme resource bundles in the form of Java ResourceBundle Properties files and Javascript files formatted as JSON objects.

The context-param value is space separated sequence of strings in the form of package paths also referred to as ResourceBundle base names. The example web application defines the apptheme bundle in its web.xml file.

    <context-param>
	<param-name>com.sun.webui.theme.THEME_RESOURCES<param-name>
	<param-value>apptheme<param-value>
    <context-param>

The bundle base name apptheme resolves to WEB-INF/classes/apptheme.properties. Since the theme resource properties files are treated like Java ResourceBundle's the files must be located along the application's class path. It is preferable to locate the properties files and actual application theme resources, like image files or style sheets under the WEB-INF/classes directory instead of in a jar. This is to ensure that the application resources take precedence. If the resources were located in a jar file and they are not uniquely named, then there is no guarantee which resource would be referenced, since the ordering of the jars in the class path would take precedence. The theme infrastructure relies on the Servlet spec as it gives precedence to resources under WEB-INF/classes over jars in WEB-INF/lib.

3 Creating Theme Properties Files

The theme resource properties files that an application creates can contain any theme property that is defined in a theme jar or a component jar that defines theme properties and includes theme resources. The application defined properties override the default value of those theme defined properties.

3.1 Java ResourceBundle Theme Properties Files

Theme properties are formatted similarly to any Java ResourceBundle Properties file. The example web application defines the following Properties file, WEB-INF/classes/apptheme.properties

3.2 Javascript Theme Properties Files

The component set is currently transitioning to a new architecture. Originally JSF Renderers rendered HTML markup. JSF Renderers in the new architecture render Javascript statements and some HTML markup associated with those Javascript statements. The Javascript statements reference Javascript functions and properties that render the component programmatically in the browser, dynamically modifying the document. For example the button component in the example web application renders the following in the response.

<span id="_form1:discuss">
<script type="text/javascript">
    webui.suntheme@CACHEVERSION@.widget.common._createWidget('_form1:discuss',
	{"widgetType":"webui.suntheme@CACHEVERSION.widget.staticText",
	 "value":"This is suntheme static text. The following button is a suntheme primary button.",
	 "visible":true,
	 "escape":true,
	 "id":"form1:discuss"}
    );
</script>
</span>

The following is the Javascript equivalent of the apptheme.properties file. The format is a hierarchy of JSON objects.

1. The Javascript theme file must be located in a subdirectory called nls. The Javascript theme file in the example web application, apptheme.js, is located here. (See The NLS Directory Structure for more information)

   WEB-INF/classes/nls/apptheme.js
   

2. At this time, page level theme properties like Theme.stylesheet are not recognized by the Javascript theme implementation. Obviously there are some oddities in this scheme. Like, "Why should I have to duplicate the content of the 'apptheme.properties' file ?". The Theme customization is at an early phase of development, especially in the area of the Javascript theme. There are other inconsistencies as well. Some components have Javascript "widget" renderers and respect the Javascript theme and other components do not have Javascript "widget" renderers and only recognize the theme's Java ResourceBundle properties files. The theme properties table identifies all component properties and indicates which components have "widget" renderers. See suntheme.js for the actual Javascript theme.

3.2.1 Issues with JSF and the Default Locale

There is special case that must be handled when the JSF default locale is "en" and the server locale is not.

The Locale instance returned by JSF from a call to FacesContext.getCurrentInstance().getViewRoot().getLocale() sets the faces-config.xml default locale, as the preferred locale. The default locale in the returned Locale instance is the web server's or the JVM's locale.

The java.util.ResourceBundle.getBundle() fallback algorithm will defer to the "default" locale before returning the bundle defined with no variant. For example. If properties files, org.app.theme and org.app.theme_fr exist and the default JSF locale is "en" and the server's locale is "fr" java.util.ResourceBundle.getBundle() will return org.app.theme_fr when called with the Locale instance returned by FacesContext.getCurrentInstance().getViewRoot().getLocale().

In order for an application's theme properties file to be referenced in the above fallback case, the application must create an empty "en" properties file. That way if the default JSF locale or the server's locale is "en" the application defined properties will be found for locales that the application does not provide a locale variant for.

Note that "en" is identified in this section as the fallback language, because the Woodstock components use "en" as the fallback language. But if your application does not use "en" as the fallback language then you need an empty properties file variant consistent with the locale environments your application will run in.

For example if your fallback language is "fr" and org.app.theme is in "fr" then you need an empty org.app.theme_fr properties file when the default JSF locale is "fr" but the server's locale is not. or if the default locale is not "fr" but the server's locale is "fr".

3.3 Localization

All theme properties can have locale specific values. This is accomplished by providing locale variants of the Java ResourceBundle Properties files and the Javascript theme files that define the theme properties.

3.3.1 Theme Resources Defined in ResourceBundle Properties Files

Locale variants of the Java ResourceBundle Properties files follow the standard localized Java ResourceBundle file name pattern where the locale variant identifiers are added as a suffix to the file base name. For example, the simplified Chinese locale variant of the example web application's theme properties file name would be

WEB-INF/classes/apptheme_zh_CN.properties

3.3.2 Theme Resources Defined in Javascript Files

The implementation of the client Javascript theme utilizes Dojo to load localized Javascript theme files. Dojo defines a slightly different organization and naming pattern for locale variants. Javascript resource files are located in directory named nls with subdirectories named for the locale variants. Standard RFC 3066 locale and country codes are utilized but instead of "_" (underscore) a "-" (dash) is used to separate the language from the country code and the country code from the locale variant. By convention lowercase letters are used in the directory name. For a simplified Chinese Javascript theme properties file, the name and location would be as follows.

WEB-INF/classes/nls/zh-cn/apptheme.js

For a Javascript theme files
    WEB-INF/classes/org/business/applications/nls/zh-cn/apptheme.js

For a Java ResourceBunndle Properties file
    WEB-INF/classes/org/business/applications/apptheme_zh_CN.properties

4 Theme Properties

Note that Application Page Theme Properties are not recognized by the Javascript Theme implementation at this time.

4.1 Application Page Theme Properties

Application Page Theme Properties are theme properties that identify theme resources that must be loaded in every application page. Resources like CSS style sheets, and Javascript files. These properties can be a list of space separated paths that exist along the application's class path. The values must not include the protocol, schema, host or application context. For example, the following could be the definition of the Theme.stylesheet property in the theme's stylesheets.properties file.