New Approach for Building Custom ZK Theme

Author
Christopher Szu, Engineer, Potix Corporation

Date
April 25, 2016

Version
ZK 8.0.2

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

Introduction

In the past decade, ZK has undergone a few iterations of theme improvement. Many different approaches for customizing ZK theme were provided, but when it comes to major style overhaul, it seems that all current approaches still have considerable room for improvement.

For simpler theme customizations like color change, a very convenient and visual tool called "Theme Roller" is available here. For slightly more sophisticated theme customizations, one must follow the steps of building ZK's own Silvertail or Sapphire theme. For major theme customizations like the Atlantic theme introduced in ZK 7, direct modification to the source files is definitely the recommended approach. But accessing all style related source files were difficult due to the fact that the source files of ZK default theme were separated into three different projects: zul, zkex, and zkmax.

That is why in ZK 8.0.2, all style-related files are collected in one template theme project, making it much easier to create a custom theme.

The main idea here is to have a ZK template theme as the base theme, which then allows ZK developers to extend the base theme and make as many modifications as desired. And since we now have this idea of theme extension, ZK developers can now create a base theme for their project, which is based on ZK template theme, and then extend their own base theme to build more custom themes.

Steps to Creating Your Custom Theme

Follow these steps to create your own custom theme based on ZK's new theme template.

1. Clone ZK's theme template from github and (optionally) rename the destination folder

   ➜ git clone https://github.com/zkoss/zkThemeTemplate.git maroon-theme
   

2. Execute the init.sh script and follow the instructions to setup your custom themed maven project

   ➜ cd maroon-theme
   ➜ ./init.sh
   
   This script will assist you in setting up your custom ZK theme maven project.
   
   Enter the [GROUP ID] for your theme project and press [ENTER]: org.zkoss.theme
   Enter the [ARTIFACT ID] for your theme project and press [ENTER]: maroon
   Enter the [VERSION] for your theme project and press [ENTER]: 1.0.0
   Enter the [THEME NAME] for your theme and press [ENTER]: maroon
   Enter the [DISPLAY NAME] for your theme and press [ENTER]: The maroon theme
   
   GROUP ID     : org.zkoss.theme
   ARTIFACT ID  : maroon
   VERSION      : 1.0.0
   THEME NAME   : maroon
   DISPLAY NAME : The maroon theme
   
   Is the above information correct? [Y/n]
   updating pom.xml......................done.
   updating version......................done.
   updating Version.java.................done.
   updating ThemeWebAppInit.java.........done.
   updating theme path...................done.
   updating config.xml...................done.
   updating lang-addon.xml...............done.
   updating readme.txt...................done.
   removing zktmp files..................done.
   All done.
   

3. You now have access to all the LESS files in ZK and can make as many changes as you like.
4. Run mvn package in the repository root to build the jar file for your custom theme

   ➜ mvn clean package
   

5. The packaged file maroon-1.0.0.jar file will be inside the target folder, copy the jar to WEB-INF/lib/ of your ZK project.
6. Activate the new theme by either adding a library property or setting the zktheme cookie value
   • Using library property, add the following property to WEB-INF/zk.xml

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

   • Using browser cookie, just add the following cookie

     zktheme=maroon
     

7. Set ZK's theme template as the upstream project of your custom theme project to pull all the latest updates into your own project
   1. Set ZK theme template project as the upstream project

      ➜ git remote add upstream https://github.com/zkoss/zkThemeTemplate.git
      

   2. Modified the origin url to your own git remote url

      ➜ git remote set-url origin <INSERT YOUR REPOSITORY URL HERE>
      

8. Run git pull upstream to receive the latest change in ZK template theme- for example CSS related bug fixes. This way, if your customization has any conflict with ZK's change, you will see git merge conflict messages.

Known Difficulties

Although this new approach gives ZK developers more freedom to create their own theme, there is still one inconvenience.
Some ZK components have style attributes calculated by JavaScript and set directly on their corresponding DOM object, thus nullifying any conflicting styles defined in the CSS. We are currently still working on a better alternative than using the dreaded !important CSS syntax to override this issue.

Advanced Theme Customization

This is the first of many ZK theme related small talks to come. Stay tuned for links to future articles!
Feel free to post any questions you have in the comments below.

Comments

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.