From Documentation

Jump to: navigation, search


The zk-spring-boot Example

The example project is located on github/zkoss-demo/zk-spring-boot. To use it all you need is a command line interface (and optional: git).

This example is based on the Spring Boot - Getting Started Guide extending it by adding the required ZK dependencies and necessary configuration in order to start a ZK project with the Spring Boot platform.

Differences to a "normal" ZK Web Application


As Spring Boot prefers Java- over XML-configuration and doesn't require a classical src/main/webapp-folder (and no WEB-INF/). Hence the ZK configuration files are moved to a different files/folders:

zk.xml was moved to a classpath location:

src/main/webapp/WEB-INF/zk.xml -> src/main/resources/metainfo/zk/zk.xml

web.xml configuration such as servlets/filters are configured the "Spring Boot Way" using java configuration

src/main/webapp/WEB-INF/web.xml -> src/main/java/zk/springboot/config/ZKCEConfig / ZKEEConfig and can be changed to fit your requirements, e.g. disable websocket filter (when used with an older ZK version < 8.5) or richlet filter if not needed.

Adding them to the Spring Boot main Application class can be done using the annotations @ZKCEApplication or

public class Application  {
	public static void main(String[] args) {, args);

Also the DHtmLayoutServlet is obsolete it tries to locate zul files from the servlet context resources, which doesn't exist when deploying packaging a spring boot application as a jar file. That's why the configuration for this Servlet is commented out in this example. (In a war file it can be used as before.)

The current alternative is a @RequestMapping which will forward requests to zul files (/**/*.zul) to ZK's dHtmlUpdateServlet internally. see:

Application structure

In this example the zul files are located below the class web resource folder src/main/resources/web/zul/

You can configure any folder below src/main/resources/web in

zul files can be referenced like this:

    <include src="~./zul/mvvm-page1.zul"/>
    <apply templateURI="~./zul/mvvm-page1.zul"/>

General resource folders are:

Spring Boot resources are referenced by urls starting with '/' ZK resources (including zul files) are prefixed with '~./'


    <image src="/img/zklogo1.png"/>      <!-- src/main/resources/static/img/zklogo1.png -->
    <image src="~./img/zklogo1.png"/>    <!-- src/main/resources/web/img/zklogo3.png -->

Examples how to access resources from either resource folder ar:

Download/Clone the example project

With the git command line installed all you need is to clone the example repository:

   git clone

Alternatively you can download the example as a zip-package.

Once cloned/unzipped open a command line in the project folder.

In order to get started immediately the project includes the gradle-wrapper and maven-wrapper.

During the first execution gradle/maven will download itself and all the required project dependencies automatically. This will initially take quite a few minutes while showing the overall progress. Subsequent executions will be faster as gradle/maven will cache downloaded resources. For additional information on gradle/maven please refer to their official documentation.

Useful build tasks

NOTE: Using the windows command line (cmd) you have to omit the "./" in front of the commands

build self executable jar

with gradle-wrapper

./gradlew clean build

with maven-wrapper

./mvnw clean package

Run the Project

for gradle:

java -jar build/libs/zk-spring-boot-0.1.0.jar

for maven

java -jar target/zk-spring-boot-0.1.0.jar

After a short startup time you'll see an output like this.

... Started ServerConnector@5536379e{HTTP/1.1,[http/1.1]}{}
... Jetty started on port(s) 8080 (http/1.1)
... Started Application in 4.328 seconds (JVM running for 4.987)

The test pages are now available under:

http://localhost:8080/mvvm.zul (small MVVM example showing subnavigation and spring service integration)

http://localhost:8080/resources.zul (examples of accessing static resources the "springboot way" vs the "zk way")

http://localhost:8080/richlet/test (sample richlet - zk in pure java)

Import the project into your IDE

The project itself designed to work from command line and independent of any IDE. Since it's both a gradle or maven project you can import it into your favorite IDE using the provided plugins.

TIP: The main class zk.springboot.Application can be executed directly in your IDE for development and debugging.

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