Data-binding Proficient in 45 Minutes

{{Template:UnderConstruction}}

= Introduction =
<!--
target readers
article purpose 
-->


This tutorial is intended for software developers who have experience in writing Java program. We will guide you how to build a modern web application with ZK. The target application we are going to build is a simple car catalog application. We have introduced '''MVC''' approach in previous Tutorial<ref> [[Tutorial]]</ref>. If you have read it, you could skip first several chapters and jump to [[#Automatic UI Controlling| Automatic UI Controlling]]. In this article, we will present another approach which is classified under the  '''Model-View-ViewModel (MVVM)''' design pattern. Using this approach, ZK can control components for you automatically.

You can take a look at [http:// target application's live demo]. We also provide the complete source code with an Eclipse project zip file in [[#Import_and_Run_Example_Application| Import and Run Example Application]] section.




{{Template:tutorial common chapters revised}}

= Automatic UI Controlling =
<!--
short sentence to describe MVVM
what is ViewModel
how ViewModel interact with View & Model
概述mvvm開發的作法
-->
The approach we introduce here to control user interaction is to '''let ZK control UI components for you'''. This approach is classified <under the> '''Model-View-ViewModel''' ('''MVVM''') design pattern. <ref> [[ZK Developer's Reference/MVVM| MVVM in Developer's Reference]] </ref> This pattern divides an application into three parts.

The '''Model''' consists of application data and business rules. <tt>CarService</tt> 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. An user's interaction with components triggers events to be sent to controllers.

The '''ViewModel''' is responsible for exposing data from the Model to the View and providing required action requested from the View. The ViewModel is type of '''View abstraction''' which contains a View's state and behavior. But '''ViewModel should contain no reference to UI components'''. ZK framework handles communication and state synchronization between View and ViewModel.

Under this approach, you just '''prepare a ViewModel class''' with proper setter, getter and behavior methods. Then '''specify data binding expression on component's attributes''' in a ZUL. There is a binder in ZK which will synchronize data between ViewModel and components and handle events automatically according to your binding expression. You don't need to control components by yourself.


Here we use search function to explain how MVVM works in ZK. Assume that a user click "Search" button then ''listbox'' updates its content. The flow is as follows:

[[Image:tutorial-mvvm.png | center]]


# A user clicks "Search" button and a corresponding event is sent.
# ZK's binder invokes the corresponding command method in the ViewModel.
# The method accesses data from Model and updates some ViewModel's properties.
# ZK's binder reloads changed properties from the ViewModel to update component's states.

<!--
In this chapter, you'll learn:

# How to implement a ViewModel
# How to use data binding
# How to use command binding and change notification
-->

== Abstract the View==

<!--
Implement ViewModel concept with a class
usage of Java annotation for data binding
-->
ViewModel is an abstraction of View. Therefore when we design a ViewModel, we should analysis UI's functions for what '''state''' it contains and what '''behavior''' it has.

The state:
# keyword from user input
# car list of search result
# selected car

The behavior:
# search


According to above analysis, the ViewModel should have 3 variables for above states and one method for the behavior. In ZK, creating a ViewModel is like creating a POJO, and it exposes its states like JavaBean's properties through setter and getter methods.  The search method implements search logic with service class and updates property "carList".

'''SearchViewModel.java'''
<source lang="java">
package tutorial;

import java.util.List;
import org.zkoss.bind.annotation.*;

public class SearchViewModel {

	private String keyword;
	private List<Car> carList;
	private Car selectedCar;
	
	//omit getter and setter

	public void search(){
		carList = carService.search(keyword);
	}
}

</source>


'''Annotation'''

In ZK MVVM, any behavior which can be requested by a View is a '''command''' in a ViewModel. Then you can bind a component's event to the command and ZK will invoke the method when bound event is triggered. In order to let ZK knows which behavior (method) can be requested, you should apply an annotation <tt>@Command</tt> on a method. We mark <tt>search()</tt> as a "command" with '''default command name''', search, which is the same as method name. The command name is used in data binding expression we'll talk about in next section.


In <tt>search()</tt>, we change a ViewModel's property: <tt>carList</tt>. Thus, we should tell ZK this change with <tt>@NotifyChange</tt> so that ZK can reload the changed property for us after it invokes this method.

For "search" command, it looks like:

'''SearchViewModel.java'''
<source lang="java" high="10,11">
package tutorial;

import java.util.List;
import org.zkoss.bind.annotation.*;

public class SearchViewModel {

	//omit other codes

	@Command
	@NotifyChange("carList")
	public void search(){
		carList = carService.search(keyword);
	}
}
</source>


For complete source code, please refer to References section. <ref>  [http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/src/tutorial/SearchViewModel.java SearchViewModel.java] </ref>

== Bind UI to ViewModel ==
In MVVM approach, the way to sketch UI is the same as MVC approach. Then you specify relationship between a ZUL and a ViewModel by writing data binding expression in component's attribute, and let ZK handles components for you.

To bind a component to a ViewModel, you should apply a composer called '''org.zkoss.bind.BindComposer'''. This composer processes data binding expressions and initializes the ViewModel's class. Then we can bind this component to a ViewModel by setting its '''viewModel''' attribute with following syntax:

'''<tt>@id('ID') @init('FULL.QUALIFIED.CLASSNAME')</tt>'''

* <tt> @id() </tt> is used to set ViewModel's id to whatever you want like a variable name. You will use this id to reference ViewModel's properties (e.g. vm.carList) in a data binding expression.
* You should provide full-qualified class name for <tt>@init()</tt> to initialize the ViewModel object.


'''searchMvvm.zul'''
<source lang="xml" high="2">
	<window title="Search" width="600px" border="normal" 
		apply="org.zkoss.bind.BindComposer" viewModel="@id('vm') @init('tutorial.SearchViewModel')">
	<!-- omit other tags-->
	</window>
</source>

After binding the ViewModel to the component, all its child components can access the same ViewModel and its properties. 



You can bind View to both ViewModel's properties and behavior with data binding expression. Let's see how to use data binding to achieve search function.

We have declared variables in ViewModel class for component's states in previous section, and we can bind component's attributes to them. After binding a component's attribute to ViewModel, ZK will synchronize data between attribute's value and a ViewModel's property for us automatically. Now we are going to specify '''which attribute is bound to which property''' by writing data binding expression as a component attribute's value with syntax:

'''<tt>@bind(vm.aProperty) </tt>'''

* Remember that <tt>vm</tt> is the id we have given it in <tt> @id()</tt> previously and now we use it to reference ViewModel object.

There are 2 states which relate to search function to be stored in the ViewModel upon previous analysis. First, we want to store value of ''textbox'' in ViewModel's <tt>keyword</tt>. Then we can bind "value" of ''textbox'' to <tt>vm.keyword</tt> with <tt>@bind(vm.keyword)</tt>.  Second, We want to store the data model of a ''listbox'' in ViewModel's <tt>carList</tt>, so we should bind ''listbox'''s "model" to <tt>vm.carList</tt>. 

'''searchMvvm.zul'''
<source lang="xml" high="3,6">

		<hbox>
			Keyword:
			<textbox value="@bind(vm.keyword)" />
			<button label="Search" image="/img/search.png"/>
		</hbox>
		<listbox height="160px" model="@bind(vm.carList)" emptyMessage="No car found in the result">
		<!-- omit other tags -->

</source>


You can only bind a component's event attribute (e.g. onClick) to ViewModel's behavior. After you bind an event to a ViewModel, each time a user triggers the event, ZK finds bound command method and invokes it. In order to handle clicking on "Search" button, you have to bind button's onClick attribute to a command method with following syntax:

'''<tt> @command('COMMAND_NAME')</tt>'''

* You should look for command name specified in your ViewModel's command method. 

'''searchMvvm.zul'''
<source lang="xml" high="4">
		<hbox>
			Name Keyword:
			<textbox value="@bind(vm.keyword)" />
			<button label="Search" image="/img/search.png" onClick="@command('search')" />
		</hbox>
		<listbox height="160px" model="@bind(vm.carList)" emptyMessage="No car found in the result">
		<!-- omit other tags -->
</source>

After binding this "onClick" event, when a user clicks "Search" button, ZK will invoke <tt>search() </tt> and reload the property "carList" which is specified in <tt>@NotifyChange</tt>.

== Display a Collection of Data ==
<!--
use binding syntax
-->

The way to display a collection of data with data binding is very similar to the way in MVC approach. The only difference is you should use data binding expression instead of EL.

<source lang="xml" high="7,8,9,10,11,12,13,14">

		<listbox height="160px" model="@bind(vm.carList)" emptyMessage="No car found in the result">
			<listhead>
				<listheader label="Name" />
				<listheader label="Company" />
				<listheader label="Price" width="20%"/>
			</listhead>
			<template name="model">
				<listitem>
					<listcell label="@bind(each.name)"></listcell>
					<listcell label="@bind(each.company)"></listcell>
					<listcell>$<label value="@bind(each.price)" />
					</listcell>
				</listitem>
			</template>
		</listbox>
</source>

== Implement View Details Function ==

The steps to implement view details function are similar to previous sections. 

# We bind attribute <tt>selectedItem</tt> of ''listbox'' to the property <tt>vm.selectedCar</tt> to save selected domain object.
# Because we want to show selected car's details, we bind value of ''label'' and src of ''image'' to selected car's properties which can be access by chaining dot notation like <tt>vm.selectedCar.name</tt>. 
# Each time a user selects a ''listitem'', ZK saves selected car to the ViewModel. Then ZK reloads <tt>selectedCar</tt>'s properties to those bound attributes.

<!--
(Most users may think this behavior is natural.)
You may wonder why does ZK know to reload <tt>selectedCar</tt>'s properties when they are changed? Because ''setter method has default notification by default''', ZK will reload the target property changed by setter method automatically. You don't need to specify <tt>@NotifyChange</tt> to notify ZK the changed property itself.
-->

<source lang="xml" high="2,6,8,9,10,11">
		<listbox height="160px" model="@bind(vm.carList)" emptyMessage="No car found in the result"
		selectedItem="@bind(vm.selectedCar)">
		<!-- omit child components -->
		</listbox>
		<hbox style="margin-top:20px">
			<image width="250px" src="@bind(vm.selectedCar.preview)" />
			<vbox>
				<label value="@bind(vm.selectedCar.name)" />
				<label value="@bind(vm.selectedCar.company)" />
				<label value="@bind(vm.selectedCar.price)" />
				<label value="@bind(vm.selectedCar.description)" />
			</vbox>
		</hbox>
</source>


You can view complete zul in References. <ref> [http://code.google.com/p/zkbooks/source/browse/trunk/tutorial/WebContent/searchMvvm.zul searchMvvm.zul] </ref>

= Approach Comparison =
<!-- 
list strength for users
-->

The interaction picture at left side is MVC, and the one at right side is MVVM. The main differences are that Controller changes to ViewModel and there is a binder to synchronize data instead of a Controller in MVVM .

[[Image:tutorial-mvc.png | 440px ]][[File:tutorial-separator.jpg]][[File:tutorial-mvvm.png | 440px ]]
<div style="width:452px;float:left;">
<div style="font-size:26px;color:DodgerBlue;width:60px;margin-left:auto;margin-right:auto;">
MVC
</div>
</div>
<div style="width:5px;float:left;">

</div>
<div style="font-size:26px;width:452px;float:left;margin-left:auto;margin-right:auto;">
<div style="font-size:26px;color:DodgerBlue;width:80px;margin-left:auto;margin-right:auto;">
MVVM
</div>
</div>



Both approaches can achieve many things in common, but there are still some differences between them. Each of two approaches has its strength. Building an application with MVC approach is more intuitive, because you directly control what you see. Its strength is that you have total control of components, so that you can create child components dynamically, control custom components, or do anything a component can do.

In MVVM, because ViewModel is loosely-coupled with View (it has no reference to components), one ViewModel may associate with multiple Views without modification. UI designers and programmers may work in parallel. If data and behavior do not change, a View's change doesn't cause modifying ViewModel. Besides, as ViewModel is a POJO, it is easy to perform unit test on it without any special environment. That means ViewModel has better reusability, testabiliby, and better resistance against View change. 


To summarize, a comparison table is illustrated below:

<div style="margin-left:auto;margin-right:auto;width:70%;">
{| border="2" style="text-align:center; font-size:18; padding:10px;"
|+ 
! !! <center>MVC</center> !! <center>MVVM</center>
|-
! Coupling with View
| Loose with layout
| Loose
|-
! Coupling with Component
| Tight
| Loose
|-
! Coding in View
| Component ID
| Data binding expression
|-
! Controller Implementation
| &nbsp;Extends ZK's composer&nbsp;
| a POJO 
|-
! UI Data Access
| Direct access
| Automatic
|-
! Backend Data Access
| Direct  access
| Direct  access
|-
! UI Updating
| Manipulate components
| &nbsp;&nbsp; Automatic(@NotifyChange) &nbsp;&nbsp;
|-
! Component Controlling Granularity
| Fine-grained 
| Normal
|-
! Performance
| High
| Normal
|}
</div>

= References = 

<references/>