Create and Run Your First ZK Application with Spring Boot

From Documentation


DocumentationZK Installation GuideQuick StartCreate and Run Your First ZK Application with Spring Boot
Create and Run Your First ZK Application with Spring Boot



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

Configuration

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

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

ZKCEConfig.java and ZKEEConfig.java 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 @Import annotation:

@SpringBootApplication
@Import(ZKEEConfig.class) /*ZK EE config includes CE*/
public class Application  {
	public static void main(String[] args) {
		SpringApplication.run(Application.class, 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: https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/config/ZKCEConfig.java#L21-L37

In this example the zul files are located below the class web resource folder src/main/resources/web/zul/ (you can choose/configure any folder below src/main/resources/web).

Application structure

When deploying the application as a 'fat' jar (self executable jar)

Download/Clone the example project

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

   git clone https://github.com/zkoss-demo/zk-spring-boot.git

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]}{0.0.0.0:8080}
... 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.



Last Update : 2017/11/23

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