Getting Started with ZK

Introduction

This tutorial is a quick guide which focuses on explaining the strengths of ZK with an example application. If you prefer a step by step tutorial, please take a look at this Step by Step Tutorial.

In this tutorial, we will introduce you two ways to build an Ajax-enabled web application with ZK, a standard way (without data binding), and an advanced way (with data binding).

• A Real World Example
• The Data Model
• A Standard Way (Without Data Binding)
  • Design User Interface Page Using ZK Markup Language
  • Manipulate UI Components Using Java
• An Advanced Way (With Data Binding)
  • Define Relations between Data Bean and UI Components
  • Revise the Java File
• Installing the Web Application

A Real World Example Live Demo

Suppose that you want to build a web site of site-seeing with Google Maps as follows. The page is divided into three parts, a table on the left side, a Google Maps on the right side, and a pane on the bottom of the page.

• Ajax in Action: When the user selects an item in the table, its location will be displayed on the Google Maps, and its coordinates will be shown on the pane.

The Data Model

According to the requirement of above web application, the data model requires four attributes - name, description, latitude, and longitude.

public class Resort {
 private String _name;
 private String _description;
 private Double _latitude;
 private Double _longitude;
 
 public Resort(){};
 public Resort(String name, String description, Double latitude, Double longitude) {
  _name = name;
  _description = description;
  _latitude = latitude;
  _longitude = longitude;
 }
 // getter and setter methods are omitted.
 }
 

A Standard Way (Without Data Binding)

First of all, the standard way to build a web application with ZK will be introduced. In this example, you will learn how to use ZK, and experience its strengths.

Design User Interface Page Using ZK Markup Language

The first file we develop is resort.zul, and it includes a listbox (table), a gmaps(Google Maps), and a groupbox(pane).

In this zul file (resort.zul), there doesn’t exit any java codes or scriplets, and the cleanness of the view page is retained. Those handling codes are defined in a separate Java file — ResortController.java.

The interaction between the zul file and Java file is triggered by user's activities. When the user selects an item in the listbox, onSelect event of the listbox will be fired, and the refreshUI() method of ResortController.java will be invoked to display the selected item on the Google Maps, and to show the coordinates of selected item.

<!-- resort.zul -->
<window id="win" use="org.zkforge.resort.ui.ResortController" title="ZK Tutorial" width="1024px" border="normal">
<script src="http://maps.google.com/maps?file=api&v=2&key=ABQIAAAACZ90QS5pNiEvbXhI0k2NLRTGXUEQDrMr1bP0DVG
8X36ZVCheaRQMK05Rsdneh4skNF6KXaLI8maLlA" type="text/javascript"/>
 <hbox>
<listbox id="lb" onSelect="win.refreshUI()">
  <listhead sizable="true">
   <listheader label="Name" width="100px"/>
   <listheader label="Description" width="250px"/>   
  </listhead>
  <listitem forEach="${win.resorts}" value="${each}">
   <listcell label="${each.name}" />
   <listcell label="${each.description}" />   
  </listitem>
 </listbox>
<gmaps id="gmap" zoom="16" showTypeCtrl="true" mapType="satellite" showLargeCtrl="true" width="610px" 
 height="400px">
  <ginfo id="ginfo"/>
 </gmaps>
 </hbox>
<groupbox mold="3d" width="100%">
  <caption label="Resort"/>
  Name:       <textbox id="name" disabled="true"/>
  Description:<textbox id="desc" disabled="true"/> 
  Latitude:   <doublebox id="lat" disabled="true"/>
  Longitude:  <doublebox id="lng" disabled="true"/>
 </groupbox> 
</window>

Manipulate UI Components Using Java

In the Java file(ResortController.java), we retrieve those UI components by their id, and put data of the selected item into them. Then, ZK engines will update the web page in Ajax automatically.

<!--ResortController.java -->
public class ResortController extends Window { 
 List _resorts = new ArrayList();
  
 public ResortController(){
 _resorts.add(new Resort("La Tour Eiffel","Insolite ! Découvrez la Tour Eiffel autrement.",48.8585599391,2.2945332527));
  _resorts.add(new Resort("Buckingham Palace","The official London residence of the sovereign.",51.5013698182,-0.1416689157));
  _resorts.add(new Resort("東京タワ","総数4万の光ファンタジーと都内最大級15ｍのツリー！",35.6583487578,139.7457217178));
  _resorts.add(new Resort("Der Kölner Dom","Offizieller Name Hohe Domkirche St. Peter und Maria",50.9414206771,6.9586372375));
 }
  
