From Documentation

Revision as of 09:29, 17 August 2012 by Southerncrossie (Talk | contribs)
Jump to: navigation, search



This tutorial is intended for software developers who have experience in writing Java programs. We will guide you through how to build a modern web application with ZK. The target application we are going to build is a simple car catalog application. In this article, we will present an approach which is classified as the Model-View-ViewModel (MVVM) design pattern. Using this approach, ZK can control components for you automatically and it separates the UI from its controller clearly. In addition, you can also go with the MVC approach that is covered in another tutorial [1].

We also provide the complete source code with an Eclipse project zip file in Import and Run Example Application section.

Tutorial Objective

Our target application is a simple car catalog application. This application has two functions:

  1. Search cars.
    Enter a keyword in the input field, click Search and search results will be displayed in the car list below.
  2. View details.
    Click an item from the car list, the area below the car list will show the selected car's details including model, price, description, and preview.


Start from Example Project

You can access the source code of this article from github and import it to your IDE without starting from scratch. Please follow the README to run the project.

Start a New Project

The following 2 sections will guide you on how to quickly create a new project with maven and m2e, an eclipse plugin for maven, and run the project with jetty. For those readers who don't use maven, please refer to ZK Installation Guide/Quick Start. If you want to know how to build the application with ZK first, please skip these two sections and start from Declaring Domain Class.


Create a new project with maven command is quick and doesn't need any IDE. We assume readers have basic understandings for maven, so we won't cover maven concepts here. If you are unfamiliar with maven, please take some time to read tutorials, like Maven Tutorial or Maven in 5 Minutes before commencing.

The archetype is a maven project template tool. It can help you quickly create a project with predefined configurations and dependencies. You can use the command below to generate a project with ZK provided archetypes:

mvn archetype:generate -DarchetypeCatalog=

Then follow the instructions described in ZK Installation Guide/Quick Start/Create and Run Your First ZK Application with Eclipse and Maven#Use the command line version of Maven to create a project to complete the creation and run the application.

Eclipse M2E Plugin (optional)

The latest Eclipse IDE for Java EE Developers (4.5 or above) already has m2e plugin installed.

You need to install Eclipse and m2e plugin for an older eclipse and setup the maven catalog, please follow the instructions described here ZK Installation Guide/Quick Start/Create and Run Your First ZK Application with Eclipse and Maven#Prepare Eclipse.

Then you can create a new project with ZK archetype and run it in eclipse, please refer to Create a Hello World Application with ZK Maven Archetype.

Declaring Domain Class

The following is the domain object that represents a car.

public class Car {
	private Integer id;
	private String model;
	private String make;
	private String preview;
	private String description;
	private Integer price;
	//omit getter and setter for brevity

We then define a service class to perform the business logic (search cars) shown below:

public interface CarService {

	 * Retrieve all cars in the catalog.
	 * @return all cars
	public List<Car> findAll();
	 * search cars according to keyword in  model and make.
	 * @param keyword for search
	 * @return list of car that match the keyword
	public List<Car> search(String keyword);

In this example, we have defined a class - CarServeImpl that implements the above interface. For simplicity, it uses a static list object as the data model. You can rewrite it so that it connects to a database in a real application. Implementation details are not in the scope of this article, please refer to source code repository.

Building the User Interface

UI Design is a good start to building an application as it helps you define the scope of your application. ZK provides hundreds of readily made UI components so developers can rapidly build their desired user interface by combining and mix matching these components without having to create them from scratch.

In ZK, you can use ZK User Interface Markup Language (ZUML) [2], an XML-formatted language, to describe UI. By ZK's convention, the files to describe user interface with ZUML uses .zul as the name suffix. In zul files, 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.[3]

In the case of this example application, first of all, we want to design a window with the specified title and normal border as our application's frame.

Extracted from search.zul

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

As window is the outermost component, it is called the root component. Window is a commonly used container because it is a basic display element of a desktop-like application while it can also enclose other components. All other components inside window are called its child components and should be put in window tag's body. 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 within the window, they are (from top to bottom) search function, car list, and car details.


Search Area

ZK components are like building blocks, you can combine and mix-match existing components to construct your desired UI. To allow users to search, we need a text to prompt users for input, a place to enter keywords, and a button for triggering the search. We can use the following ZK components to fulfill this requirement:

Extracted from search.zul

