Introduction

ZK 7 is an upcoming big release focusing on HTML5 and CSS3. Themes are now based on LESS, which means that code is now much cleaner and more concise. The greatest value of this change to users is that it is now also very easy to create a new theme. This blog will guide you step by step on how to create your own theme for ZK 7.

ZK 7′s demo is available here

Prerequisites
Here we assume you already have a ZK web project created by maven. In this demo we will use the same project in navigation component blog.

Step 1: create zk theme maven project from zk-maven-archetype in Eclipse

  • Refer to this document for using zk-maven-archetype.
  • Follow Eclipse wizard to create a new zk theme maven project from zk-maven-archetype.
    • Select zk-archetype-theme then click Next
    • zk7-theme-01

    • Type Artificial Id, theme-name and theme-listener-class values then click Finish
    • zk7-theme-02

    • Result
    • zk7-theme-03

Step 2: Customize theme and Check customization

  • Customize black theme
  • In the previous step, we created a black theme project and we can see how _zkvariables.less file located under web/black/zul folder. This file contains all the LESS variables for ZK’s default theme. Now, to customize a black theme, simply modify the color code value for these LESS variables.

    For example, to change navigation component colours, search “navbar” in _zkvariables.less file and find all the LESS variables that are used for the component. We then simply modify them to adapt the black theme style like the following:

      @navColor:                     #FFFFFF;
      @navBorderColor:               #0C0C0C;
      @navBackgroundColor:           #372F2B;
      @navHoverBackgroundColor:      #0E0E0E;
      @navSelectedColor:             #333333;
      @navSelectedBackgroundColor:   #FFFFFF;
      
  • Check the customization
  • 1. Open pom.xml in black theme project, and uncomment PE/EE related comments if you are building theme for PE/EE edition.
    2. Run maven install for black project, it will compile LESS files and create the theme jar file.
    3. In your existing ZK project, add black theme dependency in pom.xml.

      
      
          org.zkoss.theme
          black
          0.8.0-SNAPSHOT
      
      

    And add preferred theme in zk.xml

      
          org.zkoss.theme.preferred
          black
      
      

    4. Start up ZK project to check the customization.

    Original Style
    zk7-theme-05
    Black Style
    zk7-theme-04

    5. If you change LESS variables’ values again, run mvn test again to compile LESS based on latest modification. Then re-start ZK project to check the customization.
    6. After you have done the customization, execute mvn install to build the jar file.

Build by Ant instead of Maven

Previously we have showed you how to use Maven to build theme, here is the step if you would like to build by Ant.

  • 1. Follow the online document to install Apache Ant.
  • 2. Download the following necessary jars from zk repository (right click -> save as) and put in project/lib folder.
    • commons-logging.jar
    • js.jar
    • lesscss-engine.jar
    • yuicompressor.jar
    • zkjszips.jar
    • zkless.jar
    • zul.jar (extract zk-bin-7.0.0-Preview.zip file from sourceforge)
  • 3. Write ant script build.xml file like the following sample under project folder, and change input folder and output folder as needed.
  • 
    
        
            
                
                
                
                
                
                    
                    
                    
                    
                    
                    
                    
                
            
        
    
    
  • 4. Execute ant command in command line tool.
If you enjoyed this post, please consider leaving a comment or subscribing to the RSS feed to have future articles delivered to your feed reader.

8 Responses to “ZK7: Create a new theme project”

  1. Sabina says:

    I tried your sample project and it is not working for me.
    The reason might be that in your zknavdemo project you use snapshot version in pom:

    7.0.0-SNAPSHOT

    which impacts libraries:

    org.zkoss.zk
    zkbind
    ${zk.version}

    org.zkoss.zk
    zkmax
    ${zk.version}

    org.zkoss.zk
    zkplus
    ${zk.version}

    org.zkoss.zk
    zhtml
    ${zk.version}

    I do not believe we have access to your shapshots, I only have 7.0.0-Preview

  2. Infernoz says:

    Nice, I wanted an easy way to do this.

    It is sad to still see the need for Ant support and examples. I pity anyone attempting to use Ant to build and maintain non-trivial ZK projects, the experienced fragility and needless complexity of Ant projects drove me to migrate all my Ant projects to Maven, ASAP after I was up-to-speed with Maven.

  3. vincentjian says:

    @Sabina,
    Just change the version to 7.0.0-Preview in your pom.xml.

    @Infernoz,
    It can build by maven with “mvn install”, the Ant parts is an alternative if someone prefer to use Ant instead of maven.

  4. Darius says:

    I built this with a few customizations, thanks.

    One question: previously, the themes used a lot of images (e.g. panel-corner.gif, wnd-hm.png, wnd-hr.png, etc.) Looking at the ZK 7 zul.jar, I see that the images are still there, but the css does not refer to them.

    On our site, we had customized those images. Now, it seems we will need to do the gradient’s etc. via the LESS variables. Is that true?

    Also, it would be helpful if a ver 7, draft Style Guide was made available

  5. Darius says:

    Another question:

    If I want z-window-header background to be something different
    from @windowBackgroundColor
    and wanted its color to be something other than @textColorGrayDark

    what is the recommend way to customize it?

    Do I change the window.less file?

  6. vincentjian says:

    @Darius
    1. We use CSS 3 in ZK7 which means a lot of images are not needed anymore. Therefore, you can do the gradients via LESS variables.
    2. If you just want to change colors only, you don’t have to change window.less file.
    We are still working on style guide for ZK7 and will publish the articles along with ZK 7 releases.

  7. Steven says:

    I followed the above instruction and failed at maven install stage in eclipse. And class BlackThemeWebAppInit.java in IDE shows “The type org.zkoss.web.theme.StandardTheme$ThemeOrigin cannot be resolved. It is indirectly referenced from required .class files”
    at line “Themes.register(….)”. What’s the problem of the Themes class?

    Maven build trace below:
    Compiling… web/js/zul/wnd/less/panel.less
    Compiling… web/js/zul/wnd/less/window.less
    [INFO]
    [INFO] >>> exec-maven-plugin:1.2.1:java (compile-less-from-zkex) @ black >>>
    [INFO]
    [INFO] <<< exec-maven-plugin:1.2.1:java (compile-less-from-zkex) @ black <<<
    [INFO]
    [INFO] — exec-maven-plugin:1.2.1:java (compile-less-from-zkex) @ black —
    [WARNING]
    java.lang.reflect.InvocationTargetException
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:601)
    at org.codehaus.mojo.exec.ExecJavaMojo$1.run(ExecJavaMojo.java:297)
    at java.lang.Thread.run(Thread.java:722)
    Caused by: java.lang.NullPointerException
    at java.io.File.(File.java:251)
    at org.zkoss.maven.CpLess.main(CpLess.java:37)
    … 6 more
    [INFO] ————————————————————————
    [INFO] BUILD FAILURE
    [INFO] ————————————————————————

    Thanks

  8. Narl Gums says:

    How’s things, I have seen that sometimes this website displays a 403 server error. I figured you would be keen to know. All the best

Leave a Reply