Create and Run Your First ZK Application with Spring Boot"

From Documentation
Line 87: Line 87:
 
== Download/Clone the example project ==
 
== Download/Clone the example project ==
  
With the git command line installed all you need is to clone the example repository:
+
With the git command line installed all you need is to clone the example repository (Alternatively download a [https://github.com/zkoss/zkspringboot/archive/master.zip zip-package]):
  
 
     git clone https://github.com/zkoss/zkspringboot
 
     git clone https://github.com/zkoss/zkspringboot
 
     cd zkspringboot/zkspringboot-demos
 
     cd zkspringboot/zkspringboot-demos
 
Alternatively you can download the example as a [https://github.com/zkoss/zkspringboot/archive/master.zip zip-package].
 
  
 
Build/Run instructions are provided in the [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/README.md README].
 
Build/Run instructions are provided in the [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/README.md README].

Revision as of 11:17, 23 August 2018


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



The zkspringboot Demos

The demo projects are located on [1]. To run them all you need is a command line interface (and optional: git).

These examples are derived from the Spring Boot - Getting Started Guide replacing the springboot-starter-web dependency by zkspringboot-starter to enable convenient auto-configuration for the most common usage scenarios while allowing customization where needed.

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/). Hence the ZK configuration files are moved to a different files/folders:

zk.xml and zk-label.properties were moved to a classpath location:

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


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

src/main/webapp/WEB-INF/web.xml -> auto configuration is provided by the zkspringboot-starter dependency (configurable via application.properties)

After adding the zkspringboot-starter dependency the @SpringBootApplicatio-annotation is sufficient to make initialize ZK.

@SpringBootApplication
public class Application  {
	public static void main(String[] args) {
		SpringApplication.run(Application.class, args);
	}
}

For a single-page-application all you need is to specify a view name as the zk.homepage parameter in the application.properties (or specify a richlet).

Multiple zul-files as entry points for your application are defined using Spring-MVC's @GetMapping annotatios.

see:

Application structure

In the zkspringboot-demo-jar 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 using a the zk.view-resolver-prefix property in application.properties. The extension .zul is added automatically by the default value of zk.view-resolver-suffix.

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 '~./'

e.g.

    <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 are:

Zats Testing

Support for Zats Testing can be enabled by adding the zkspringboot-zats dependency.

Since Zats is running its own embedded jetty, it can't use the same application startup mechanism as plain spring boot. In order to allow Zats tests, the Application configuration must be loaded from a separate web.xml (note it is in src/test/webapp so it doesn't affect the production deployment).

As of now you can specify your test context configuration class (e.g. zk.springboot.Application) as a context parameter inside web.xml. The customized ContextLoaderListener (ZatsSpringBootContextLoaderListener.java) reads this parameter and initializes the application context accordingly.

E.g. the DemoPageTest-case refers to this web.xml to initialize the spring boot application inside Zats' embedded Jetty.

As usual, alternative test-configuration is possible if needed.

(Feedback regarding a cleaner startup of a Spring Boot project in an alternative embedded container is welcome, to avoid extending/overriding Framework classes.)

Download/Clone the example project

With the git command line installed all you need is to clone the example repository (Alternatively download a zip-package):

   git clone https://github.com/zkoss/zkspringboot
   cd zkspringboot/zkspringboot-demos

Build/Run instructions are provided in the README.

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.

Build / Run the Project

Please follow the instructions in the README.md.

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 standard plugins provided by the IDE.

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



Last Update : 2018/08/23

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