Get ZK Up and Running with MVC"

From Documentation
Line 5: Line 5:
  
 
This tutorial is targeted to software developers. We will teach you how to build a modern web application with ZK. The target application we are going to build is a bookstore catalog application.
 
This tutorial is targeted to software developers. We will teach you how to build a modern web application with ZK. The target application we are going to build is a bookstore catalog application.
 +
 +
This application has 2 main functions:
 +
# Search books by book name keyword
 +
# View a book's details
  
  
Line 11: Line 15:
 
You can take look at [http://www.zkoss.org this application's live demo].
 
You can take look at [http://www.zkoss.org this application's live demo].
  
 +
We also provide the complete source code with an Eclipse project zip file, please refer to [[Download]].
 
<!--
 
<!--
 
target readers
 
target readers

Revision as of 06:38, 4 July 2012

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

Introduction

This tutorial is targeted to software developers. We will teach you how to build a modern web application with ZK. The target application we are going to build is a bookstore catalog application.

This application has 2 main functions:

  1. Search books by book name keyword
  2. View a book's details


Tutorial-searchexample.png

You can take look at this application's live demo.

We also provide the complete source code with an Eclipse project zip file, please refer to Download.

Installation

In this section, we'll tell you how to setup up ZK in a web application project.

Prerequisite

We use Eclipse IDE 3.7 (indigo) for Java EE developer (Download it) to demonstrate the whole instructions.

Add a Server Runtime Environment

A web application project needs an application server environment to run. In Eclipse menu, select Window \ Preferences, in Preferences window, select Server\Runtime Environments. Click Add button to add a server runtime environment.

Tutorial-addruntime.png


Select Apache Tomcat v6.0 as our environment, click Next.

Tutorial-tomcat.png


If you have installed Tomcat before, just provide your path. If you don't, just click Download and Install button and choose a folder, wait for a while, Eclipse will download and install Tomcat for you. After installation is complete, the Finish button will become enabled. Click it to finish adding server runtime.

Tutorial-downloadinstall.png


You shall see a entry like the following in your Server Runtime Environment.

Tutorial-runtimeEnvironment.png


Create a Web Project

In Eclipse, select File \ New \ Dynamic Web Project, enter zktutorial in Project name, select 2.4 for Dynamic web module version and keep every thing else default.

Tutorial-newproject.png

Download

Download the ZK CE (file name should be zk-bin-6.0.0.zip) and extract it to a folder.

Add ZK JAR to Your Project

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

Copy JAR files under following list to zktutorial/WEB-INF/lib:

  • {YOUR_ZK_UNZIP_FOLDER}/dist/lib
  • {YOUR_ZK_UNZIP_FOLDER}/dist/lib/ext

If your project use maven, please add following dependencies:

		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkbind</artifactId>
			<version>6.0.0</version>
		</dependency>

Configure web.xml

By default, Eclipse creates a default web.xml under [PROJECT_NAME]/WebContent/WEB-INF. You just add line 15 to 42 of the following sample web.xml to your project and the configuration is complete.

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> 

	<display-name>zktutorial</display-name>
	<welcome-file-list>
		<welcome-file>index.zul</welcome-file>
		<welcome-file>index.zhtml</welcome-file>
		<welcome-file>index.html</welcome-file>
		<welcome-file>index.htm</welcome-file>
	</welcome-file-list>
	
    <!-- ZK -->
    <listener>
        <description>ZK listener for session cleanup</description>
        <listener-class>org.zkoss.zk.ui.http.HttpSessionListener</listener-class>
    </listener>
    <servlet>
        <description>ZK loader for ZUML pages</description>
        <servlet-name>zkLoader</servlet-name>
        <servlet-class>org.zkoss.zk.ui.http.DHtmlLayoutServlet</servlet-class>
        <init-param>
            <param-name>update-uri</param-name>
            <param-value>/zkau</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>zkLoader</servlet-name>
        <url-pattern>*.zul</url-pattern>
    </servlet-mapping>

    <servlet>
        <description>The asynchronous update engine for ZK</description>
        <servlet-name>auEngine</servlet-name>
        <servlet-class>org.zkoss.zk.au.http.DHtmlUpdateServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>auEngine</servlet-name>
        <url-pattern>/zkau/*</url-pattern>
    </servlet-mapping>

</web-app>

Verify Installation

After installation, you can create a simple zul to verify the installation works or not. In Eclipse, select File / New / File or File / New / Other / File to add a new file, hello.zul, under WebContent. Copy and paste the following sample code into hello.zul and save it.


hello.zul

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


Add a Server in Eclipse

Right click on your project root folder, in context menu, select Run As / Run on Server to run this project on an application server.

Tutorial-runonserver.png


If you have defined servers before, choose an existing server. If you don't, select Manually define a new server and select Tomcat v6.0 Server as we previously installed server runtime environment. Then click "Finish" and you can see a "Tomcat v6.0 Server" item in the Servers view.

Tutorial-newserver.png


If your Eclipse contains only one dynamic web project, that project should already be configured to deploy on Tomcat you just created. If there is no project under your Tomcat server, you still can add your web project manually. Right click Tomcat server, select Add and Remove.... Select your project from left side "Available", click "Add >" button to add a project to deploy on Tomcat server.

Tutorial-addproject.png



You can see a jar icon with project name under your Tomcat server. That means zktutorial is configured to deploy on Tomcat v6.0.

Tutorial-serverview.png



Eclipse let users to start, stop, and deploy a web application to an application server through "Servers" view. Click start icon to start server or right click on zktutorial root folder and select Run As / Run on Server to run the project.

Tutorial-startserver.png


Open your browser to visit http://localhost:8080/hello.zul. If you can see the following image, then your installation is success.

Tutorial-hello.png

The Domain in This Tutorial

Our target application is a bookstore catalog that allows users to search and view book's detail including name, price, description, and cover preview. The following is the domain object that represents a book.

public class Book {
	private Integer id;
	private String name;
	private String thumbnail;
	private String description;
	private Float price;
	//omit getter and setter for brevity
}


Then we can 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);
}

Sketch User Interface

Design UI is a good step to start building an application. In ZK, you can use a XML-formatted language, ZK User Interface Markup Language (ZUML) [1], to describe user interface. Each XML element represents a component and its attributes are used to set the component's property. For example, the following code creates a window with specified title and normal border and it has a child component, label.

<window title="My First ZK Application" border="normal">
    <label value="Hello"/>
</window>


ZK components are like building blocks, and each component's style, behavior, and function can be configured. You can combine existing components to construct your desired UI. Basically, our target application's user interface is divided into 3 areas inside a window, they are (from up to down) search, listbox, and detail.


search

listbox

detail


The following is the complete code of our target application UI:

searchMvc.zul

	<window title="Search Product" width="800px" border="normal"
	 style="padding-top:10px;padding-left:10px;" apply="tutorial.SearchProductComposer">
		<vlayout>
			<hlayout>
				<textbox id="keywordBox" />
				<button id="searchButton" label="search" image="img/search.png" />
			</hlayout>
			<listbox id="productListbox" mold="paging" pageSize="5">
				<listhead>
					<listheader label="Name" />
					<listheader label="Price" />
				</listhead>
				<template name="model">
					<listitem>
						<listcell label="${each.name}"></listcell>
						<listcell>$<label value="${each.price}" /></listcell>
					</listitem>
				</template>
			</listbox>
			<separator bar="true" height="10px" />
			<hbox id="detailArea">
				<image id="thumbImage" width="250px" />
				<vlayout>
					<label id="nameLabel" />
					<label id="priceLabel" />
					<label id="descriptionLabel" style="display:inline" />
				</vlayout>
			</hbox>
		</vlayout>
	</window>

Manipulate UI

The next step after sketching the UI is to make UI interact with user. We change the UI dynamically by controlling UI component Java object directly.

UI Controller

In order to control UI, you have to create a controller class.

Stuff a bunch of data

We hope users can see a list of books when the page shows up.


Handling User Action

When users select a listitem, we should show them the detail.

Bind UI Automatically

Binding data

Handling UI commands

Patterns Comparison

MVC v.s MVVM

When to use

Restriction

Unit Test ZK Application

ZK provides a unit test library, Mimic, which is one module of ZK Application Test Suite (ZATS).

Deploy and Run

Reference