From Documentation

Jump to: navigation, search




  • Author
    Timothy Clare, Technology Evangelist, Potix Corporation
  • Date
    June 26, 2009
  • Version
    ZK Calendar 1.0.0 RC


Contents

Introducing ZK Calendar

ZK Calendar is an Ajax component that integrates rich and intuitive scheduling functionality into existing enterprise applications using pure Java. The calendar facilitates interaction with other Ajax components and the ability to customize functionality and styling.

The aim of the article is to build a web application using ZK Calendar and a database backend.


Demo


Creating the database

The database structure is simple and mirrors the event object defined by ZK Calendar. The model object is named SimpleCalendarEvent and stores such things as the color of the news item. In addition to the properties within the SimpleCalendarEvent we will need an id for each news item which will be the primary key and an auto incrementing field. We are using the MySQL server, however, this is just for an example you can use any server type, just make sure to change the data types accordingly. The table below shows the entire database structure:

News_item INTEGER Date_begin BIGINT Date_end BIGINT Title VARCHAR Content VARCHAR Header_color VARCHAR Content_color VARCHAR Zclass VARCHAR isLocked BIT

Here is the SQL statement to create the above table:

CREATE TABLE tblnews ( news_item int NOT NULL AUTO_INCREMENT, 
                                       date_begin bigint NOT NULL, 
                                       date_end bigint NOT NULL, 
                                       title varchar(200) NOT NULL, 
                                       content varchar(200) NOT NULL, 
                                       header_color varchar(10) NOT NULL, 
                                       content_color varchar(10) NOT NULL, 
                                       isLocked tinyint(1) NOT NULL, 
                                       PRIMARY KEY (news_item) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Interacting with the database

Linking the application with the database is the easy part and involves creating a DAO to handle the interaction. The DAO consists of functions to insert, update, delete and retrieve news items from the database. For more details please refer to the NewsDAO in the source.


These functions are the basic essentials for any application. The connection is handled via the MySQL J/Connector with a new connection being made for each operation. Please note that a new connection for each operation is NOT the best method of implementation, a connection pool would be far more efficient so please do not use the code for production level software.

Building the model

The model is based off the above datatable and implementing getters and setters for each field. The only interest choices of field type are the BIGINTs for each date. The choice was made to remove the need to format the date to put it into the database and do the same to take it out. The BIGINT is the time since epoc. Below is a sample extract from the NewsItem class which is used to represent an item object. This object extends SimpleCalendarModel and hence inherits all its’ fields.

public class NewsItem extends SimpleCalendarEvent {
	
	private int news_item;

	public int getNews_item() {
		return news_item;
	}
	
	public void setNews_item(int id) {
		news_item = id;
	}
	
	public NewsItem() {
		
	}
}


Building the UI

Creating ZK Calendar dialogs

We need two dialogs to handle the inserting, updating and deleting of items from the calendar. The createDialog will handle the creation of the items and the update dialog will handle the item updating and deletion. Calendar.zul

The zul file is very simple, only containing the calendar and a window. The window is then wired to the controller, NewsController, using the MVC pattern. In addition to this the CreateDialog and UpdateDialog macro components are declared at the top of the file and included in the Window. The code is shown below.

<?page title="News Calendar" contentType="text/html;charset=UTF-8"?>
<?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit"?>
<?component name="CreateDialog" macroURI="createEntry.zul"?>
<?component name="UpdateDialog" macroURI="updateEntry.zul"?>
<zk>
	<window id="win" title="news" border="none" apply="org.zkoss.zknewsfeed.controllers.NewsController" height="100%" width="100%">
		<CreateDialog id="creationDialog" />
		<UpdateDialog id="updateDialog" />
		
		<calendars firstDayOfWeek="Sunday" timeZone="Taiwan=GMT+8" model="@{win$composer.getCalendarModel}" 
			 mold="default" id="cal">
			 	
			 </calendars>
	</window>
</zk>


Create Dialog

The creation dialog is implemented using the MVC design patter and hence uses the controller EventCreationController.

Firstly, we need to display the dialog and this is again handled using the MVC pattern. We implement the function

public void onEventCreate$cal(ForwardEvent event)

within the NewsController the handle the creation of the creation dialog. The creation dialog in itself is simple and just consists of the minimal required fields. For the sake of simplicity we have cut down on the number of fields that the user can edit.

<zk>
	<window id="create_my_entry" title="Create Entry" border="normal" mode="popup" apply="org.zkoss.zknewsfeed.controllers.EventCreationController" visible="false">
		<grid>
			<rows>
				<row>
					Item: <textbox id="tbText" cols="40" value="" />
				</row>
				<row>
					Type: <combobox id="cmbType">
						<comboitem label="Release" />
						<comboitem label="Small talk" />
						<comboitem label="Event" />
					  </combobox>
				</row>
				<row>
					Submit:
					<button id="btnAddNews" label="Create" width="36px" height="24px"/>
					<button id="btnCancel" label="Cancel" width="36px" height="24px" />
				</row>	
			</rows>
		</grid>
	</window>
</zk>

Upon creation of the dialog we need to provide it with some information, this is handled in the NewsController just after the creation of the dialog. Using setAttribute calls we can provide the dialog with the required event and calendar information as well as setting the fields within the dialog as shown below:

creationDialog.setAttribute("calendars", cal);
creationDialog.setAttribute("calevent", evt);

When creating the item, the dialog needs to add it to the database and the model, this is achieved using the DAO and the authors extra abstraction in the form of a class to handle the model.

DatabaseCalendarModel.dao.insertNewsItem(ni);
DatabaseCalendarModel.cm.add(ni);


Update Dialog

The Update dialog is very similar to the Creation except it also contains a deletion method. In addition to this the Update dialog is passed the news item (which contains an id) so that it knows which item in the database to update.

<zk>
	<window id="update_my_entry" title="Update Entry" border="normal" mode="popup" apply="org.zkoss.zknewsfeed.controllers.EventUpdateController" visible="false">
		<grid>
			<rows>
				<row>
					Item: <textbox id="tbText" cols="40" value="" />
				</row>
				<row>
					Type: <combobox id="cmbType">
						<comboitem label="Release" />
						<comboitem label="Small talk" />
						<comboitem label="Event" />
					  </combobox>
				</row>
				<row>
					Submit:
					<button id="btnUpdateNews" label="Create" width="36px" height="24px"/>
					<button id="btnDeleteNews" label="Delete" width="36px" height="24px"/>
					<button id="btnCancel" label="Cancel" width="36px" height="24px" />
				</row>	
			</rows>
		</grid>
	</window>
</zk>

Apart from the use of a news item when setting the attribute there is no other real difference between the creation and update dialog in the way they work. Please explore the source code for more information on the dialog.


Loading the Calendar model from the Calendar

The NewsController

The retrieval of the model from the database is the most important part. The Window in calendar.zul is linked with the NewsController and hence we are able to set the calendar to retrieve its’ model from the same class. This is done by creating the function

public SimpleCalendarModel getCalendarModel() {
	DatabaseCalendarModel dcm = new DatabaseCalendarModel();
	piechart.setModel(dcm.getSimplePieModel());
	return dcm.getSimpleCalendarModel();
}

The constructor of the DatabaseCalendarModel reloads the model from the database. It really is this simple to implement the interaction between the calendar and the database.


Adding extra functionality

Interacting with other ZK Components

The power of ZK Calendar lies in the fact that it can be used to interact with other controls, in this example we are going to use a pie chart to display the types of news items and how many of each news items there are.


Implementing a charting system

The implementation is very easy, upon resetting the calendar’s model we need to also update the chart’s mode. This is not as complex as it seems, the most complex part is counting the types available. The code below demonstrates the creation of both models:


public DatabaseCalendarModel() {
		_simpleCalendarModel = new SimpleCalendarModel();
		_simplePieModel = new SimplePieModel();
		
		int counts[] = {0, 0, 0};
		
		java.util.List lst = dao.selectAll();
		
		for(int i=0; i<lst.size(); i++) {
			NewsItem ni = (NewsItem) lst.get(i);
			_simpleCalendarModel.add(ni);
			
			int colorPos = NewsColors.getColorPosition(ni.getContentColor());
			
			if(colorPos >-1) {
				counts[colorPos]++;
		}
	}
	
	for(int j=0; j<3; j++) {
		Integer count = new Integer(counts[j]);
		_simplePieModel.setValue(NewsColors._type[j], count);
	}
}

While looping through all the news items, the types are counted and then we construct the pie model for each color. Once this is implemented all we need is to give the pie chart the model. This is achieved by setting the pie charts model upon retrieval of the calendar’s model, as demonstrated below:

public SimpleCalendarModel getCalendarModel() {
	DatabaseCalendarModel dcm = new DatabaseCalendarModel();
	piechart.setModel(dcm.getSimplePieModel());
	return dcm.getSimpleCalendarModel();
}

Source Code

To obtain the source code please download the WAR file below and then extract it to a place of your choosing.

ZKNewsExamp.war




Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.
You got stuck here?
Let us know why!
For questions please use the forum