Monday, April 30, 2012

A First Look at MVVM in ZK 6

MVVM vs. MVC

In a previous post we've seen how the Ajax framework ZK adopts a CSS selector inspired Controller for wiring UI components in View and listening to their events. Under this ZK MVC pattern, the UI components in View need not to be bound to any Controller methods or data objects. The flexibility of using selector patterns as a mean to map View states and events to the Controller makes code more adaptive to change.

MVVM approaches separation of concern in a reverse direction. Under this pattern, a View-Model and a binder mechanism take place of the Controller. The binder maps requests from View to action logic in View-Model and updates any value (data) on both sides, allowing the View-Model to be independent of any particular View.

Anatomy of MVVM in ZK 6

The below is a schematic diagram of ZK 6's MVVM pattern:
Here are some additional points that's not conveyed in the diagram:
BindComposer:
  • implements ZK's standard controller interfaces (Composer & ComposerExt)
  • the default implementation is sufficient, no modifications necessary
View:
  • informs binder which method to call and what properties to update on the View-Model
View-Model:
  • just a POJO
  • communication with the binder is carried out via Java Annotation

MVVM in Action

Consider the task of displaying a simplified inventory without knowledge of the exact UI markup. An inventory is a collection of items, so we have the object representation of such:

public class Item {
 private String ID;
 private String name;
 private int quantity;
 private BigDecimal unitPrice;

        //getters & setters
}

It also makes sense to expect that an item on the list can be selected and operated on. Thus based on our knowledge and assumptions so far, we can go ahead and implement the View-Model.

public class InventoryVM {
 
    ListModelList<Item> inventory;
    Item selectedItem;
  
    public ListModelList<Item> getInventory(){
        inventory = new ListModelList<Item>(InventoryDAO.getInventory());
        return inventory;
    }

    public Item getSelectedItem() {
        return selectedItem;
    }
 
    public void setSelectedItem(Item selectedItem) {
        this.selectedItem = selectedItem;
    }

}   

Here we have a typical POJO for the View-Model implementation, data with their getters and setter.

View Implementation, "Take One"

Now suppose we later learned the requirements for the View is just a simple tabular display:

A possible mark-up to achieve the UI as indicated above is:
<window title="Inventory" border="normal" apply="org.zkoss.bind.BindComposer" 
 viewModel="@id('vm') @init('lab.zkoss.mvvm.ctrl.InventoryVM')" >
 <listbox model="@load(vm.inventory)" width="600px" >
  <auxhead><auxheader label="Inventory Summary" colspan="5" align="center"/> </auxhead>
  <listhead>
   <listheader width="15%" label="Item ID" sort="auto(ID)"/>
   <listheader width="20%" label="Name" sort="auto(name)"/>
   <listheader width="20%" label="Quantity" sort="auto(quantity)"/>
   <listheader width="20%" label="Unit Price" sort="auto(unitPrice)"/>
   <listheader width="25%" label="Net Value"/>
  </listhead>
  <template name="model" var="item">
   <listitem>
    <listcell><label value="@load(item.ID)"/></listcell>
    <listcell><label value="@load(item.name)"/></listcell>
    <listcell><label value="@load(item.quantity)"/></listcell>
    <listcell><label value="@load(item.unitPrice)"/></listcell>
    <listcell><label value="@load(item.unitPrice * item.quantity)"/></listcell>
   </listitem> 
  </template>
 </listbox>
</window>

Let's elaborate a bit on the mark-up here.

  • At line 1, we apply the default BindComposer to the Window component which makes all children components of the Window subject to the BindComposer's effect.
  • On the following line, we instruct the BindComposer which View-Model class to instantiate and we give the View-Model instance an ID so we could make reference to it.
  • Since we're loading a collection of data onto the Listbox, at line 3 we assign the property "inventory" of our View-Model instance, which is a collection of the Item objects, to Listbox's attribute "model". 
  • At line 12, we then make use of the model on our Template component. Template iterates its enclosed components according to the model it receives. In this case, we have 5 list items which makes up a row in the Listbox. 
  • In each Listcell, we load the properties of each object and display them in Labels.
