Online Training

Step by Step Tutorial - A Real-World Application with Database.

We will show you, step by step, how to develop a simple web application that uses a database. Although this tutorial is intended for new users of ZK, it, nonetheless, requires that the user have at least a little experience with Java; that is really all a user needs in order to develop Ajax-enabled web applications with ZK.

In this tutorial, we assume that you have already installed JDK (1.4 or above), and a servlet container (ex.Tomcat).

This tutorial is divided into 2 parts,

  • Part 1, the user interface
  • Part 2, linking the user interface to the database

If you are interested in developing your own application, you may need to read this about how to set up the development directory.

The First ZK Application (To-do List)

Imagine that in order to overcome our forgetfulness, we need an application which stores events we are going to do in the future. Such a web application would require the use of a database. For the purposes of this tutorial we'll use the Java database (HSQL DB) which does not require us to install a database server. Try Live Demo

Installing this application   

  1. Download the todo.zip file, and unpack the zip file which includes a war file and a folder
  2. Deploy this application to Tomcat by copying the todo.war file to the directory $TOMCAT_HOME/webapps/. Tomcat will handle the rest of the work, including unzipping and deploying.
  3. Copy hsqldb folder (database files) to the root of the development directory.(ex.C:\)
  4. Start your Tomcat.
  5. Open your browser, and visit http://localhost:8080/todo/todo.zul (the port number depends on the configuration of your Tomcat), and you should see the figure shown below.

All Scenarios

  • Key in related information about an event, and press the Add button to insert it into database.
  • Select any row in the table to show event information in the fields below for users to modify, then press Update button to update the event.
  • Select any row in the table, and press the Delete button to delete the selected "Event".

User Interface Pages

Your First ZK Component

The first step is to create a file whose file extension must be zul, say todo.zul, and place this file under the home directory of your web application, for example, $TOMCAT_HOME/webapps/ProjectName/. You declare a ZK component in much the same way as you declare a component using HTML. Try declaring your first window component as follows:


<window title="To do list" width="640px" border="normal">
</window>

Then, start your Tomcat, and use a browser to visit this page, ex: http://localhost:8080/todo/todo.zul. The result is shown below, a window entitled with “To do List”.

Everything in ZK is a component. As such, you can change the title, width, and border of your window as you please. It is quite simple and intuitive. Try to change these attributes, and see the result.

Hierarchical Relationship among ZK Components

Next, let’s try to enrich this page with more ZK components. Since we need to show data in a table, we could declare a listbox component, which is designed for displaying data, within the enclosing tags of the window component, as follows:


<window title="To do list" width="640px" border="normal">
 <listbox id="box" multiple="true" rows="4">
  </listbox>
</window>

In this example, the listbox component has become a child component of the window component. Yes, there are hierarchical relationships among ZK components, and you will encounter an UI exception if you try to declare a component within a wrong context, for example, declaring a window component as a child of a listbox component.

A Nested Component

Within the declaration of the listbox, we use id attribute to specify the identifier (“box”) of the listbox so that we could use “box” to reference the listbox. Further, listbox is a nested component, which supports two kinds of child components, listhead (aka: column of table), and listitem (aka: row of table).


<window title="To do list" width="640px" border="normal">
 <listbox id="box" multiple="true" rows="4">
  <listhead>
   </listhead>
   <listitem>
   </listitem>
 </listbox>
</window>

We are not yet finished. Let’s declare three listheader components within the enclosing tags of listhead since we need three columns -- “Item”, “Priority”, and “Date” -- in this table, as follows:


<window title="To do list" width="640px" border="normal">
<listbox id="box" multiple="true"  rows="4">
  <listhead>
   <listheader label="Item" />
      <listheader label="Priority" width="50px" />
      <listheader label="Date" width="90px" />
  </listhead>
  <listitem>
  </listitem>
 </listbox>
</window>

And, the result is showed below,

Since we have three columns in our table, each table row also requires three fields. Declare three listcell components within the enclosing tags of the listitem component.


<window title="To do list" width="640px" border="normal">
<listbox id="box" multiple="true"  rows="4">
  <listhead>
   <listheader label="Item" />
   <listheader label="Priority" width="50px" />
   <listheader label="Opened" width="90px" />
  </listhead>
  <listitem>
   <listcell/>
      <listcell/>
      <listcell/>
  </listitem>
 </listbox>
</window>
The nested structure of the listbox component is as follows, 

+listbox 
  +listhead
    listheader
  +listitem
    listcell

Input Components

In addition to displaying these events in the listbox, we need to input information about the event, including event name (text value), event priority (numeric value), and event date (date value). To accomplish that, we declare a textbox, an intbox, and a datebox within the enclosing tags of the window component, as follows:


<window title="To do list" width="640px" border="normal">
<listbox id="box" multiple="true"  rows="4">
  <listhead>
   <listheader label="Item" />
   <listheader label="Priority" width="50px" />
   <listheader label="Opened" width="90px" />
  </listhead>
  <listitem>
   <listcell/>
   <listcell/>
   <listcell/>
  </listitem>
 </listbox>
  Item:<textbox id="name" cols="50" />
    Priority:<intbox id="priority" cols="1" />
    Date:<datebox id="date" cols="8" />
    <button label="Add" width="36px" height="24px"/>
    <button label="Update" width="46px" height="24px"/>
    <button label="Delete" width="46px" height="24px"/> 
</window>

The result is shown below,

Layout Component

To distinguish these input components from the above listbox in a visual presentation, we declare a groupbox component to group the input components together, and a border is drawn around those input components.


<window title="To do list" width="640px" border="normal">
<listbox id="box" multiple="true"  rows="4">
  <listhead>
   <listheader label="Item" />
   <listheader label="Priority" width="50px" />
   <listheader label="Opened" width="90px" />
  </listhead>
  <listitem>
   <listcell/>
   <listcell/>
   <listcell/>
  </listitem>
 </listbox>
    <groupbox>
              <caption label="Event" />
       Item: <textbox id="name" cols="50" />
       Priority: <intbox id="priority" cols="1" />
       Date: <datebox id="date" cols="8" />
       <button label="Add" width="36px" height="24px"/>
       <button label="Update" width="46px" height="24px"/>
       <button label="Delete" width="46px" height="24px"/>
    </groupbox>
</window>

In addition to the groupbox component, we declare a caption component to show a “Event” label across the top of the group box, and the caption component works much like the HTML legend element. The result is shown below,

We have now completed the user interface part of the application's page; the next step is to link the page with our database.

Go to Part 2.