 public void refreshUI(){
  Listbox lb = (Listbox) getFellow("lb");
  Resort resort = (Resort) lb.getSelectedItem().getValue();
  ((Textbox)getFellow("name")).setValue(resort.getName());
  ((Textbox)getFellow("desc")).setValue(resort.getName());
  ((Doublebox)getFellow("lat")).setValue(resort.getLatitude());
  ((Doublebox)getFellow("lng")).setValue(resort.getLongitude());
  
  Gmaps gmap = (Gmaps) getFellow("gmap");
  Ginfo ginfo = (Ginfo) getFellow("ginfo");
  ginfo.setLat(resort.getLatitude());
  ginfo.setLng(resort.getLongitude());
  ginfo.setContent(resort.getDescription());
  gmap.panTo(resort.getLatitude(),resort.getLongitude());
  gmap.setZoom(16);
  gmap.openInfo(ginfo);
 }
 public List getResorts() {
  return _resorts;
 }
 public void setResorts(List resorts) {
  _resorts = resorts;
 }
}

In this example, you could realize the simplicity of building Ajax-enabled web application with ZK. The viewer and controller are separated clearly. Moreover, no more JavaScript code is required! Our belief is that the best way to use Ajax is not to know its existence.

An Advanced Way (With Data Binding)

To simplify the job of maintaining the data consistency between the data bean and the user interface, ZK provides the mechanism of data-binding. The only thing you need to is to define the relation between the data bean and UI components, and data-binding will maintain the data consistency between them automatically.

Define Relations between Data Bean and UI Components

One simple way is to define those relations in the web page directly. One of the major differences is that we add another data bean which represents the selected item, and then binds all of related ZK components to it.

<!-- resort_databind.zul -->
<?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit" ?>
<window id="win" use="org.zkforge.resort.ui.ResortController2" title="ZK Tutorial" width="1024px" border="normal">
<script src="http://maps.google.com/maps?file=api&v=2&key=ABQIAAAACZ90QS5pNiEvbXhI0k2NLRTGXUEQDrMr1bP0DVG
8X36ZVCheaRQMK05Rsdneh4skNF6KXaLI8maLlA"  type="text/javascript"/>
 <hbox>
<listbox model="@{win.resorts}" selectedItem="@{win.selected}" onSelect="win.refreshUI()">
  <listhead sizable="true">
   <listheader label="Name" width="100px"/>
   <listheader label="Description" width="250px"/>   
  </listhead>
  <listitem self="@{each=resort}">
   <listcell label="@{resort.name}" />
   <listcell label="@{resort.description}" />   
  </listitem>
 </listbox> 
 <gmaps id="gmap" zoom="16" showTypeCtrl="true" mapType="satellite" showLargeCtrl="true" width="610px" 
  height="400px">
  <ginfo id="ginfo" lng="@{win.selected.longitude}" lat="@{win.selected.latitude}"
  content="@{win.selected.description}"/>
 </gmaps>
 </hbox>
 <groupbox id="gb" mold="3d" width="100%">
  <caption label="Resort"/>
  Name:<textbox id="name" value="@{win.selected.name}" disabled="true"/>
  Description:<textbox  id="desc" value="@{win.selected.description}" disabled="true"/> 
  Latitude:<doublebox id="lat" value="@{win.selected.latitude}" disabled="true"/>
  Longitude:<doublebox id="lng" value="@{win.selected.longitude}" disabled="true"/>  
 </groupbox>
</window>

Revise the Java File

With the help of data-binding, the handling codes in ResortController.java are much reduced. Once the user selects a different item, the data bean will be changed, and then data of all related ZK components will be updated automatically.

<!--ResortController2.java --> 
 
public class ResortController extends Window { 
 List _resorts = new ArrayList();  
 Resort _selected = new Resort();
 
 public ResortController(){
  _resorts.add(new Resort("La Tour Eiffel","Insolite ! Découvrez la Tour Eiffel autrement.",48.8585599391,2.2945332527));
  _resorts.add(new Resort("Buckingham Palace","The official London residence of the sovereign.",51.5013698182,-0.1416689157));
  _resorts.add(new Resort("東京タワ","総数4万の光ファンタジーと都内最大級15ｍのツリー！",35.6583487578,139.7457217178));
  _resorts.add(new Resort("Der Kölner Dom","Offizieller Name Hohe Domkirche St. Peter und Maria",50.9414206771,6.9586372375));
 }
  
 public void refreshUI(){  
  Gmaps gmap = (Gmaps) getFellow("gmap");
  Ginfo ginfo = (Ginfo) getFellow("ginfo");  
  gmap.panTo(ginfo.getLat(),ginfo.getLng());
  gmap.setZoom(16);
  gmap.openInfo(ginfo);
 }
 public List getResorts() {
  return _resorts;
 }
 public void setResorts(List resorts) {
  _resorts = resorts;
 }
 public Resort getSelected() {
  return _selected;
 }
 public void setSelected(Resort selected) {
  _selected = selected;
 }
}

Installing the Web Application

1. Install Java SDK

If you haven't install Java SDK yet, please download and install SUN Java Standard SDK.

2. Install a Servlet Container

If you don't have a Servlet container, please download and install Apache Tomcat.

3. Download the Web Application

Download the application files here.

4. Unzip the file

Unzip resort.zip, and copy resort.war to $TOMCAT_HOME/webapps/.

5. Start your Web Server, and open your browser to visit http://localhost:8080/resort/resort.zul