The Theme and Woodstock Web Applications - Version @THEMEVERSION@
[ Table of Contents | 0 Revision History | 1 Introduction | 2 Configuring THEME_RESOURCES | 3 Creating Properties Files | 4 Redefining Properties | 5 Creating Themes | 6 Configuring DEFAULT_THEME | 7 Runtime Theme Components | 8 PortalThemeTagLib | 9 com.sun.webui.jsf.theme | 10 com.sun.webui.theme | 11 Javascript Theme | Appendices ]

The Javascript Theme

11 The Javascript Theme

11.1 Generating the Javascript Theme

11.2 Javascript Theme Properties

11.2.1 themeBundle

11.2.2 themeModule

11.2.3 themeModulePath

11.3 The NLS Directory Structure

11 The Javascript Theme

The Javascript theme is a Javascript file formatted as a JSON object that contains all the theme properties from all the theme properties files. This format is required in order to use the DOJO localized Javascript resource file interfaces.

The Woodstock components are in a transitional phase where some components utilize HTML renderers that render HTML markup to display the components, and "widget" renderers that render minimal HTML markup and Javascript statements. The Javascript statements invoke Javascript methods that modify the document directly to display the components. This means that HTML renderers reference the theme on the server and Javascript implementations for the "widget" components reference the Javascript theme.

11.1 Generating the Javascript Theme

The Javascript theme is generated from the webui-jsf-suntheme.jar file using the "main" method of ResourceBundleTheme.java. 

