Difference between revisions of "Template:Tutorial common chapters"

From Documentation
(30 intermediate revisions by the same user not shown)
Line 10: Line 10:
  
  
 +
= Start from Example Project =
  
= Start a New Project =
+
You can get [https://github.com/zkoss-demo/gettingStarted/ the source code of this article] and import it to your IDE without starting from scratch. Please follow the README to run the project.
  
The following 2 sections will guide you on how to quickly create a new project with [http://maven.apache.org/ maven] and [http://eclipse.org/m2e/ m2e],  an 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| Declaring Domain Class]].
+
If you want to start a new project, please refer to [[ZK Installation Guide/Quick Start]].
 
 
 
 
== 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 [http://www.tutorialspoint.com/maven/ Maven Tutorial] or [http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html Maven in 5 Minutes] before commencing.
 
 
 
The [http://maven.apache.org/archetype/index.html archetype] is a maven project template tool. It can help you 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 (optional) ==
 
The latest '''Eclipse IDE for Java EE Developers''' (4.5 or above) already has m2e plugin installed.
 
 
 
You need to install Eclipse and m2e plugin for an older eclipse 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 | Create a Hello World Application with ZK Maven Archetype]].
 
 
 
= Example Source Code =
 
 
 
You can [https://github.com/zkoss/zkbooks/tree/master/gettingStarted/getZkUp access the source code of this article from github ]. You can also [https://github.com/zkoss/zkbooks/releases/download/getzkup-7.0.3/getzkup-7.0.3-2014-10-16.zip 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 =
 
= Declaring Domain Class =
Line 52: Line 32:
 
}
 
}
 
</source>
 
</source>
* Please refer to References section to see the complete code. <ref> [https://github.com/zkoss/zkbooks/blob/master/gettingStarted/getZkUp/src/main/java/tutorial/Car.java Car.java] </ref>
 
  
 
We then define a service class to perform the business logic (search cars) shown below:
 
We then define a service class to perform the business logic (search cars) shown below:
Line 68: Line 47:
 
* search cars according to keyword in  model and make.
 
* search cars according to keyword in  model and make.
 
* @param keyword for search
 
* @param keyword for search
* @return list of car that match the keyword
+
* @return list of car that matches the keyword
 
*/
 
*/
 
public List<Car> search(String keyword);
 
public List<Car> search(String keyword);
Line 74: Line 53:
 
</source>
 
</source>
  
In this example, we have defined a class - <tt>CarServeImpl</tt> 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.<ref> [https://github.com/zkoss/zkbooks/blob/master/gettingStarted/getZkUp/src/main/java/tutorial/CarService.java CarService.java] [https://github.com/zkoss/zkbooks/blob/master/gettingStarted/getZkUp/src/main/java/tutorial/CarServiceImpl.java CarServiceImpl.java] </ref>
+
In this example, we have defined a class, <code>CarServeImpl</code>, 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. Its implementation details are not in the scope of this article, please refer to source code repository.
  
=Building the User Interface =
+
=Building 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.  
+
UI 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 a page 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 ZK, you can use [[ZUML Reference|ZK User Interface Markup Language (ZUML)]], an XML-formatted language, to describe UI. By ZK's convention, the files to describe the user interface with ZUML uses '''.zul''' as the name suffix. In zul files, one component is represented as an XML element (tag) and you can configure each component's style, behavior, and function by setting XML element's attributes. (check [[ZK Component Reference|ZK Component Reference]] for details)
  
In the case of this example application, first of all, we want to design a ''window'' with the specified title and normal border as our application's frame.
+
In this example application, first of all, we want to use a <code>Window</code> with the specified title and normal border as our application's frame.
  
  
'''Extracted from search.zul'''
+
As <code>Window</code> is the outermost component, it is called the ''root component''. <code>Window</code> is a commonly used container because it makes your web application look like a desktop application. Besides, it can also enclose other components. All other components inside <code>Window</code> are called its ''child components'' and should be put in <code><window></code>'s body.
<source lang="xml">
 
  
<window title="Search" width="600px" border="normal">
+
'''Extracted from [https://github.com/zkoss-demo/gettingStarted/blob/master/src/main/webapp/search.zul search.zul]'''
 +
<syntaxhighlight lang="XML" line>
 +
<window title="Search" border="normal"
 +
width="600px">
 
<!-- put child components inside a tag's body -->
 
<!-- put child components inside a tag's body -->
 
</window>
 
</window>
</source>
+
</syntaxhighlight>
 +
 
 +
* Line 1: Specifying title bar text with <code>title</code> and make <code><window></code> display a normal border with <code>border</code> . For <code>width</code> attribute, use CSS like syntax such as <code>800px</code> or <code>60%</code>.
  
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 its ''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 <code><window></code> (from top to bottom):
  
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.
+
# search function
 +
# car list
 +
# car details.
  
 
[[File:Tutorial-ui-3areas.png | 400px |center]]
 
[[File:Tutorial-ui-3areas.png | 400px |center]]
  
  
'''Search Area:'''
+
== 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:
 
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'''
+
'''Extracted from [https://github.com/zkoss-demo/gettingStarted/blob/master/src/main/webapp/search.zul search.zul]'''
<source lang="xml">
+
<syntaxhighlight lang="XML" line>
 
+
Keyword:
<hbox align="center">
+
<textbox id="keywordBox" />
Keyword:
+
<button id="searchButton" label="Search" iconSclass="z-icon-search" style="margin: 0 0 5px 5px"/>
<textbox id="keywordBox" />
+
</syntaxhighlight>
<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 allow 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.
+
* Line 1~2: Specifying the <code>id</code> attribute for some components allows you to control them by referencing their ''id''.  
 +
* Line 3: You can use built-in Font Awesome icon at <code>iconSclass</code>. Please refer to [[ZK_Component_Reference/Base_Components/LabelImageElement#IconSclass| LabelImageElement#IconSclass]] for details.
  
'''Extracted from search.zul'''
+
== Car List Area ==
<source lang="xml">
+
ZK provides several components to display a collection of data such as <code>listbox</code>, <code>grid</code>, and <code>tree</code>. In this example, we use a <code>listbox</code> to display a list of cars with 3 columns: Model, Make, and Price.  Here we use <code>listcell</code> with static label to demonstrate structure of a <code>listitem</code>. Later, we'll talk about how to create <code>listitem</code> dynamically with a collection of data.
<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>
 
</source>
 
  
 +
'''Extracted from [https://github.com/zkoss-demo/gettingStarted/blob/master/src/main/webapp/search.zul search.zul]'''
 +
<syntaxhighlight lang="XML" line>
 +
<listbox id="carListbox" emptyMessage="No car found in the result" rows="5">
 +
    <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>
 +
</syntaxhighlight>
 +
* Line 1: <code>rows</code> determines the max visible row. <code>emptyMessage</code> is used to show a message when <code>listbox</code> contains no items.
 +
* Line 2: The <code>listbox</code>  is a container component, and you can add <code>listhead</code> to define a column.
 +
* Line 7: The <code>listitem</code> is used to display data, and the number of <code>listcell</code> in one <code>listitem</code> usually equals to the number of <code>listheader</code>.
  
'''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.
+
== Car Details Area ==
 
+
<code>hlayout</code> and <code>vlayout</code> are layout components which arrange their child components in horizontal and vertical order.
'''Extracted from search.zul'''
 
<source lang="xml">
 
<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>
 
</source>
 
 
 
  
You can see the complete zul file through the link in the References section. <ref> [https://github.com/zkoss/zkbooks/blob/master/gettingStarted/getZkUp/src/main/webapp/search.zul search.zul] </ref>
+
'''Extracted from [https://github.com/zkoss-demo/gettingStarted/blob/master/src/main/webapp/search.zul search.zul]'''
 +
<syntaxhighlight lang="XML" line>
 +
<hlayout style="margin-top:20px" width="100%">
 +
<image id="previewImage" width="250px" />
 +
<vlayout hflex="1">
 +
<label id="modelLabel" />
 +
<label id="makeLabel" />
 +
<label id="priceLabel" />
 +
<label id="descriptionLabel" />
 +
</vlayout>
 +
</hlayout>
 +
</syntaxhighlight>
 +
* Line 1: the <code>style</code> attribute allows you to customize component's style with CSS syntax.

Revision as of 02:24, 19 January 2022

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 from Example Project

You can get the source code of this article and import it to your IDE without starting from scratch. Please follow the README to run the project.

If you want to start a new project, please refer to ZK Installation Guide/Quick Start.

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
}

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 matches 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. Its implementation details are not in the scope of this article, please refer to source code repository.

Building User Interface

UI 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 a page from scratch.

In ZK, you can use ZK User Interface Markup Language (ZUML), an XML-formatted language, to describe UI. By ZK's convention, the files to describe the user interface with ZUML uses .zul as the name suffix. In zul files, one component is represented as an XML element (tag) and you can configure each component's style, behavior, and function by setting XML element's attributes. (check ZK Component Reference for details)

In this example application, first of all, we want to use a Window with the specified title and normal border as our application's frame.


As Window is the outermost component, it is called the root component. Window is a commonly used container because it makes your web application look like a desktop application. Besides, it can also enclose other components. All other components inside Window are called its child components and should be put in <window>'s body.

Extracted from search.zul

1 	<window title="Search" border="normal"
2 	width="600px">
3 		<!-- put child components inside a tag's body -->
4 	</window>
  • Line 1: Specifying title bar text with title and make <window> display a normal border with border . 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> (from top to bottom):

  1. search function
  2. car list
  3. 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

1 Keyword:
2 <textbox id="keywordBox" />
3 <button id="searchButton" label="Search" iconSclass="z-icon-search" style="margin: 0 0 5px 5px"/>
  • Line 1~2: Specifying the id attribute for some components allows you to control them by referencing their id.
  • Line 3: You can use built-in Font Awesome icon at iconSclass. Please refer to LabelImageElement#IconSclass for details.

Car List Area

ZK provides several components to display a collection of data such as listbox, grid, and tree. In this example, we use a listbox to display a list of cars with 3 columns: Model, Make, and Price. Here we use listcell with static label to demonstrate structure of a listitem. Later, we'll talk about how to create listitem dynamically with a collection of data.

Extracted from search.zul

 1 <listbox id="carListbox" emptyMessage="No car found in the result" rows="5">
 2     <listhead>
 3         <listheader label="Model" />
 4         <listheader label="Make" />
 5         <listheader label="Price" width="20%"/>
 6     </listhead>
 7     <listitem>
 8         <listcell label="car model"></listcell>
 9         <listcell label="make"></listcell>
10         <listcell>$<label value="price" /></listcell>
11     </listitem>
12 </listbox>
  • Line 1: rows determines the max visible row. emptyMessage is used to show a message when listbox contains no items.
  • Line 2: The listbox is a container component, and you can add listhead to define a column.
  • Line 7: The listitem is used to display data, and the number of listcell in one listitem usually equals to the number of listheader.

Car Details Area

hlayout and vlayout are layout components which arrange their child components in horizontal and vertical order.

Extracted from search.zul

1 	<hlayout style="margin-top:20px" width="100%">
2 		<image id="previewImage" width="250px" />
3 		<vlayout hflex="1">
4 			<label id="modelLabel" />
5 			<label id="makeLabel" />
6 			<label id="priceLabel" />
7 			<label id="descriptionLabel" />
8 		</vlayout>
9 	</hlayout>
  • Line 1: the style attribute allows you to customize component's style with CSS syntax.