From Documentation

Revision as of 00:48, 1 August 2012 by Hawk (Talk | contribs)
Jump to: navigation, search

WarningTriangle-32x32.png This page is under construction, so we cannot guarantee the accuracy of the content!



This tutorial is intended for software developers who have experience in writing Java program. We will guide you how to build a modern web application with ZK. The target application we are going to build is a simple bookstore catalog application. We have introduced MVC approach in previous Tutorial[1]. If you have read it, you could skip first several chapters and jump to Automatic UI Controlling. In this article, we will present another approach which is classified to Model-View-ViewModel (MVVM) design pattern. Using this approach, ZK can control components for you automatically.

You can take look at [http:// target application's live demo]. We also provide the complete source code with an Eclipse project zip file in Download section.

Warm Up

In this chapter, we'll guide you how to prepare an environment to build a web application with ZK including setting IDE, installing ZK, and running an application in a server.

Setup Eclipse

We use Eclipse IDE 3.7 (indigo) for Java EE developer Eclipse-javaee.png (Download Eclipse) to demonstrate the whole instructions. Extract the downloaded zip file to a folder and execute eclipse.exe to open Eclipse.

In order to edit ZK UI page in Eclipse, you should add "zul" (It's ZK UI page's file extension name) as a content type of XML format in following steps:

  1. Select Window \ Preferences to open Preferences window
  2. In left tree, select General \ Content Types, on right hand side, expand Text node in "Content types" box, select XML
  3. Click Add button, type *.zul, and click OK button


After this setup, when you double click a zul file, Eclipse will use XML editor to open it. Click Source tab to view source with syntax hightlight.


Install ZK in a Web Project

Download ZK

Download the ZK CE first (file name looks like zk-bin-[version].zip) and extract it to a folder.

Create a Project

To build a web application, you should create a "Dynamic Web Project" in Eclipse first:

  1. Select File \ New \ Dynamic Web Project
  2. Enter tutorial in Project name and keep every thing else default.
  • You can leave "Target runtime" as "none".
  • Notice that we select Dynamic web module version to 3.0 because we want to use Servlet 3.0 to eliminate application configuration.

Install ZK JAR

To use ZK in your project, you have to copy ZK JAR into your project's library folder.

Copy JAR files under following list to WebContent\WEB-INF\lib:

  • {YOUR_ZK_UNZIP_FOLDER}\dist\lib
  • {YOUR_ZK_UNZIP_FOLDER}\dist\lib\ext

If you prefer to use an application server that does not support Servlet 3.0 specification, you need more configuration on web.xml. Please refer to ZK Installation Guide. [2]

Create a Simple Page

After installation, you can create a simple zul to verify the installation works or not. In Eclipse,

  1. Select File \ New \ File (or File \ New \ Other \ File ) to add a new file, hello.zul, under WebContent.
  2. Copy and paste the following sample code into hello.zul and save it.


 <window title="My First ZK Application" border="normal">
 	Hello World!

After above steps, in Project view your project may look like:


Run an Application

Before running a web application, we must create a server in Eclipse. In Servers view, click new server wizard... or right click in it and select New \ Server. If you can't find Servers view tab, select menu Window \ Show View \ Servers to open it.


Select Manually define a new server and select Tomcat v7.0 Server because it supports Servlet 3.0. Then click Next button.


If you have installed Tomcat 7 before, just provide your path. If you don't, proceed the following step:

  1. Click Download and Install button and choose a folder
  2. Accept the license agreement, wait for a minute.
    Eclipse will download and install Tomcat into the folder you specified. After installation is complete, the Finish button will become enabled.
  3. Click Finish button to complete it.

Right click on hello.zul, in context menu, select Run As \ Run on Server to run this zul on an application server.


Choose an existing Tomcat 7. Yon can also check Always use this server when running this project option to avoid choosing a server each time you run the application in the future. Click Finish button and wait for the server starts running.


After server start running successfully, Eclipse opens a browser automatically and connects to http://localhost:8080/hello.zul. If you can see the following image, then your project is ready to use ZK.


You can follow the steps of this section to run your application during reading this tutorial.

Example Application

Use Case

Our target application is a simple bookstore catalog application. This application has 2 functions:

  1. Search books.
    Enter a keyword in the input field, click search button and it displays the search result in the book list below.
  2. View details.
    Click any item of the book list, then the area below the book list shows the selected book's details including name, price, description, and cover preview.


Domain Class

The following is the domain object that represents a book.

public class Book {
	private Integer id;
	private String name;
	private String previewImage;
	private String description;
	private Float price;
	//omit getter and setter for brevity
  • Please refer to References section to see the complete code. [3]

Then we define a service class to perform the business logic (search books) as follows:

public interface BookService {

	 * Retrieve all books in the bookstore.
	 * @return all books
	public List<Book> findAll();
	 * search books according to keyword.
	 * @param keyword book name's keyword
	 * @return list of book that match the keyword
	public List<Book> search(String keyword);

We have a BookServeImpl that implements above interface. For simplicity it uses a static list object as the data model. You can replace it with connecting to a database in a real application. The implementation detail is not in this article's scope, please refer to References section.[4]

Sketch User Interface

Design UI is a good step to start building an application, since it helps you define the scope of your application. ZK provides hundreds of ready-made UI components. Developers can rapidly build their desired user interface by combining these components without creating from scratch.

In ZK, you can use ZK User Interface Markup Language (ZUML) [5], an XML-formatted language, to describe user interface. In ZK default convention, the files to describe user interface use .zul as file name suffix. One component can be represented as an XML element (tag), and you can configure each component's style, behavior, and function by setting XML element's attributes.[6]

First of all, we use a window with specified title and normal border as our application's frame.

Extracted from search.zul

	<window title="Search Product" width="600px" border="normal">
		<!-- put child components inside a tag's body -->

As window is the outmost component, it's called the root component. Window is a mostly common used container because it's a basic display element of a desktop-like application and it can also encloses other components. All other components inside the window should be put in window tag's body, and they are called child component. We set window's title bar text with "title" attribute and make window display a normal border with "border" attribute. For "width" attribute, use CSS like syntax such as "800px" or "60%".

Basically, our example application's user interface is divided into 3 areas inside a window, they are (from top to bottom) search function, book list, and book details area.


Search Area. ZK components are like building blocks, you can combine existing components to construct your desired user interface. To allow users to search, we need a text to tell user what they should input, a place to enter keywords, and a button for triggering search. We can use following ZK components to fulfill this requirement:

Extracted from searchMvvm.zul

	 	<hbox align="center">
	 		Book Name Keyword:
	 		<textbox />
	 		<button label="Search" image="/img/search.png" />

The hbox ("h" means horizontal) is a layout component and it can arrange its child components in horizontal order. Because these three child components have different height, we use "align" attribute to arrange them for elegance. You can easily create an image button by specifying path at "image" attribute.

Book List Area. ZK provides several components to display a collection of data such as listbox, grid, and tree. We use listbox to display a list of book with 2 columns: Name and Price. We set "height" attribute to limit fixed number of visible row and you can drag scroll-bar to see the rest of rows. The "emptyMessage" attribute is used to show a message when listbox contains no items. The listbox is a container component, and you can add listhead to define a column. The listitem is used to display data, and the number of listcell in one listitem should equals to the number of listheader. Here we use listcell with static value to demonstrate structure of a listitem, and these will be replaced in next chapter.

Extracted from searchMvvm.zul

	 	<listbox height="160px" emptyMessage="No book found in the result">
				<listheader label="Name" />
				<listheader label="Price" width="20%"/>
				<listcell value="product name"></listcell>
				<listcell>$<label value="price" /></listcell>

Book Details Area. Like the hbox, vbox is also a layout component which arranges its child component in vertical order. By combing these 2 layout components, we can present more information on a screen. The "style" attribute allows you to customize component's style with CSS syntax.

Extracted from searchMvvm.zul

		<hbox style="margin-top:20px">
			<image width="250px" />
				<label />
				<label />
				<label />

You can see complete zul through the link in References section. [7]

Automatic UI Controlling

The approach we introduce here to control user interaction is to let ZK control UI components for you. This approach is classified to Model-View-ViewModel (MVVM) design pattern. [8] This pattern divides an application into three parts.

The Model consists of application data and business rules. BookService and other classes used by it represent this part in our example application.

The View means user interface. The zul page which contains ZK components represents this part. An user's interaction with components triggers events to be sent to controllers.

The ViewModel is responsible for exposing data from the Model to the View and providing required action requested from the View. The ViewModel is type of View abstraction which contains a View's state and behavior. But ViewModel should contain no reference to UI components. ZK framework handles communication and state synchronization between View and ViewModel.

Under this approach, you just prepare a ViewModel class with proper setter, getter and behavior methods. Then specify data binding expression on component's attributes in a ZUL. There is a binder in ZK which will synchronize data between ViewModel and components and handle events automatically according to your binding expression. You don't need to control components by yourself.

Here we use search function to explain how MVVM works in ZK. Assume that a user click "Search" button then listbox updates its content. The flow is as follows:


  1. A user clicks "Search" button and a corresponding event is sent.
  2. ZK's binder invokes the corresponding command method in the ViewModel.
  3. The method accesses data from Model and updates some ViewModel's properties.
  4. ZK's binder reloads changed properties from the ViewModel to update component's states.

Abstract the View

ViewModel is an abstraction of View. Therefore when we design a ViewModel, we should analysis UI's functions for what state it contains and what behavior it has.

The state:

  1. keyword from user input
  2. book list of search result
  3. selected book

The behavior:

  1. search

According to above analysis, the ViewModel should have 3 variables for above states and one method for the behavior. In ZK, creating a ViewModel is like creating a POJO, and it exposes its states like JavaBean's properties through setter and getter methods. The search method implements search logic with service class and updates property "bookList".

package tutorial;

import java.util.List;
import org.zkoss.bind.annotation.*;

public class SearchViewModel {

	private String keyword;
	private List<Book> bookList;
	private Book selectedBook;
	//omit getter and setter

	public void search(){
		bookList =;


In ZK MVVM, any behavior which can be requested by a View is a command in a ViewModel. Then you can bind a component's event to the command and ZK will invoke the method when bound event is triggered. In order to let ZK knows which behavior (method) can be requested, you should apply an annotation @Command on a method. We mark search() as a "command" with default command name, search, which is the same as method name. The command name is used in data binding expression we'll talk about in next section.

In search(), we change a ViewModel's property: bookList. Thus, we should tell ZK this change with @NotifyChange so that ZK can reload the changed property for us after it invokes this method.

For "search" command, it looks like:

package tutorial;

import java.util.List;
import org.zkoss.bind.annotation.*;

public class SearchViewModel {

	//omit other codes

	public void search(){
		bookList =;

For complete source code, please refer to References section. [9]

Bind UI to ViewModel

In MVVM approach, the way to sketch UI is the same as MVC approach. Then you specify relationship between a ZUL and a ViewModel by writing data binding expression in component's attribute, and let ZK handles components for you.

To bind a component to a ViewModel, you should apply a composer called org.zkoss.bind.BindComposer. This composer processes data binding expressions and initializes the ViewModel's class. Then we can bind this component to a ViewModel by setting its viewModel attribute with following syntax:


  • @id() is used to set ViewModel's id to whatever you want like a variable name. You will use this id to reference ViewModel's properties (e.g. vm.bookList) in a data binding expression.
  • You should provide full-qualified class name for init() to initialize the ViewModel object.


	<window title="Search Product" width="600px" border="normal" 
		apply="org.zkoss.bind.BindComposer" viewModel="@id('vm') @init('tutorial.SearchViewModel')">
	<!-- omit other tags-->

After binding the ViewModel to the component, all its child components can access the same ViewModel and its properties.

Both ViewModel's properties and behavior can be bound to View with data binding expression. Let's see how to use data binding to achieve search function.

We have declared variables in ViewModel class for component's states in previous section, and we can bind component's attributes to them. After binding a component's attribute to ViewModel, ZK will synchronize data between attribute's value and a ViewModel's property for us automatically. Now we are going to specify which attribute is bound to which property by writing data binding expression in a component attribute's value with syntax:


  • Remember that vm is the id we have given it in @id() previously and now we use it to reference ViewModel object.

There are 2 states which relate to search function to be stored in the ViewModel upon previous analysis. First, we want to store value of textbox in ViewModel's keyword. Then we can bind "value" of textbox to vm.keyword with @bind(vm.keyword). Second, We want to store the data model of a listbox in ViewModel's bookList, so we should bind listbox's "model" to vm.bookList.


			Book Name Keyword:
			<textbox value="@bind(vm.keyword)" />
			<button label="Search" image="/img/search.png"/>
		<listbox height="160px" model="@bind(vm.bookList)" emptyMessage="No book found in the result">
		<!-- omit other tags -->

Only a component's event attribute (e.g. onClick) can be bound to ViewModel's behavior. After you bind an event to a ViewModel, each time a user triggers the event, ZK finds bound command method and invokes it. In order to handle clicking on "Search" button, we have to bind button's onClick attribute to a command method with following syntax:


  • You should look for command name specified in your ViewModel's command method.


			Book Name Keyword:
			<textbox value="@bind(vm.keyword)" />
			<button label="Search" image="/img/search.png" onClick="@command('search')" />
		<listbox height="160px" model="@bind(vm.bookList)" emptyMessage="No book found in the result">
		<!-- omit other tags -->

After binding this "onClick" event, when a user clicks "Search" button, ZK will invoke search() and reload the property "bookList" which is specified in @NotifyChange.

Display a Collection of Data

The way to display a collection of data with data binding is very similar to the way in MVC approach. The only difference is you should use data binding expression instead of EL.

		<listbox height="160px" model="@bind(vm.bookList)" emptyMessage="No book found in the result">
				<listheader label="Name" />
				<listheader label="Price" width="20%"/>
			<template name="model">
					<listcell label="@bind("></listcell>
					<listcell>$<label value="@bind(each.price)" />

Implement View Details Function

The steps to implement view details function are similar to previous sections.

  1. We bind attribute selectedItem of listbox to the property vm.selectedBook to save selected domain object.
  2. Because we want to show selected book's details, we bind value of label and src of image to selected book's properties which can be access by chaining dot notation like
  3. Each time a user selects a listitem, ZK saves selected book to the ViewModel. Then ZK reloads selectedBook's properties to those bound attributes.

		<listbox height="160px" model="@bind(vm.bookList)" emptyMessage="No book found in the result"
		<!-- omit child components -->
		<hbox style="margin-top:20px">
			<image width="250px" src="@bind(vm.selectedBook.preview)" />
				<label value="@bind(" />
				<label value="@bind(vm.selectedBook.price)" />
				<label value="@bind(vm.selectedBook.description)" />

Approach Comparison

The interaction picture at left side is MVC, and the one at right side is MVVM. The main differences are that Controller changes to ViewModel and there is a binder to synchronize data instead of a Controller in MVVM .


Both approaches can achieve many things in common, but there are still some differences between them. Each of two approaches has its strength. Building an application with MVC approach is more intuitive, because you directly control what you see. Its strength is that you have total control of components, so that you can create child components dynamically, control custom components, or do anything a component can do.

In MVVM, because ViewModel is loosely-coupled with View (it has no reference to components), one ViewModel may associate with multiple Views without modification. UI designers and programmers may work in parallel. If data and behavior do not change, a View's change doesn't cause modifying ViewModel. Besides, as ViewModel is a POJO, it is easy to perform unit test on it without any special environment. That means ViewModel has better reusability, testabiliby, and better resistance against View change.

To summarize, a comparison table is illustrated below:

Coupling with View Loose with layout Loose
Coupling with Component Tight Loose
Coding in View Component ID Data binding expression
Controller Implementation  Extends ZK's composer  a POJO
UI Data Access Direct access Automatic
Backend Data Access Direct access Direct access
UI Updating Manipulate components    Automatic(@NotifyChange)   
Component Controlling Granularity Fine-grained Normal
Performance High Normal


[Example application zip file]

Download the example application zip file. In Eclipse, select File \ Import \ Existing Projects into Workspace \ Select archive file to import example application zip file as a project to your Eclipse. Then follow the instructions in Run an Application to run it.


  1. Tutorial
  2. Create and Run Your First ZK Application Manually
  5. ZUML Reference
  6. ZK Component Reference
  7. searchMvvm.zul
  8. MVVM in Developer's Reference