Get ZK Up and Running with MVVM

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


This tutorial is intended for software developers who have experience in writing Java EE programs. We will guide you on how to build a modern web application with ZK. The target application we are going to build is a simple car catalog application. In this article, we will present an approach that is classified as the '''Model-View-ViewModel (MVVM)''' design pattern. Using this approach, ZK can control components for you automatically and it separates the UI from its controller clearly. In addition, you can also choose to go with the <b>MVC</b> approach that is covered in another tutorial <ref> [[ZK Getting Started/Get ZK Up and Running with MVC]]</ref>.

<!--
You can see the example application deployed on-line here [http:// target application's live demo]. 
-->



{{Template:tutorial common chapters}}

= 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 to '''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. <code>CarService</code> 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 '''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, we just '''prepare a ViewModel class''' with proper setter, getter and application logic methods, then '''assign data-binding expression to a 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 binding expressions. We don't need to control components by ourselves.


Here we use the 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
-->

== Abstracting the View==

<!--
Implement the 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 analyze 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 operation:
# search


According to the above analysis, the ViewModel should have 3 variables for the 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 the property "carList".

'''SearchViewModel.java'''
<syntaxhighlight line 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);
	}
}

</syntaxhighlight>


'''Annotation'''

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


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

For the "search" command, it looks like this:

'''SearchViewModel.java'''
<syntaxhighlight line lang="java" highlight="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);
	}
}
</syntaxhighlight>


For complete source code, please refer to [https://github.com/zkoss-demo/gettingStarted/blob/master/src/main/java/tutorial/SearchViewModel.java Github]

== Binding UI to ViewModel ==
Under MVVM, we build our UI as same as we would with the MVC approach, then we specify the relationship between a ZUL and a ViewModel by writing data binding expression in component's attribute and let ZK handle components for us.

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

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

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


'''Extracted from searchMvvm.zul'''
<syntaxhighlight line lang="xml" highlight="2">
	<window title="Search" width="600px" border="normal" 
            viewModel="@id('vm') @init('tutorial.SearchViewModel')">
	...
	</window>
</syntaxhighlight>

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


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


=== Load Data From a ViewModel ===
Since we have declared variables in ViewModel class for a component's states in the previous section, we can bind the component's attributes to them. After binding a component's attribute to ViewModel, ZK will synchronize data between the attribute's value and a ViewModel's property for us automatically. We can specify '''which attribute is loaded from which property''' by writing data binding expression as a component attribute's value with the syntax:

'''<code>@load(vm.aProperty) </code>'''

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


=== Save Data to a ViewModel ===
There are 2 states which relate to search function in the ViewModel upon the previous analysis. First, we want to store value of ''textbox'' in ViewModel's <code>keyword</code>. We can then bind "value" of ''textbox'' to <code>vm.keyword</code> with <code>@save(vm.keyword)</code>. So that ZK will save the user input into the ViewModel at the proper moment.  Second, we want to assign the ''Listbox'' 's data with ViewModel's <code>carList</code>, so we should bind its "model" attribute to <code>vm.carList</code>. 

'''Extracted from searchMvvm.zul'''
<syntaxhighlight line lang="xml" highlight="3,6">

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

</syntaxhighlight>


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

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

* We should look for command name specified in our ViewModel's command method. 

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

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

== Displaying Data Collection ==
<!--
use binding syntax
-->

The way to display a collection of data with data binding is very similar to the way in the MVC approach.  we will use a special tag, <code> <template> </code><ref>[[ZK Developer's Reference/MVC/View/Template]]</ref>, to control the rendering of each item. The only difference is we should use data binding expression instead of EL.

Steps to use <code> <template> </code>:
# Use '''<code><template></code>''' to enclose components that we want to create iteratively.
# Set template's "name" attribute to "model". <ref> [[ZK Developer's Reference/MVC/View/Template/Listbox Template]]</ref>
# Use implicit variable, '''each''', to assign domain object's properties to component's attributes.

'''Extracted from searchMvvm.zul'''
<syntaxhighlight line lang="xml" highlight="7,8,9,10,11,12,13,14">

		<listbox height="160px" model="@load(vm.carList)" 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="@init(each.model)"></listcell>
					<listcell label="@init(each.make)"></listcell>
					<listcell>$<label value="@init(each.price)" />
					</listcell>
				</listitem>
			</template>
		</listbox>
</syntaxhighlight>

== Implementing View Details Functionality ==

The steps to implement the view details functionality are similar to previous sections. 

# We bind attribute <code>selectedItem</code> of ''listbox'' to the property <code>vm.selectedCar</code> 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 <code>vm.selectedCar.price</code>. 
# Each time a user selects a ''listitem'', ZK saves selected car to the ViewModel. Then ZK reloads <code>selectedCar</code>'s properties to those bound attributes.

<!--
(Most users may think this behavior is natural.)
We may wonder why does ZK know to reload <code>selectedCar</code>'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. We don't need to specify <code>@NotifyChange</code> to notify ZK the changed property itself.
-->

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


You can view complete zul at [https://github.com/zkoss-demo/gettingStarted/blob/master/src/main/webapp/searchMvvm.zul Github]


{{Template:tutorial Approach Comparison}}

= References = 

<references/>