	 	<hbox align="center">
	 		<textbox id="keywordBox" />
	 		<button id="searchButton" label="Search" image="/img/search.png" />

hbox is a layout component that arranges its child components horizontally and you can probably guess by now that the h represents horizontal. As these child components have different heights, we set the "align" attribute to "center" so they are aligned neatly along their center line. Here we also specify an "id" attribute for some components which allow you to control them by referencing their id. You can also easily create an image button by specifying the path for the "image" attribute.

Car List Area

ZK provides several components to display a collection of data such as listbox, grid, and tree. In this example, we have chosen to use a listbox to display a list of cars with 3 columns: Model, Make, and Price. We set the "height" attribute, so the number of rows visible is limited with respect to the height specified; 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 equal to the number of listheader. Here we use listcell with static label to demonstrate structure of a listitem, and we'll talk about how to create listitem dynamically with respect to each data object in the next chapter.

Extracted from search.zul

	 	<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">
				<listheader label="Model" />
				<listheader label="Make" />
				<listheader label="Price" width="20%"/>
				<listcell label="car model"></listcell>
				<listcell label="make"></listcell>
				<listcell>$<label value="price" /></listcell>

Car Details Area

Like the hbox, hlayout and vlayout are also layout components which arrange their child components in horizontal and vertical order. But they are more light-weighted than <hbox/>/ <vbox/> since it renders <div/> intead of <table/> rendered by <hbox>. If you don't have alignment need, using <hlayout/>/ <vlayout/> can reduce a page's complexity and your browser's rendering cost.

By combing these 2 layout components, we can display more information on 2 different divisions. The style attribute allows you to customize component's style with CSS syntax.

Extracted from search.zul

	<hlayout style="margin-top:20px" width="100%">
		<image id="previewImage" width="250px" />
		<vlayout hflex="1">
			<label id="modelLabel" />
			<label id="makeLabel" />
			<label id="priceLabel" />
			<label id="descriptionLabel" />

You can see the complete zul file through the link in the source repository.

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. [4] This pattern divides an application into three parts.

The Model consists of application data and business rules. CarService 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. A 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, we just prepare a ViewModel class with proper setter, getter and behavior methods, then assign data binding expression to a 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 binding expressions. We don't need to control components by ourselves.

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.

Abstracting 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. car list of search result
  3. selected car

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 the property "carList".

package tutorial;

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

public class SearchViewModel {

	private String keyword;
	private List<Car> carList;
	private Car selectedCar;
	//omit getter and setter

	public void search(){
		carList =;


In ZK MVVM, any behavior which can be requested by a View is a command in a ViewModel. We 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 know 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: carList. 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(){
		carList =;

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

Binding UI to ViewModel

Under MVVM, we build our UI as same as we would with the MVC approach, then we specify relationship between a ZUL and a ViewModel by writing data binding expression in component's attribute, and let ZK handle components for us.

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


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

Extracted from searchMvvm.zul

		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.

We can bind View to both ViewModel's properties and behavior with data binding expression. Let's see how to use data binding to achieve search function.

Since we have declared variables in ViewModel class for component's states in previous section, 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. We can specify which attribute is bound to which property by writing data binding expression as 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. We can then 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 carList, so we should bind listbox's "model" to vm.carList.

Extracted from searchMvvm.zul

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

We can only bind a component's event attribute (e.g. onClick) to ViewModel's behavior. After we bind an event to a ViewModel, each time a user triggers the event, ZK finds the 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:


  • We should look for command name specified in our ViewModel's command method.

Extracted from searchMvvm.zul

			Name Keyword:
			<button label="Search" image="/img/search.png" onClick="@command('search')" />
		<!-- omit other tags -->

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

Displaying Data Collection

The way to display a collection of data with data binding is very similar to the way in MVC approach. we will use a special tag, <template> [6], to control the rendering of each item. The only difference is we should use data binding expression instead of EL.

Steps to use <template> :

  1. Use <template> to enclose components that we want to create iteratively.
  2. Set template's "name" attribute to "model". [7]
  3. Use implicit variable, each, to assign domain object's properties to component's attributes.

Extracted from searchMvvm.zul

				<listheader label="Name" />
				<listheader label="Company" />
			<template name="model">
					<listcell label="@bind("></listcell>
					<listcell>$<label value="@bind(each.price)" />

Implementing View Details Functionality

The steps to implement the view details functionality are similar to previous sections.

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

		<!-- omit child components -->
		<hbox style="margin-top:20px">
			<image width="250px" src="@bind(vm.selectedCar.preview)" />
				<label value="@bind(" />
				<label value="@bind(" />
				<label value="@bind(vm.selectedCar.price)" />
				<label value="@bind(vm.selectedCar.description)" />

You can view complete zul in References. [8]

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. In addition, 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


  1. ZK Getting Started/Get ZK Up and Running with MVC
  2. ZUML Reference
  3. ZK Component Reference
  4. MVVM in Developer's Reference
  6. ZK Developer's Reference/MVC/View/Template
  7. ZK Developer's Reference/MVC/View/Template/Listbox Template
  8. searchMvvm.zul