From Documentation

Jump to: navigation, search

Contents

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 application we are going to build is 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 can also choose to go with 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 model, price, description, and preview.


Tutorial-searchexample.png


Start a New Project

The following 2 sections will guide you on how to quickly create a new project with maven and m2e - a 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.


Maven

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 to 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=http://mavensync.zkoss.org/maven2/

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

You need to install Eclipse and m2e plugin 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 ZK Installation Guide/Quick Start/Create and Run Your First ZK Application with Eclipse and Maven#Create a .22Hello World.22 application with ZK Maven Archetype.

Example Source Code

You can access the source code of this article from github . You can also download a maven project zip file containing the complete source code and import it to your Eclipse without having to start from scratch.

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
}
  • Please refer to References section to see the complete code. [2]

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 References section.[3]

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) [4], 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.[5]

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


	<window title="Search" width="600px" border="normal">
		<!-- put child components inside a tag's body -->
	</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 enclose other components. 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 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.

Tutorial-ui-3areas.png


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">
	 		Keyword:
	 		<textbox id="keywordBox" />
	 		<button id="searchButton" label="Search" image="/img/search.png" />
	 	</hbox>

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 allows 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">
			<listhead>
				<listheader label="Model" />
				<listheader label="Make" />
				<listheader label="Price" width="20%"/>
			</listhead>
			<listitem>
				<listcell label="car model"></listcell>
				<listcell label="make"></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 information on a screen. The "style" attribute allows you to customize component's style with CSS syntax.

Extracted from search.zul

		<hbox style="margin-top:20px">
			<image id="previewImage" width="250px" />
			<vbox>
				<label id="modelLabel" />
				<label id="makeLabel" />
				<label id="priceLabel" />
				<label id="descriptionLabel"/>
			</vbox>
		</hbox>


You can see the complete zul file through the link in the References section. [6]

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 Model-View-Controller (MVC) design pattern. [7] 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 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.


Tutorial-mvc.png
  1. When a user interacts with a component (e.g. click a button) on a ZUL, the user's action triggers an event.
  2. This event is sent to the controller and invokes corresponding event listener method.
  3. The event listener method usually executes business logic or accesses data, then manipulate ZK components.
  4. 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.SelectorComposer :

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 apply attribute. The following code shows how to associate a controller with a window.

Extracted from searchMvc.zul


	<window title="Search" width="600px" border="normal"
	apply="tutorial.SearchController">
	<!-- omit other components for brevity -->
	</window>

See the complete zul in References.[8]


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 start from the search function: a 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 the triggered event, it will be 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 when the "Search button" is clicked with the following annotation:

@Listen("[EVENT_NAME] = #[COMPONENT_ID]").

Such method serves as an event listener method.

The final code looks like:

public class SearchController extends SelectorComposer<Component> {

	@Listen("onClick = #searchButton")
	public void search(){

	}
}
  • 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 [9] to describe a component.
  • 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 object by annotating @Wire on 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 [10] 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 variables.


public class SearchController extends SelectorComposer<Component> {

	@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 carListbox reference 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 attribute such as user's input with 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 a user inputs by 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 change the data rendering on the screen.

public class SearchController extends SelectorComposer<Component> {
	//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 ListModel object, so we can use org.zkoss.zul.ListModelList to wrap search result list. There are other ListModel objects for different collection types, please refer to References section. [11]

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 because we haven't specified how to render data model on the listbox. Now, we will use a special tag, <template> [12], to control the rendering of each item. ZK will render template tag's content iteratively for each object in the data model.

Steps to use <template> :

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

Extracted from searchMvc.zul


		<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">
			<listhead>
				<listheader label="Model" />
				<listheader label="Make" />
				<listheader label="Price" width="20%"/>
			</listhead>
			<template name="model">
				<listitem>
					<listcell label="${each.model}"></listcell>
					<listcell label="${each.make}"></listcell>
					<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 Car in our example application. We can use it to access domain object's property with EL, e.g. ${each.price}.

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 listbox with @Listen, then use @Wire to get components like previewImage, modelLabel, priceLabel, and descriptionLabel and assign value to them with setter.


public class SearchController extends SelectorComposer<Component> {

	@Wire
	private Listbox carListbox;
	@Wire
	private Label modelLabel;
	@Wire
	private Label makeLabel;
	@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());
		modelLabel.setValue(selected.getModel());
		makeLabel.setValue(selected.getMake());
		priceLabel.setValue(selected.getPrice().toString());
		descriptionLabel.setValue(selected.getDescription());
	}
	//omit other codes for brevity
}


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

References

  1. ZK Getting Started/Get ZK Up and Running with MVVM
  2. Car.java
  3. CarService.java CarServiceImpl.java
  4. ZUML Reference
  5. ZK Component Reference
  6. search.zul
  7. MVC in Developer's Reference
  8. searchMvc.zul
  9. selector syntax
  10. Wire Components in Developer's Reference
  11. List Model in Developer's Reference
  12. ZK Developer's Reference/MVC/View/Template
  13. ZK Developer's Reference/MVC/View/Template/Listbox Template
  14. SearchController.java
You got stuck here?
Let us know how we can improve this page
For specific questions please use the forum