Understanding the Theming Subsystem

This page is under construction, so we cannot guarantee the accuracy of the content!

Overview

The collection of the components' stylesheets and associated images is called a theme. Theme controls the overall look and feel of a page composed of ZK components. For example, all the components using the standard sapphire theme have the same blue-ish glow appeal.

Starting from ZK 6.5.2, supporting different themes take a more modularized approach. Theming subsystem breaks up into a few pluggable modules: ThemeRegistry, ThemeResolver, and ThemeProvider. Customizing these modules enable web developers to modify the any part of the theme support subsystem.

Information about a Theme

Available in ZK 6.5.2+

Apart from having a name, a theme could be associated with many attributes. Encapsulating theme-specific attributes is defined in Theme. Each theme should have at least a name, which helps the web application to identify it. Web developers should extend this class to define other attributes associated with concrete themes, such as file paths included in a theme, or variables that could be used to parameterize a theme.

Standard themes have additional attributes like a more descriptive name for displaying purposes, a priority value to help the system choose the theme to use, and a origin of the theme's resources (i.e. CSS and image files). Standard theme information is provided by StandardTheme

import org.zkoss.web.theme.Theme;

public class MyTheme extends Theme {
    // theme-specific attributes
    ...
    // getters/setters
    ...
}

Registering your Theme

Before using a theme, it must be registered so that the system knows about its existence and where to retrieve its resources (from a jar file or from a folder). Web developers could also modify the theme registration process by writing a ThemeRegistry, if their application requires it.

Switching Themes

The user could switch to any registered themes by setting a cookie or a library property. Web developers could also add other ways for setting the current theme by writing a custom ThemeResolver.

Providing Theme Resources

After switching to another theme, ThemeProvider is responsible for getting the correct stylesheets to the client. This is done by manipulating the list of widget stylesheets comprising the theme. Web developers could create a custom ThemeProvider to change the caching for the widget stylesheets, inject additional widget stylesheets, reject unwanted widget stylesheets, and/or replace some widget stylesheets with another set.

Resolving Theme URLs

Themes comprises of stylesheets and images. The URLs for those resources must be resolved once the theme changes. There are utility methods created for this purpose.