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 had under gone a few iterations of theme improvement. Many different approaches for customizing ZK theme were provided, but when it comes to major style overhaul, all current approaches are still inefficient and cumbersome.

For simpler theme customization like color change, a very convenient and visual tool called "Theme Roller" is available here. For slightly more sophisticated theme customization, one must follow the steps of building ZK's own Silvertail or Sapphire theme. For major theme customization 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 in 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, makes it much more easier to create a custom theme.

The main idea here is to have a ZK template theme as the base theme, then ZK developers can 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 Create 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 theme 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, make as many changes as you like. In this quick demo, we'll be changing the background color of the window title area.
   1. Locate the LESS file containing all the predefined color variables _zkvariables.less in src/archive/web/maroon/zul/_zkvariables.less
4. Run mvn package in the repository root to build the jar file for your custom theme

   ➜ mvn clean package
   

5. The packaged jar file will be inside target folder, copy the jar to WEB-INF/lib/ of your ZK project.
6. Either activate the new theme by adding a library property or by 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 template theme as the upstream project of your custom theme project to pull all the latest updates into your own project
   1. Set ZK template theme project as the upstream project

      ➜ git remote add upstream https://github.com/zkoss/zk-template-theme.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 have any conflict with ZK's change, you'll see git merge conflict messages.

Known Difficulties

Although this new approach give 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 style defined in the CSS. Unfortunately, one must use the dreaded !important CSS syntax to override this issue right now.

Advanced Theme Customization

This is the first of many ZK theme related small talks to come, stay tuned for links to future articles. Please post any questions you have in the comments below.