View source for Template:Tutorial common chapters revised

= Tutorial Objective =
Our target application is a simple car catalog application. This application has two functions:
# Search cars.
#: Enter a keyword in the input field, click <b>Search</b> and search results will be displayed in the car list below.
# 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.


[[File:tutorial-searchexample.png| 400px | center]]



The next chapter guides you 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 [[#Domain Class| Domain Class]].


= Warm Up =

To begin, we will start with 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 [[File:Eclipse-javaee.png]] is used to demonstrate the building of the car catalog application. ([http://www.eclipse.org/downloads/packages/release/indigo/sr2 Download Eclipse] here, 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:

# Select '''Window \ Preferences''' to open Preferences window
# On the left, select '''General --> Content Types'''. On right, expand '''Text''' node in "Content types" box and select '''XML'''
# Click '''Add''' and type in the content type you wish to add which is '''*.zul''' in this case, then click '''OK''' 

[[File:Tutorial-add-contenttype.png| 400px | center]]


After this has been done, Eclipse will use XML editor to open your zul file.

== Install ZK in a Web Project==

'''Download ZK'''

[http://www.zkoss.org/download/zk Download the ZK CE first] (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:
# Select '''File \ New \ Dynamic Web Project'''
# Enter '''warmup''' in Project name and keep every thing else default.

[[File:Tutorial-newproject.png | 400px | center]]

* 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


<div style="background-color:gold;border:solid;border-width:2px;border-radius:5px;padding-left:5px;padding-right:5px">
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 Guide. <ref> [[ZK Installation Guide/Quick Start/Create and Run Your First ZK Application Manually| ZK Installation Guide \ Create and Run Your First ZK Application Manually]] </ref>
</div>


'''Create a Simple Page ''' 

After installation, you can create a simple zul to verify if the installation has been successful or not. 

In Eclipse, 
# Select '''File \ New \ File''' (or '''File \ New \ Other \ File''' ) to add a new file, '''hello.zul''', under '''WebContent'''. 
# Click '''Source''' tab to modify source.
#: [[File:Tutorial-xmleditor.png| 400px | center]]
# Copy and paste the following sample code into hello.zul and save. 

'''hello.zul'''
<source lang="xml">
 <window title="My First ZK Application" border="normal">
 	Hello World!
 </window>
</source>




Now, in '''Project Explorer''' view your project would look something like:

[[File:Tutorial-project-structure.png | 200px | center]]

If you cannot find '''Project Explorer''' view, select menu '''Window \ Show View \ Project Explorer''' to open it.

== Run an Application ==
<!--
將 new server 及 run on the server 分成兩個步驟，後面的章節可隨時依照run on the server的步驟執行範例程式
-->


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. Click '''Add''' to add a server runtime environment.

[[File:Tutorial-preference-server.png | 400px | center]]


Select '''Apache \ Tomcat v7.0 Server''' as it supports Servlet 3.0 and tick '''Create a new local server''', then click '''Next'''.

<div style="background-color:gold;border:solid;border-width:2px;border-radius:5px;padding-left:5px;padding-right:5px;">
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| References]] .
</div>

[[File:Tutorial-newserver.png | 400px | center]]



If you have installed Tomcat 7 previously, simply provide the directory path. If you haven't, proceed with the following steps:
# Click '''Download and Install''' and choose a folder.
#: '''Notice that the installation path must not contain non-ASCII characters.'''
# Accept the license agreement and wait.
#: '''Eclipse will show an error message before installation completes, please ignore this message.'''
#: [[File:Tutorial-installing-unknown.png | 400px | center]]
#: '''Please wait and do not interrupt the installation before it completes to ensure that the installation  has been done properly.'''
#: [[File:Tutorial-installing-progress.png | center]]
#: Eclipse will download and install Tomcat into the folder you have specified.  
# After the installation has been completed, click '''Finish'''
[[File:Tutorial-downloadinstall.png | 400px | center]]

Now you should be able to see a new entry in '''Server rumtime environments'''.

[[File:Tutorial-server-complete.png | 400px | center]]



Right click on hello.zul and select '''Run As \ Run on Server''' to run this zul on an application server.

[[File:Tutorial-runonserver.png | 400px | center]]



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 '''Finish''' and wait for the server to start running.

[[File:Tutorial-choose-server.png | 400px | center]]



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.

[[File:Tutorial-hello.png | 400px | center]]

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:
# [http://zkbooks.googlecode.com/files/tutorial-20120807.zip Download ] example application project zip file. 
# 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. 
# Then follow the instructions from [[#Run an Application |Run an Application]] to run it.

<!--
We describe domain objects here, because this section is independent from MVC and MVVM sections and domain part is unchanged for these 2 design patterns.
-->

= Declaring Domain Class =

The following is the domain object that represents a car. 

<source lang="java">

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
}
</source>
* Please refer to References section to see the complete code. <ref> [http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/src/tutorial/Car.java Car.java] </ref>

We then define a service class to perform the business logic (search cars) shown below:

<source lang="java">
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);
}
</source>

In this example, we have defined a class - <tt>CarServeImpl</tt> that implements the above user 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.<ref> [http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/src/tutorial/CarService.java CarService.java] [http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/src/tutorial/CarServiceImpl.java CarServiceImpl.java] </ref>

=Building the User Interface =

UI Designing 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) <ref> [[ZUML Reference|ZUML Reference]] </ref>, 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.<ref> [[ZK Component Reference|ZK Component Reference]] </ref> 

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'''
<source lang="xml">

	<window title="Search" width="600px" border="normal">
		<!-- put child components inside a tag's body -->
	</window>
</source>

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.

[[File:Tutorial-ui-3areas.png | 400px |center]]


'''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'''
<source lang="xml">

	 	<hbox align="center">
	 		Keyword:
	 		<textbox id="keywordBox" />
	 		<button id="searchButton" label="Search" image="/img/search.png" />
	 	</hbox>

</source>

<tt>hbox</tt> () 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 at "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: Name, Company 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 value to demonstrate structure of a ''listitem'', and we'll talk about how to create ''listitem'' upon dynamic data in next chapter.

'''Extracted from search.zul'''
<source lang="xml">
	 	<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 value="product name"></listcell>
				<listcell value="company"></listcell>
				<listcell>$<label value="price" /></listcell>
			</listitem>
		</listbox>
</source>


'''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'''
<source lang="xml">
		<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>
</source>


You can see complete zul through the link in References section. <ref> [http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/WebContent/search.zul search.zul] </ref>