Creating Custom Themes

since 3.5.0

ZK Spreadsheet provides an extensive component set that allow web developers to use as building blocks for easy web page UI construction. Theme is a collection of stylesheets and associated images for its component set. Stylesheets are the files with extension of ".css.dsp". Think of them as normal CSS files that could utilize JSP taglib functionality. Associated images all have file extension either of ".gif" or ".png". Please refer to the subsections for the process of creating custom themes and packaging them inside jar files

Create a theme project skeleton

The general idea is described in the introductory paragraph. Since classic is the official example theme, web developers could simply clone the classic project, and use it as a starting point.

Modify the theme resources

Now it is just a matter of modifying the relevant stylesheets and importing associated image files.

Instead of creating a theme project from scratch, it is easier to use one of the existing standard theme as a template.

Setting up the environment:

1. Clone classic theme from github, if haven't done so.
2. Import Classic as an Existing Maven Project into Eclipse.
3. Rename all the file names and folder names that contains the word classic to the theme name of your choice
4. Unpack the generated archive to replace the content originally inside the folder src/archive/web/classic/js/zss

Next, the new theme will need to be registered first before it could be used by the ZK Spreadsheet application. For archive-based themes, this is done by providing an implementation of the WebAppInit interface.

Note: the registered name should match the folder name.

For example, assume the custom theme is named darkstar,

1 package foo;
2 import org.zkoss.zss.theme.SpreadsheetThemes;
3 
4 public class DarkstarThemeWebAppInit implements WebAppInit {
5     @Override
6     public void init(WebApp webapp) throws Exception {
7         SpreadsheetThemes.register("darkstar");
8     }
9 }

Also, make sure that metainfo/zk/config.xml contained the following configuration.

<config>
...
    <listener>
        <listener-class>foo.DarkstarThemeWebInit</listner-class>
    </listener>
...
</config>

Here would just summarize the steps.

General steps for component style modification:

1. Locate the stylesheet for a given component
2. Modify existing images or add new images as needed
3. Customize the spreadsheet style by tweaking the stylesheet located in step 1

Use a Theme

Using a archive-based theme in a ZK Spreadsheet Application is simple. Simply put the theme jar file inside the WEB-INF/lib folder of your ZK Spreadsheet application. During the startup of your application, the new custom theme would be automatically registered, and available to use.

The process can be summarized as follows:

1. Put the theme jar file inside WEB-INF/lib folder
2. Ready to use

Switching Themes

Standard theme resolution checks the theme settings in the following order.

1. Cookies
2. Library property
3. Theme priority

Dynamically switching themes using Cookies

SpreadsheetThemes.setTheme(Executions.getCurrent(), "custom");
Executions.sendRedirect();

Dynamically switching themes using Library Property

Library property could be used to assign a preferred theme when the current theme setting could not be obtained from Cookies.

Programmatically:

Library.setProperty("org.zkoss.zss.theme.preferred", "custom");
Executions.sendRedirect();

Declaratively: in (WEB-INF/zk.xml)

<library-property>
    <name>org.zkoss.zss.theme.preferred</name>
    <value>custom</value>
</library-property>

References

All source code listed in this book is at Github.