ZK Essentials/Chapter 6: Implementing CRUD

Target Application

In this chapter, we are going to build an application with 4 basic operations, CRUD (Create, Read, Update, and Delete). The application's user interface looks like the images below:

Select an Item:

Select a Todo Item

It is a personal todo list management system and it has following features:

1. List all todo items
2. Create a todo item.

   Type item name in upper-left textbox and click or press "Enter" key to create a new todo item.

3. Finish a todo item.

   Click the checkbox in front of a todo item to mark it as finished and the item name will be decorated with line-through.

4. Modify a todo item.

   Click an existing item and the detail editor appears. Then you can edit the item's details.

5. Delete a todo item.

   Click to delete an existing todo item.

MVC Approach

If you have read previous chapters, constructing user interface for the example application should not be a big problem. Let's look at the layout first and ignore the details.

Layout in chapter6/todolist-mvc.zul

<?link rel="stylesheet" type="text/css" href="/style.css"?>
<window apply="org.zkoss.tutorial.chapter6.mvc.TodoListController" 
	border="normal" hflex="1" vflex="1" contentStyle="overflow:auto">
	<caption src="/imgs/todo.png" sclass="fn-caption" label="Todo List (MVC)"/>
	<borderlayout>
		<center autoscroll="true" border="none">
			<vlayout hflex="1" vflex="1">
				<!-- todo creation function-->	
				<!-- todo list -->
			</vlayout>
		</center>
		<east id="selectedTodoBlock" visible="false" width="300px" border="none" collapsible="false" splittable="true" minsize="300" autoscroll="true">
			<vlayout >
				<!-- detail editor -->
			</vlayout>
		</east>
	</borderlayout>
</window>

• Line 5: We construct the user interface with Border Layout to separate layout into 2 areas.
• Line 6: The center area contains a todo creation function and a todo list.
• Line 12: The east area is a todo item editor which is invisible if no item selected.

Read

As we talked in previous chapters, we can use Template to define how to display a data model list with implicit variable each.

Display a To-do List

...
	<listbox id="todoListbox" vflex="1">
		<listhead>
			<listheader width="30px" />
			<listheader/>
			<listheader hflex="min"/>
		</listhead>
		<template name="model">
			<listitem sclass="${each.complete?'complete-todo':''}" value="${each}">
				<listcell>
					<checkbox forward="onCheck=todoListbox.onTodoCheck" checked="${each.complete}"/>
				</listcell>
				<listcell>
					<label value="${each.subject}"/>
				</listcell>
				<listcell>
					<button forward="onClick=todoListbox.onTodoDelete" image="/imgs/cross.png" width="36px"/>
				</listcell>
			</listitem>
		</template>
	</listbox>
...

• Line 8: The default value for required attribute name is "model".
• Line 9: We can implement simple presentation logic with EL expression. Here we apply different styles according to a flag each.complete. We also set a whole object in value attribute, and later we can get the object in the composer.
• Line 11: The each.complete is a boolean variable so that we can assign it to checked. By doing this, the Checkbox will be checked if the to-do item's compelete variable is true.
• Line 11, 17: The forward attribute is used to forward events to another component and we will talk about it in later sections.

In the composer, we should provide a data model for the Listbox.

public class TodoListController extends SelectorComposer<Component>{


	//wire components
	...
	@Wire
	Listbox todoListbox;
	
	...
	
	//services
	TodoListService todoListService = new TodoListServiceChapter6Impl();
	
	//data for the view
	ListModelList<Todo> todoListModel;
	ListModelList<Priority> priorityListModel;
	Todo selectedTodo;
	
	
	@Override
	public void doAfterCompose(Component comp) throws Exception{
		super.doAfterCompose(comp);
		
		//get data from service and wrap it to list-model for the view
		List<Todo> todoList = todoListService.getTodoList();
		todoListModel = new ListModelList<Todo>(todoList);
		todoListbox.setModel(todoListModel);
		
		...
	}
...
}

• Line 25 ~ 27: We initialize the data model in doAfterCompose(). Get data from the service class todoListService and create a ListModelList object. Then set it as the data model of todoListbox.

There is a priority radiogroup in to-do item detail editor appeared on the right hand side when you select an item.

In our application, its priority labels come from a enumeration Priority instead of a static text. We can still use Template to define how to create each Radio under a Radiogroup. The zul looks like as follows:

...
				<grid hflex="1">
					<columns>
						<column align="right" hflex="min"/>
						<column/>
					</columns>
					<rows>
						<row>
							<cell sclass="row-title">Priority :</cell>
							<cell>
								<radiogroup id="selectedTodoPriority">
									<template name="model">
										<radio label="${each.label}"/>	
									</template>
								</radiogroup>
							</cell>
						</row>