Via ZK's binding system, we were able to access data in our View-Model instance and load them in View using annotations.

View Implementation, "Take Two"

Suppose later in development, it's agreed that the current tabular display takes too much space in our presentation and we're now asked to show the details of an item only when the item is selected in a Combobox, as shown below:


Though both the presentation and behaviour(detail is shown only upon user's selection) differ from our previous implementation, the View-Model class needs not be heavily modified. Since an item's detail will be rendered only when it is selected in the Combobox, it's obvious that we'd need to handle the "onSelect" event, let's add a new method doSelect:
public class InventoryVM {
 
    ListModelList<Item> inventory;
    Item selectedItem;

    @NotifyChange("selectedItem")
    @Command
    public void doSelect(){ }
    
    //getters & setters

}

A method annotated with @Command makes it eligible to be called from our mark-up by its name, in our case:

<combobox onSelect="@command('doSelect')" >

The annotation @NotifyChange("selectedItem") allows the property selectedItem to be updated automatically whenever user selects a new Item from the Combobox. For our purposes, no addition implementation is needed for the method doSelect. With this bit of change done, we can now see how this slightly-modified View-Model would work with our new mark-up:

<window title="Inventory" border="normal" apply="org.zkoss.bind.BindComposer" 
 viewModel="@id('vm') @init('lab.zkoss.mvvm.ctrl.InventoryVM')" width="600px">
 ...
  <combobox model="@load(vm.inventory)" 
     selectedItem="@bind(vm.selectedItem)" 
      onSelect="@command('doSelect')" >
   <template name="model" var="item">
    <comboitem label="@load(item.ID)"/>
   </template>
   <comboitem label="Test"/>
  </combobox>
  <listbox  visible="@load(not empty vm.selectedItem)" width="240px">
   <listhead>
    <listheader ></listheader>
    <listheader ></listheader>
   </listhead>
   <listitem>
    <listcell>
     <label value="Item Name: " />
    </listcell>
    <listcell>
     <label value="@load(vm.selectedItem.name)" />
    </listcell>
   </listitem>
   <listitem>
    <listcell>
     <label value="Unit Price: " />
    </listcell>
    <listcell>
     <label value="@load(vm.selectedItem.unitPrice)" />
    </listcell>
   </listitem>
   <listitem>
    <listcell>
     <label value="Units in Stock: " />
    </listcell>
    <listcell>
     <label value="@load(vm.selectedItem.quantity)" />
    </listcell>
   </listitem>
   <listitem>
    <listcell>
     <label value="Net Value: " />
    </listcell>
    <listcell>
     <label value="@load(vm.selectedItem.unitPrice * vm.selectedItem.quantity)" />
    </listcell>
   </listitem>
  </listbox>
 ...
</window>


  • At line 4, we load the data collection inventory to the Combobox's model attribute so it can iteratively display the ID for each Item object in the data model using the Template component declared on line 7. 
  • At line 5, the selectedItem attribute points to the most recently selected Item on that list of Item objects
  • At line 6, we've mapped the onSelect event to the View-Model's doSelect method
  • At line 12,  we make the Listbox containing an Item's detail visible only if the selectedItem property in View-Model is not empty (selectedItem will remain empty until an item is selected in the Combobox).
  • The selectedItem's properties are then loaded to fill out the Listbox.

Recap

Under the MVVM pattern, our View-Model class exposes its data and methods to the binder; there's no reference made to any particular View component. The View implementations access data or invoke event handlers via the binder.

In this post, we're only exposed to the fundamental workings of ZK's MVVM mechanisms. The binder is obviously not restricted to just loading data from the View-Model. In addition to saving data from View to ViewModel, we can also inject data converters and validators in the mix of View to View-Model communications. The MVVM pattern may also work in conjunction with the MVC model. That is, we can also wire components and listen to fired-events via the MVC Selector mechanism if we wish to do so.

We'll dig into some of these topics at a later time.

Reference

ZK Developer's Reference