% java -classpath ./webui-jsf.jar com.sun.webui.theme.ResourceBundleTheme -help
Usage: java com.sun.webui.jsf.theme.ResourceBundleTheme 
[-bundle messages|stylesheets|templates|properties|javascript|images|styles]
[-factory <ThemeFactory implementation class name>]
[-dir destination-directory]
[-themeModule <theme module javascript namespace>]
[-theme <theme name>]
[-version <theme version>]
[-locale <lang>[_<country>[_<variant>]]]
[-l10nJar "jar:file:<fullpath>/<jarname>_<lang>[_<country>[_<variant>]].jar!/"
[-prettyprint <indent>]

[-help]
'-bundle' - the properties file to process. If not specified, all properties
    bundles are processed. If 'bundle' is specified the file name is
    '<bundle>.js'.
'-factory' - the ThemeFactory implementation to use, to obtain a Theme
    instance. If not specified the 'com.sun.webui.theme.SPIThemeFactory'
    implementation is used.
'-dir' - the destination directory for the theme javascript file. The file
    created is named from the 'ThemeJavascript.THEME_BUNDLE' theme property 
    with an extension of '.js' If not specified the file is created in the
    current directory.

-l10nJar - the URI including the full path to l10n jar file. This value
    is used to create a URLClassLoader restricting the class path to this jar.
If '-themeModule' is not specified the 'ThemeJavascript.THEME_MODULE' theme
    property is used as the theme name space.
If '-theme' is not specified 'suntheme' is used. This theme is used as the
    source of the properties files.
If '-version' is not specified then '@THEMEVERSION@' is used.

The webui-jsf.jar and webui-jsf-suntheme.jar or equivalent theme jar
    must appear in the class path.

Note that if the '-bundle' and/or '-themeModule' options are specified,
    javascript must be written to load those files. The default 'Head' component
    behavior loads theme files based on the 'ThemeJavascript.THEME_BUNDLE',
    'ThemeJavascript.THEME_MODULE', and 'ThemeJavascript.THEME_MODULE_PATH'
    (or 'ThemeJavascript.THEME_MODULE_PATH_UNCOMPRESSED') theme properties.
This operation is performed by the themes/build.xml file after the webui-jsf-suntheme.jar file is created. The webui-jsf-suntheme.jar file is updated with the resulting Javascript theme file suntheme.js. 
% java -classpath ../webui/lib/external/json-2.jar:../webui/dist/webui-jsf.jar:\
./dist/webui-jsf-suntheme.jar com.sun.webui.theme.ResourceBundleTheme \
-dir build/suntheme/com/sun/webui/jsf/@SUNTHEMEPKGDIR@/javascript/theme/nls \
-theme suntheme
This process transforms the theme properties into a syntactically correct form for use in Javascript. This means that the parameter replacement format defined for properties files must be converted to a syntax suitable for the javascript stirng "replace" method.

The contents of the "widget" HTML template files are used as the value of the templates properties so that a request does not have to be made for the "widget" template HTML files. For the example the contents of the textField.html template becomes the value of the "templates" "textField" property instead of the resource location /com/sun/webui/jsf/@SUNTHEMEPKGDIR@/templates/textField.html.
From "suntheme.js" 

...
{
    ....,
    "templates" : {
        "textField": "<span dojoAttachPoint=\"domNode\"><span dojoAttachPoint=\" labelContainer\">
        <\/span><input dojoAttachPoint=\"fieldNode\" type=\"text\"><\/input><\/span>",
	...
    },
    ...
}
...

Unicode escape sequences are used for non-ascii characters.

11.2 Javascript Theme Properties

The DOJO localized resource file interfaces recognize resource files based on a bundle name, a module name and a path associated with that module. These properties are defined in javascript.properties.

11.2.1 themeBundle

The themeBundle property defines the actual resource file name. In the Woodstock suntheme the value is "suntheme" which translates to "suntheme.js".

11.2.2 themeModule

The themeModule property is used as a Javascript namespace. In the Woodstock suntheme the value is "webui.suntheme.theme".

11.2.3 themeModulePath

The themeModulePath and themeModulePathUncompressed properties refer to the parent directory path of the "nls" directory. DOJO organizes resource files differently than Java ResourceBundles as discussed in the next section. In the Woodstock suntheme this value is not set since the module path is the same as the initial module path set for other Javascript files and the themeModule is a superset of the modulePrefix. See DOJO for more information on how a module prefix and module path are used to identify Javascript resources and objects.

The uncompressed version of this property is the location of the Javascript theme that was JSON "pretty printed" meaning that properties are indented and newlines are used. This format convenient when debugging.

11.3 The NLS Directory Structure

DOJO organizes resource files differently than Java ResourceBundles. A directory is used to identify localized resources, vs. a suffix. The language, country and variant codes are in lower case and combined using a "-" (dash). This string is used to name subdirectories in the "nls" directory. For example: 

<themeModulePath>/<themeModule>/nls/<themeBundle>.js
<themeModulePath>/<themeModule>/nls/<language>/<themeBundle>.js
<themeModulePath>/<themeModule>/nls/<language>-<country>/<themeBundle>.js
<themeModulePath>/<themeModule>/nls/<language>-<country>-<variant>/<themeBundle>.js

For the Woodstock suntheme and a "ja" and "zh_CN" translation.

com/sun/webui/jsf/@SUNTHEMEPKGDIR@/javascript/theme/nls/suntheme.js
com/sun/webui/jsf/@SUNTHEMEPKGDIR@/javascript/theme/nls/ja/suntheme.js
com/sun/webui/jsf/@SUNTHEMEPKGDIR@/javascript/theme/nls/zh-cn/suntheme.js

Note that these paths would require the web application and theme
servlet context in order to download them. They are supplied at 
runtime to the Javascript "widget" library in the  rendered markup for the HEAD HTML element.
[ Table of Contents | 0 Revision History | 1 Introduction | 2 Configuring THEME_RESOURCES | 3 Creating Properties Files | 4 Redefining Properties | 5 Creating Themes | 6 Configuring DEFAULT_THEME | 7 Runtime Theme Components | 8 PortalThemeTagLib | 9 com.sun.webui.jsf.theme | 10 com.sun.webui.theme | 11 Javascript Theme | Appendices ]