Wednesday February 08, 2006

Rough Guide: Editing Themes for Creator 2.0

The components that ship with Java Studio Creator 2.0 derive their look and feel, and in some cases, their behavior, from a theme. At the most basic level, a theme is simply a JAR file that contains resources such as CSS stylesheets and graphical icons.

An easy way to create your own look and feel is to edit the contents of the default Creator theme. The following guidelines explain how to do it.

A theme JAR file has three main types of content:

• manifest file: information about the theme's name, version, prefix, and locations of properties and resources
• properties files: a map of theme keywords to theme resources, used by the theme manager to location theme resources
• resource files: the images, Javascript files, CSS stylesheets, and messages that constitute the theme itself

You'll find a copy of the default theme jar (defaulttheme.jar) in the Creator install directory, under rave2.0/modules/ext. Or, after you have deployed an application, in the application directory build/web/WEB-INF/lib.

Expand the file into a new directory. Users of M$ Windows may find it more convenient to rename defaultheme.jar to defaulttheme.zip, so that they can expand its contents using the Explorer.

Step One: Updating the manifest

The first thing to do is to give your theme a name, and to edit the manifest accordingly. I'll start by renaming the Creator default theme, from defaulttheme to isopaleocopria. The theme name is given in the manifest entry X-SJWUIC-Theme-Name. At the same time, I'll modify the package names for the various resources so that they are based on a namespace that I own.

Here's the new manifest:

    Manifest-Version: 1.0
    Ant-Version: Apache Ant 1.6.2
    Created-By: 1.4.2_07-b05 (Sun Microsystems Inc.)

    Name: com/sun/rave/web/ui/theme/
    X-SJWUIC-SWAED-Version: 3.0
    X-SJWUIC-Theme-Version: 1.0
    X-SJWUIC-Theme-Name: isopaleocopria
    X-SJWUIC-Theme-Prefix: /theme
    X-SJWUIC-Theme-Messages: org.isopaleocopria.themes.messages.messages
    X-SJWUIC-Theme-Images: org.isopaleocopria.themes.properties.images
    X-SJWUIC-Theme-JavaScript: org.isopaleocopria.themes.properties.javascript
    X-SJWUIC-Theme-Stylesheets: org.isopaleocopria.themes.properties.stylesheets

A few important points about the manifest:

• To be a valid theme JAR, the manifest must contain an attributes section named "com/sun/rave/web/ui/theme/"
• The attibute X-SJWUIC-Theme-Name must be present, and it must contain a unique name (a name not used by any themes already loaded into Creator).
• The last four entries are package names that must correspond to property files in the theme JAR. For example, org.isopaleocopria.themes.properties.images should correspond to the file org/isopaleocopria/themes/properties/images.properties. Do not edit the keys in these property files!

If the above conditions are not met, Creator will reject the theme.

Nota Bene: According to the spec, lines in a JAR manifest file are limited to a maximum length of 72 bytes. When you extract and first open the manifest for editing, you may notice that some lines longer than 72 bytes have been wrapped, and the enjambed portion has been indented with a single space character. You'll need to patch these lines back together again before reconstituting the JAR or ZIP file.

Step Two: Editing theme content

Before editing the content, you'll want to move it to your own package. In order for the theme manager to find the content in its new location, you'll need to update the path values in the various property files listed above. For example, as part of developing my new theme I would move the Javascript file /com/sun/rave/web/ui/defaulttheme/javascript/table.js to org/isopaleocopria/themes/javascript/table.js, and update the corresponding value in the javascript.properties file.

After updating the theme name and the locations of the property files, it's time to edit the theme content. In some cases, the key names in the property files will help you to identify which theme artifact belongs to which component. The CSS stylesheets also generally use a truncated version of the name of the component as the prefix of style class names that apply to the component.

Step Three: Importing the edited theme into Creator

When you are finished modifying the theme content, you will need to repackage the contents as a JAR or ZIP file which can then be imported into Creator.

To import the theme file, start Creator and open or create a project. From the menu, open Tools -> Library Manager. Select the Theme Libraries section, and click on "New Library". Give the library a name, e.g. IsoPaleoCopria (note that spaces are not accepted, probably a bug), and add the theme JAR or ZIP file to the library's classpath and to its runtime, using the appropriate tabs.

Finally, to apply the theme to the current project, select it in the project hierarchy, right-click, and choose "Apply Theme".

Have fun! (2006-02-08 15:36:48.0) Permalink