Integrate ZK Calendar With A Database

{{Template:Smalltalk_Author|
|author=Timothy Clare, Technology Evangelist, Potix Corporation
|date=June 26, 2009
|version=ZK Calendar 1.0.0 RC
}}


== 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 ==

<gflash width="800" height="475">qoCcsr0rpTQ.swf</gflash>

== 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:

<source lang="sql">
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;
</source>

== 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.

<source lang="java">
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() {
		
	}
}</source> 


== 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.

<source lang="xml">
<?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></source>


=== 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 

<source lang="java">
public void onEventCreate$cal(ForwardEvent event)</source>

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.

<source lang="xml">
<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></source>

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:

<source lang="java">
creationDialog.setAttribute("calendars", cal);
creationDialog.setAttribute("calevent", evt);</source>

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.

<source lang="java">
DatabaseCalendarModel.dao.insertNewsItem(ni);
DatabaseCalendarModel.cm.add(ni);</source>


=== 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.

<source lang="xml">
<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></source>

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

<source lang="java">
public SimpleCalendarModel getCalendarModel() {
	DatabaseCalendarModel dcm = new DatabaseCalendarModel();
	piechart.setModel(dcm.getSimplePieModel());
	return dcm.getSimpleCalendarModel();
}</source>

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:


<source lang="java">
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);
	}
}</source>

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:

<source lang="java">
public SimpleCalendarModel getCalendarModel() {
	DatabaseCalendarModel dcm = new DatabaseCalendarModel();
	piechart.setModel(dcm.getSimplePieModel());
	return dcm.getSimpleCalendarModel();
}</source>

== Source Code ==

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

[https://sourceforge.net/project/downloading.php?group_id=156140&filename=ZKNewsExamp.war&a=96720434 ZKNewsExamp.war]


<comment>/smalltalks/zkcalendar/index.dsp</comment>

[[Category:ZK Calendar]]
[[Category:JDBC]]
{{Template:Smalltalk_Footer|
|name=Potix Corporation
}}