...

• Line 12 ~14: Define how to create each Radio with Template and assign each.label to label attribute.

We also need to provide a data model for the Radiogroup in the composer:

public class TodoListController extends SelectorComposer<Component>{


	//wire components
	...
	@Wire
	Listbox todoListbox;
	
	...
	@Wire
	Radiogroup selectedTodoPriority;
	...
	
	//services
	TodoListService todoListService = new TodoListServiceChapter6Impl();
	
	//data for the view
	ListModelList<Todo> todoListModel;
	ListModelList<Priority> priorityListModel;
	Todo selectedTodo;	
	
	@Override
	public void doAfterCompose(Component comp) throws Exception{
		super.doAfterCompose(comp);
		
		//get data from service and wrap it to list-model for the view
		List<Todo> todoList = todoListService.getTodoList();
		todoListModel = new ListModelList<Todo>(todoList);
		todoListbox.setModel(todoListModel);
		
		priorityListModel = new ListModelList<Priority>(Priority.values());
		selectedTodoPriority.setModel(priorityListModel);
	}
...
}

• Line 31, 32: Create a LisModelList with Priority and set it as a model of selectedTodoPriority.

Update

To update a to-do item, you should select an item first then detail editor will appear. The following codes demonstrate how to listen a "onSelect" event and display the item's detail.

public class TodoListController extends SelectorComposer<Component>{


	//wire components
	@Wire
	Textbox todoSubject;
	@Wire
	Button addTodo;
	@Wire
	Listbox todoListbox;
	
	@Wire
	Component selectedTodoBlock;
	@Wire
	Checkbox selectedTodoCheck;
	@Wire
	Textbox selectedTodoSubject;
	@Wire
	Radiogroup selectedTodoPriority;
	@Wire
	Datebox selectedTodoDate;
	@Wire
	Textbox selectedTodoDescription;
	@Wire
	Button updateSelectedTodo;


	//when user selects a todo of the listbox
	@Listen("onSelect = #todoListbox")
	public void doTodoSelect() {
		if(todoListModel.isSelectionEmpty()){
			//just in case for the no selection
			selectedTodo = null;
		}else{
			selectedTodo = todoListModel.getSelection().iterator().next();
		}
		refreshDetailView();
	}

	private void refreshDetailView() {
		//refresh the detail view of selected todo
		if(selectedTodo==null){
			//clean
			selectedTodoBlock.setVisible(false);
			selectedTodoCheck.setChecked(false);
			selectedTodoSubject.setValue(null);
			selectedTodoDate.setValue(null);
			selectedTodoDescription.setValue(null);
			updateSelectedTodo.setDisabled(true);
			
			priorityListModel.clearSelection();
		}else{
			selectedTodoBlock.setVisible(true);
			selectedTodoCheck.setChecked(selectedTodo.isComplete());
			selectedTodoSubject.setValue(selectedTodo.getSubject());
			selectedTodoDate.setValue(selectedTodo.getDate());
			selectedTodoDescription.setValue(selectedTodo.getDescription());
			updateSelectedTodo.setDisabled(false);
			
			priorityListModel.addToSelection(selectedTodo.getPriority());
		}
	}
...
}

• Line 29: Use @Listen to listen onSelect event of the Listbox whose id is todoListbox.
• Line 30: This method checks todoListModel's selection and refreshes the detail editor.
• Line 35: Get user selection from data model by getSelection() which returns a Set
• Line 40: If an item is selected, it makes detail editor visible and pushes data into those input components of the editor by calling setter methods. If no item selected, it turns detail editor invisible and clear all input components' value.
• Line 60: Use addToSelection() to control a component's selection and it will automatically reflect to the corresponding widget's selection.

After modifying item's detail, you can click "Update" button to save the modification or "Reload" to revert back original data. The following codes demonstrate how to implement these functions:

Handle clicking "update" and "reload" button

	//when user clicks the update button
	@Listen("onClick = #updateSelectedTodo")
	public void doUpdateClick(){
		if(Strings.isBlank(selectedTodoSubject.getValue())){
			Clients.showNotification("Nothing to do ?",selectedTodoSubject);
			return;
		}
		
		selectedTodo.setComplete(selectedTodoCheck.isChecked());
		selectedTodo.setSubject(selectedTodoSubject.getValue());
		selectedTodo.setDate(selectedTodoDate.getValue());
		selectedTodo.setDescription(selectedTodoDescription.getValue());
		selectedTodo.setPriority(priorityListModel.getSelection().iterator().next());
		
		//save data
		selectedTodo = todoListService.updateTodo(selectedTodo);
		
		//refresh listmodel for only 1 item
		todoListModel.set(todoListModel.indexOf(selectedTodo), selectedTodo);
		
		//show message for user
		Clients.showNotification("Todo saved");
	}
	
	//when user clicks the update button
	@Listen("onClick = #reloadSelectedTodo")
	public void doReloadClick(){
		refreshDetailView();
	}

