ZK - ZK Getting Started - Get ZK Up and Running With MVC - Documentation

27/09/2012
ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation
Products
ZK
ZK Studio
ZK Spring
ZK Spreadsheet
ZK Pivottable
ZK Calendar
ZK JSP
ZATS
Demos
ZK
ZK Studio
ZK SpreadSheet
ZK Pivottable
ZK Calendar
ZK Web Mail
ZK Sandbox
Real World Apps
Downloads
ZK
ZK Studio
ZK Spring
ZK Spreadsheet
ZK Pivottable
ZK Calendar
ZK JSP
ZATS
Why ZK
Features
Top Reasons
Who's Using
Case Studies
Testimonials
Community
Forum
Blog
Contributors
Blogosphere
Small Talks
Request Features
Report Bugs
Documentation
ZK
ZK Studio
ZK Spring
ZK Spreadsheet
ZK Pivottable
ZK Calendar
ZK JSP
ZATS
Support
books.zkoss.org/wiki/ZK_Getting_Started/Get_ZK_Up_and_Running_with_MVC
1/13
27/09/2012
Support Options
Partners
About Us
Search..
Custom Search
Wiki Search
ZK Getting Started/Get ZK Up and Running with MVC

From Documentation
Contents
1 Introduction
2 Tutorial Objective
3 Warm Up
3.1 Setup Eclipse
3.2 Install ZK in a Web Project
3.3 Run an Application
3.4 Import and Run Example Application
4 Declaring Domain Class
5 Building the User Interface
6 Handling UI Logic
6.1 Declaring UI Controllers
6.2 Listening to User Action
6.3 Controlling UI Components
6.4 Displaying a Data Collection
6.5 Implementing the View Details Functionality
7 References
Introduction
This tutorial is intended for software developers who have experience in writing Java programs. You will learn basic concepts through building a modern web application with ZK. The target appli
a simple car catalog application. We will use the MVC approach to build the application here. This approach is very intuitive and flexible and gives you full control of components. In addition, you
the MVVM approach that is covered in another tutorial. [1]
You can download the complete source code with an Eclipse project zip file under 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 name, price, description, and preview.
2/13
27/09/2012
Warm Up
This section guides you through how to setup a project and use ZK in Eclipse. If you want to know how to build the application with ZK first, please skip it and start from Declaring Domain Class
how to prepare an environment to build a ZK web application in including setting the IDE, installing ZK, and running an application in a server.
Setup Eclipse
In this tutorial, Eclipse IDE 3.7 (indigo) for Java EE developer