Complete a Todo

Click a Checkbox in front of a todo item means to finish it. To implement this feature, the first problem is: how do we know which Checkbox is checked for there are many of them. Although we can use @Listen("onCheck = #todoListbox checkbox") to listen all CheckEvent under todo listbox, here we introduce "Event Forwarding" feature to demonstrate ZK's flexibility. This feature can forward an event from a component to another component, so we can forward all onCheck events from Checkbox to the Listbox that encloses them, then we can just listen Listbox's events instead of all events of Checkbox.

extracted from chapter6/todolist-mvc.zul

...
	<listbox id="todoListbox" vflex="1">
...
		<template name="model">
			<listitem sclass="${each.complete?'complete-todo':''}" value="${each}">
				<listcell>
					<checkbox forward="onCheck=todoListbox.onTodoCheck" checked="${each.complete}"/>
				</listcell>
				<listcell>
					<label value="${each.subject}"/>
				</listcell>
				<listcell>
					<button forward="onClick=todoListbox.onTodoDelete" image="/imgs/cross.png" width="36px"/>
				</listcell>
			</listitem>
		</template>

• Line 7: Forward Checkbox's onCheck to an event onTodoCheck of a Listbox whose id is todoListbox. The onTodoCheck is a customized forward event name, and you can use whatever name you want. Then we can use @Listen to listen this special event name.

Next, we listen the customized event onTodoCheck and mark the todo as finished.

public class TodoListController extends SelectorComposer<Component>{
...

	//when user checks on the checkbox of each todo on the list
	@Listen("onTodoCheck = #todoListbox")
	public void doTodoCheck(ForwardEvent evt){
		//get data from event
		Checkbox cbox = (Checkbox)evt.getOrigin().getTarget();
		Listitem litem = (Listitem)cbox.getParent().getParent();
		
		boolean checked = cbox.isChecked();
		Todo todo = (Todo)litem.getValue();
		todo.setComplete(checked);
		
		//save data
		todo = todoListService.updateTodo(todo);
		if(todo.equals(selectedTodo)){
			//refresh detail view
			refreshDetailView();
		}
		//update listitem style
		((Listitem)cbox.getParent().getParent()).setSclass(checked?"complete-todo":"");
	}
...
}

• Line 5: Listen the customized event name onTodoCheck of a Listbox todoListbox for we already forward onCheck to the Listbox in the zul.
• Line 6: An event listener method can have a argument for event, but which type depends on which event you listen. As the customized event is forwarded from another component, the argument should be ForwardEvent. This method set the Todo object of the selected item as complete and decorate Listitem with line-through by changing its sclass.
• Line 8: You should call getOrigin() to get the original event that is forwarded. Every event object has a method getTarget() that allows you get the target component that receives the event.
• Line 9: Navigate component tree by getParent() or getChildren.
• Line 12: Here we get Todo object of the selected todo item from value attribute that we assigned in the zul.

Create

After typing todo item name, we can create it by either clicking the button with plus icon or pressing "Enter" key. Therefore, we have to listen 2 events: onClick and onOK. About handling other key pressing event, please refer to ZK_Developer's_Reference/UI_Patterns/Keystroke_Handling.

public class TodoListController extends SelectorComposer<Component>{

	//wire components
	@Wire
	Textbox todoSubject;
	@Wire
	Button addTodo;
	@Wire
	Listbox todoListbox;
	
	@Wire
	Component selectedTodoBlock;
	@Wire
	Checkbox selectedTodoCheck;
	@Wire
	Textbox selectedTodoSubject;
	@Wire
	Radiogroup selectedTodoPriority;
	@Wire
	Datebox selectedTodoDate;
	@Wire
	Textbox selectedTodoDescription;
	@Wire
	Button updateSelectedTodo;
	
	//services
	TodoListService todoListService = new TodoListServiceChapter6Impl();
	
	//data for the view
	ListModelList<Todo> todoListModel;
	ListModelList<Priority> priorityListModel;
	Todo selectedTodo;

	...

	//when user clicks on the button or enters on the textbox
	@Listen("onClick = #addTodo; onOK = #todoSubject")
	public void doTodoAdd(){
		//get user input from view
		String subject = todoSubject.getValue();
		if(Strings.isBlank(subject)){
			Clients.showNotification("Nothing to do ?",todoSubject);
		}else{
			//save data
			selectedTodo = todoListService.saveTodo(new Todo(subject));
			//update the model of listbox
			todoListModel.add(selectedTodo);
			//set the new selection
			todoListModel.addToSelection(selectedTodo);
			
			//refresh detail view
			refreshDetailView();
			
			//reset value for fast typing.
			todoSubject.setValue("");
		}
	}
...
}

• Line 37: Listen the button's onClick event and "Enter" key pressing event: onOK.
• Line 38: This method add a todo item with a service object, update the data model of Listbox, change the selection to newly created one, then reset the input field of the Textbox.
• Line 40: Get user input in the Textbox todoSubject by getValue().
• Line 42: Show a notification at the right side of the Textbox todoSubject.
• Line 47: When you add a new item in a ListModelList object, it will automatically reflect to Listbox's rendering.

Delete

Implement deletion feature is similar to completing a todo item. We also forward each delete button's () onClick to the Listbox that encloses those buttons.

Forward delete button's onClick

	<listbox id="todoListbox" vflex="1">
...
		<template name="model">
			<listitem sclass="${each.complete?'complete-todo':''}" value="${each}">
				<listcell>
					<checkbox forward="onCheck=todoListbox.onTodoCheck" checked="${each.complete}"/>
				</listcell>
				<listcell>
					<label value="${each.subject}"/>
				</listcell>
				<listcell>
					<button forward="onClick=todoListbox.onTodoDelete" image="/imgs/cross.png" width="36px"/>
				</listcell>
			</listitem>
		</template>
...

• Line 12: Forward delete button's onClick to the Listbox's with custom forward event name onTodoDelete.

Then we can listen the forwarded event to perform deletion.

	//when user clicks the delete button of each todo on the list
	@Listen("onTodoDelete = #todoListbox")
	public void doTodoDelete(ForwardEvent evt){
		Button btn = (Button)evt.getOrigin().getTarget();
		Listitem litem = (Listitem)btn.getParent().getParent();
		
		Todo todo = (Todo)litem.getValue();
		
		//delete data
		todoListService.deleteTodo(todo);
		
		//update the model of listbox
		todoListModel.remove(todo);
		
		if(todo.equals(selectedTodo)){
			//refresh selected todo view
			selectedTodo = null;
			refreshDetailView();
		}
	}

MVVM Approach

Building user interface for example application in MVVM approach is very similar to building in MVC approach, but you don't have to give id to components since we don't need to identify components for wiring.

Read

As we have talked in previous chapter, display a collection of data requires to prepare a data model in the ViewModel.

public class TodoListViewModel implements Serializable{

	
	//services
	TodoListService todoListService = new TodoListServiceChapter6Impl();
	
	//data for the view
	String subject;
	ListModelList<Todo> todoListModel;
	Todo selectedTodo;

	@Init // @Init annotates a initial method
	public void init(){
		//get data from service and wrap it to model for the view
		List<Todo> todoList = todoListService.getTodoList();
		//you can use List directly, however use ListModelList provide efficient control in MVVM 
		todoListModel = new ListModelList<Todo>(todoList);
	}

...
}

• Line 10: A Todo object for binding selected todo item.
• Line 17: Initialize ListModelList with todoList retrieved with a service class.

Then we can bind Listbox's model to prepared data model with data binding expression.

	<listbox model="@bind(vm.todoListModel)" selectedItem="@bind(vm.selectedTodo)" vflex="1" >
		<listhead>
			<listheader width="30px" />
			<listheader/>
			<listheader hflex="min"/>
		</listhead>
		<template name="model">
			<listitem sclass="@bind(each.complete?'complete-todo':'')">
				<listcell>
					<checkbox checked="@bind(each.complete)" onCheck="@command('completeTodo',todo=each)"/>
				</listcell>
				<listcell>
					<label value="@bind(each.subject)"/>
				</listcell>
				<listcell>
					<button onClick="@command('deleteTodo',todo=each)" image="/imgs/cross.png" width="36px"/>
				</listcell>
			</listitem>
		</template>
	</listbox>

• Line 1: Set Listboxs data model by binding model attribute to a property of type ListModelList. Binding seleccteditem to vm.selectedTodo to keep selection state.
• Line 8: You can fill any valid EL expression In a data binding annotation, so that you can implement simple presentation logic with EL. Here we set sclass according to a Todo object's complete property.
• Line 10,13: Use implicit variable each to access each Todo object in the data model.