is used to demonstrate the building of the car catalog application. (Download Eclipse (http://www.eclipse.org/downloads/pack
extract the downloaded zip file to a folder and execute eclipse.exe to run Eclipse.)
In order to edit ZK UI pages in Eclipse, add "zul" (ZK UI page's file extension name) as a content type of XML format following these steps below:
1. Select Window \ Preferences to open Preferences window
2. On the left, select General --> Content Types. On right, expand Text node in "Content types" box and select XML
3. Click Add and type in the content type you wish to add which is *.zul in this case, then click OK
After this has been done, Eclipse will use XML editor to open your zul file.
Install ZK in a Web Project

Download ZK
Download the ZK CE first (http://www.zkoss.org/download/zk) (file name would look like zk-bin-[version].zip) and extract it to a folder.
Create a Project
To build a web application, first, create a "Dynamic Web Project" in Eclipse:
1. Select File \ New \ Dynamic Web Project
2. Enter warmup in Project name and keep every thing else default.
3/13
27/09/2012
You can leave "Target runtime" as "none".

Notice that we set 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 files into your project's library folder.
Copy the JAR files from the following directory 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 supports older (< 3.0) Servlet specification or JDK 1.5, you need to add more configuration on web.xml. Please refer to ZK Installation G
Create a Simple Page

After installation, you can create a simple zul to verify if the installation has been successful or not.
In Eclipse,
1. Select File \ New \ File (or File \ New \ Other \ File ) to add a new file, hello.zul, under WebContent.
2. Click Source tab to modify source.
3. Copy and paste the following sample code into hello.zul and save.
hello.zul
1
2
3
<window title="My First ZK Application" border="normal">

Hello World!
</window>
Now, in Project Explorer view your project would look something like:
4/13
27/09/2012
If you cannot find Project Explorer view, select menu Window \ Show View \ Project Explorer to open it.
Run an Application
Before running a web application, we must create a server in Eclipse. Select Window \ Preferences to open Preferences window and select Server \ Runtime Environments from the left. Clic
environment.
Select Apache \ Tomcat v7.0 Server as it supports Servlet 3.0 and tick Create a new local server, then click Next.
If you use JDK 1.5, you could choose Tomcat v6.0 but you will need more configuration on web.xml. Please refer to ZK Installation Guide in References .
5/13
27/09/2012
If you have installed Tomcat 7 previously, simply provide the directory path. If you haven't, proceed with the following steps:
1. Click Download and Install and choose a folder.
Notice that the installation path must not contain non-ASCII characters.
2. Accept the license agreement and wait.

Eclipse will show an error message before installation completes, please ignore this message.
Please wait and do not interrupt the installation before it completes to ensure that the installation has been done properly.
Eclipse will download and install Tomcat into the folder you have specified.
3. After the installation has been completed, click Finish
Now you should be able to see a new entry in Server rumtime environments.
6/13
27/09/2012
Right click on hello.zul and select Run As \ Run on Server to run this zul on an application server.
Choose an existing Tomcat 7. Yon can also tick Always use this server when running this project option to avoid choosing a server each time you run the application in the future. Click
start running.
After the server starts running, Eclipse will open a browser and connect to http://localhost:8080/hello.zul automatically . If you can see the following image, then your project is ready to use ZK.
You can come back and follow these steps to run your application during this tutorial
Import and Run Example Application

We have prepared an Eclipse project zip file that contains the complete source code, you can download and import it to your Eclipse without having to start from scratch.
To use example application, follow the steps below:
PA1SIDHHU.K
1. Download
example applicationSearch
project zip file (http://zkbooks.googlecode.com/files/tutorial-20120906.zip) .
7/13
27/09/2012
2. In Eclipse, select File \ Import \ General \ Existing Projects into Workspace, choose Select archive file to import example application zip file as a project into your Eclipse.
3. Then follow the instructions from Run an Application to run it.
Declaring Domain Class

The following is the domain object that represents a car.
1
2
3
4
5
6
7
8
9
public class Car {

private Integer id;
private String name;
private String company;
private String preview;
private String description;
private Integer price;
//omit getter and setter for brevity
}
Please refer to References section to see the complete code. [3]
We then define a service class to perform the business logic (search cars) shown below:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public interface CarService {

/**
* Retrieve all cars in the catalog.
* @return all cars
*/
public List<Car> findAll();
/**
* search cars according to keyword in name and company.
* @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 - CarServeImplthat 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
application. Implementation details are not in the scope of this article, please refer to References section.[4]
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 thei
combining and mix matching these components without having to create them from scratch.
In ZK, you can use ZK User Interface Markup Language (ZUML) [5], an XML-formatted language, to describe UI. By ZK's convention, the files to describe user interface with ZUML uses
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]
In the case of this example application, first of all, we want to design a window with specified title and normal border as our application's frame.
Extracted from search.zul
1
2
3
<window title="Search" width="600px" border="normal">


</window>
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
All other components inside window are called 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 norma
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.
8/13
27/09/2012
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 us
keywords, and a button for triggering the search. We can use the following ZK components to fulfill this requirement:
1
2
3
4
5
<hbox align="center">
Keyword:
<textbox id="keywordBox" />
<button id="searchButton" label="Search" image="/img/search.png" />
</hbox>
hboxis 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,
"center" so they are aligned neatly along their center line. Here we also specify an "id" attribute for some components which allows you to control them by referencing their id. You can also easily c
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 co
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 use
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
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
1
2
3
4
5
6
7
8
9
10
11
12
<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">

<listhead>
<listheader label="Name" />
<listheader label="Company" />
<listheader label="Price" width="20%"/>
</listhead>
<listitem>
<listcell label="product name"></listcell>
<listcell label="company"></listcell>
<listcell>$<label value="price" /></listcell>
</listitem>
</listbox>
Car 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 informatio
attribute allows you to customize component's style with CSS syntax.
1
2
3
4
5
6
7
8
9
<hbox style="margin-top:20px">
<image id="previewImage" width="250px" />
<vbox>
<label id="nameLabel" />
<label id="companyLabel" />
<label id="priceLabel" />
<label id="descriptionLabel"/>
</vbox>
</hbox>
You can see the complete zul file through the link in the References section. [7]
Handling UI Logic
The next step after building the UI is to make it respond to users. The approach we introduce here is to control UI component directly by yourself. This approach can be classified to
design pattern. [8] This pattern divides an application into three parts.
The Model consists of application data and business rules. CarServiceand other classes used by it represent this part in our example application.
9/13
27/09/2012
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 Controller plays the role of a coordinator between View and Model. It receives events from View to update Model and retrieve data from Model to change View's presentation.
1.
2.
3.
4.
When a user interacts with a component (e.g. click a button) on a ZUL, the user's action triggers an event.
This event is sent to the controller and invokes corresponding event listener method.
The event listener method usually executes business logic or accesses data, then manipulate ZK components.
A component's state change in an event listener is reflected in its corresponding UI.
Declaring UI Controllers
In ZK, the controller is responsible for controlling ZK components and listening to events triggered by user interaction. We can create a such controller class by simply extending org.zkoss.zk.Se
1
2
3
4
5
6
7
package tutorial;
// omit import for brevity
public class SearchController extends SelectorComposer<Component> {
}
After a controller is created, we associate it with its corresponding UI component. Associating a controller with a component is just specifying full-qualified class name for the target component's
code shows how to associate a controller with a window.
Extracted from searchMvc.zul
1
2
3
4
<window title="Search" width="600px" border="normal"

apply="tutorial.SearchController">

</window>
See the complete zul in References.[9]
After associating the controller with the window component, the controller can listen to events sent from UI and retrieve components which allows us to implement application's function. Let's star
user enters a keyword, clicks the "Search" button to trigger the search.
Steps to implement a function:
1. Declare a method which listens to a component's event
2. Control UI components to implement presentation and business logic in the listener method
Listening to User Action
When we associate a controller with a component, every event triggered by this component (and its child components) is sent to the controller. If there is a method which we assigned to listen to t
invoked. As a user clicks "Search" button to trigger the search function, we have to listen to "Search" button's "onClick" event. We declare a method, search(), and specify it to be invoked whe
clicked with the following annotation:
@Listen("[EVENT_NAME] = #[COMPONENT_ID]").
Such method serves as an event listener method.

The final code looks like:
1
2
3
4

@Listen("onClick = #searchButton")
public void search(){
10/13
27/09/2012
5
6
7
Line 3: "searchButton"is the button component's id, and you can find it in previous zul. There are other syntax which can be specified in @Listen's parameter [10] to describe a compone
Line 4: It must be a public method.
Controlling UI Components
After establishing the relationship between an event and an event listener method, we can start to implement method's logic with components. But firstly we should retrieve the UI component's obj
controller's member variables.
Steps to retrieve components:
1. Declare a variable with target component type (e.g. Listbox, Label...)
2. Name the variable as component's ID.
Matching ID is the default rule to match a component for @Wire, and please refer to ZK Developer's Reference [11] to know other ways.
3. Annotate the variable with @Wire.
Then ZK will "wire" a corresponding ZK component object to the variable we declared. After this has been done, we can then control and manipulate UI by accessing those annotated member va
1
2
3
4
5
6
7
8
9

@Wire
private Textbox keywordBox;
@Wire
private Listbox carListbox;
}
//other codes...
Line 5-6: In searchMvc.zul, there is a listbox whose id is carListbox. ZK will make the variable carListboxreference to the listbox object after components are created.
The search method performs a simple logic: call car service class to search with keyword and set result list to listbox. For a variable which references to a component, we can get component's att
getter (getValue()) or change a component's status like making a label invisible with setter (setVisible(false)) to achieve some dynamic UI effect. Hence, we can easily get what keyword
keywordBox.getValue() and change data item of listbox by carListbox.setModel() . The model of a component is the data the component holds and we can change the model to chang
screen.
1
2
3
4
5
6
7
8
9
10

//omit codes to get components
@Listen("onClick = #searchButton")
public void search(){
String keyword = keywordBox.getValue();
List<Car> result = carService.search(keyword);
carListbox.setModel(new ListModelList<Car>(result));
}
Line 8: Notice that setModel() only accepts a ListModelobject, so we can use org.zkoss.zul.ListModelList to wrap search result list. There are other ListModelobjects for differe
refer to References section. [12]
Displaying a Data Collection
We have successfully made clicking "Search" button to invoke its corresponding event listener, but we would still find that content of listbox doesn't show the search result correctly. That is becau
to render data model on the listbox. Now, we will use a special tag, <template> [13], to control the rendering of each item. ZK will render template tag's content iteratively for each object in the
Steps to use <template> :
1. Use <template>to enclose components that we want to create iteratively.
2. Set template's "name" attribute to "model". [14]
3. Use implicit variable, each, to assign domain object's properties to component's attributes.
Extracted from searchMvc.zul
1
2
3
4
5
6
7
8
9
10
<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">

<listhead>
<listheader label="Name" />
<listheader label="Company" />
<listheader label="Price" width="20%"/>
</listhead>
<template name="model">
<listitem>
<listcell label="${each.name}"></listcell>
<listcell label="${each.company}"></listcell>
11/13
27/09/2012
11
12
13
14
<listcell>$<label value="${each.price}" /></listcell>

</listitem>
</template>
</listbox>
Line 7: The template tag should be put inside the listbox .

Line 8: The <listitem> in previous chapter's zul is for static data, we should replace it with current code.
Line 9: The "each" is a variable that references to a domain object in the model list which is Carin our example application. We can use it to access domain object's property with EL, e.g. $
Implementing the View Details Functionality

Previous sections describe the basic steps to implement a function with ZK. Let's recap them by implementing "view details" function. We declare a method to listen to "onSelect" event of
@Wireto get components including previewImage, nameLabel, priceLabel, and descriptionLabel and assign value to them with setter.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

@Wire
private Listbox carListbox;
@Wire
private Label nameLabel;
@Wire
private Label companyLabel;
@Wire
private Label priceLabel;
@Wire
private Label descriptionLabel;
@Wire
private Image previewImage;
@Listen("onSelect = #carListbox")
public void showDetail(){
Car selected = carListbox.getSelectedItem().getValue();
previewImage.setSrc(selected.getPreview());
nameLabel.setValue(selected.getName());
companyLabel.setValue(selected.getCompany());
priceLabel.setValue(selected.getPrice().toString());
descriptionLabel.setValue(selected.getDescription());
}
//omit other codes for brevity
For complete source code, please refer to References section [15]
References
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
ZK Getting Started/Get ZK Up and Running with MVVM

ZK Installation Guide \ Create and Run Your First ZK Application Manually
Car.java (http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/src/tutorial/Car.java)
CarService.java (http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/src/tutorial/CarService.java) CarServiceImpl.java
(http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/src/tutorial/CarServiceImpl.java)
ZUML Reference
ZK Component Reference
search.zul (http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/WebContent/search.zul)
MVC in Developer's Reference
searchMvc.zul (http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/WebContent/searchMvc.zul)
selector syntax (http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/select/SelectorComposer.html)
Wire Components in Developer's Reference
List Model in Developer's Reference
ZK Developer's Reference/MVC/View/Template
ZK Developer's Reference/MVC/View/Template/Listbox Template
SearchController.java (http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/src/tutorial/SearchController.java)
Retrieved from "http://books.zkoss.org/wiki/ZK_Getting_Started/Get_ZK_Up_and_Running_with_MVC"

Page |
Discussion |
View source |
History
Like
Tw eet
Send
1,838 people like this.
258
Follow us via :
ZK RSS
StumbleUpon
ZK LinkedIn Group
12/13
27/09/2012
twitter @zkoss
facebook fan page
Log in / create account
What links here |
Related changes |
Special pages
| Recent changes
| Help
This page was last modified on 21 August 2012, at 03:59.
This page has been accessed 3,256 times.
Disclaimers | Modified by ZK
Partners :
Partners
13/13

ZK - ZK Getting Started - Get ZK Up and Running With MVC - Documentation

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ZK - ZK Getting Started - Get ZK Up and Running With MVC - Documentation

Uploaded by

Copyright:

Available Formats

27/09/2012

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

ZK Getting Started/Get ZK Up and Running with MVC

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

In this tutorial, Eclipse IDE 3.7 (indigo) for Java EE developer

Install ZK in a Web Project

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

You can leave "Target runtime" as "none".

Create a Simple Page

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

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

2. Accept the license agreement and wait.

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

Import and Run Example Application

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

Declaring Domain Class

public class Car {

public interface CarService {

Building the User Interface

<window title="Search" width="600px" border="normal">

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

hboxis a layout component that arranges its child

<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

<window title="Search" width="600px" border="normal"

See the complete zul in References.[9]

Listening to User Action

Such method serves as an event listener method.

public class SearchController extends SelectorComposer<Component> {

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

public class SearchController extends SelectorComposer<Component> {

public class SearchController extends SelectorComposer<Component> {

Displaying a Data Collection

<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

<listcell>$<label value="${each.price}" /></listcell>

Line 7: The template tag should be put inside the listbox .

Implementing the View Details Functionality

public class SearchController extends SelectorComposer<Component> {

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

ZK Getting Started/Get ZK Up and Running with MVVM

Retrieved from "http://books.zkoss.org/wiki/ZK_Getting_Started/Get_ZK_Up_and_Running_with_MVC"

1,838 people like this.

ZK - ZK Getting Started/Get ZK Up and Running with MVC - Documentation

You might also like