Sie sind auf Seite 1von 28

ZK Calendar Essentials

The essentials of ZK Calendar

PDF generated using the open source mwlib toolkit. See http://code.pediapress.com/ for more information.
PDF generated at: Mon, 22 Mar 2010 08:53:13 CET

Contents
Articles
ZK Calendar Essentials

ZK Calendar Essentials/Introduction

ZK Calendar Essentials/Getting Started with ZK Calendar

ZK Calendar Essentials/Getting Started with ZK Calendar/Setting Up ZK Calendar

ZK Calendar Essentials/Getting Started with ZK Calendar/The ZK Calendar Component

ZK Calendar Essentials/Working with ZK Calendar

ZK Calendar Essentials/Working with ZK Calendar/Initializing View Attributes

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data

ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/


Managing Event Data

ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/


Managing Event Data/SimpleCalendarEvent

11

ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/


Managing Event Data/Date Formatting

12

ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/


Managing Event Data/Multiple Timezones

13

ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/


Storing Event Data in Memory

14

ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/


Presenting Event Data

15

ZK Calendar Essentials/Working with ZK Calendar/Implementing ZK Calendar Event Listeners

17

ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners/


Introducing ZK MVC

18

ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners/


Declaring Events

20

ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners/


The CalendarsEvent Object

21

ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners/


Devising an Input Method

22

References
Article Sources and Contributors

25

Image Sources, Licenses and Contributors

26

ZK Calendar Essentials

ZK Calendar Essentials
<CollectionIndex>Documentation:Books/ZK_Calendar_Essentials</CollectionIndex>

ZK Calendar Essentials/Introduction
ZK Calendar is a Google Calendar like Ajax component that integrates rich and intuitive scheduling functionality
into enterprise web applications using pure Java. One of the main benefits of ZK Calendar is it can be embedded into
existing Java applications with minimal effort. The calendar facilitates interaction with other Ajax components and
the ability to customize functionality and styling.
ZK Calendar boasts all the advanced features of a modern day calendar such as daily, weekly, and monthly views,
drag-n-drop, multiple time zones, and permission control.

ZK Calendar Essentials/Getting Started with ZK Calendar

ZK Calendar Essentials/Getting Started with ZK


Calendar
This sections aims to walk through setting up ZK Calendar and provide a brief overview on the main essentials of
ZK Calendar.
<CollectionMiniIndex
book="Documentation:Books/ZK_Calendar_Essentials&#10;"
Essentials&#10;"> </CollectionMiniIndex>

page="ZK

Calendar

ZK Calendar Essentials/Getting Started with ZK


Calendar/Setting Up ZK Calendar
To enable use of ZK Calendar there are a few prerequisites.

Prerequisites
Downloaded ZK 5 CE (or higher) from [1]
Downloaded ZK Calendar 2.0 from [2]

Installing the libraries


Depending on your IDE the steps will differ, however the most important part is both ZK Calendar and ZKs JAR
files are included in your project. The project should be a ZK Project or a Web Application Project depending on
what environment you are using.
The easiest way to create a compatible project is to use ZK Studio [3] and then include calendar.jar as a library.

A Very Basic Application


Having set-up ZK and ZK Calendar in the environment we need to create an index.zul file. We can then place the
following code into it.
<?xml version="1.0" encoding="UTF-8"?>
<zk xmlns="http://www.zkoss.org/2005/zul">
<calendars />
</zk>
This gives us our very first ZK Calendar application. When the code is started, navigate to index.zul and the
following page should be displayed.

ZK Calendar Essentials/Getting Started with ZK Calendar/Setting Up ZK Calendar

Congratulations! That is all it takes to embed ZK Calendar within your ZK application.

References
[1] http:/ / www. zkoss. org/ download/ zk. dsp
[2] http:/ / www. zkoss. org/ download/ zkcalendar. dsp
[3] http:/ / www. zkoss. org/ download/ zkstudio. dsp

ZK Calendar Essentials/Getting Started with ZK Calendar/The ZK Calendar Component

ZK Calendar Essentials/Getting Started with ZK


Calendar/The ZK Calendar Component
The ZK Calendar Component
In this section, a brief overview is given on how developers work with the ZK Calendar component.
The Bare Calendar Component
ZK Calendar is a single ZK component. Developers could declare it within any ZK container components, such as
Window, tabs, groupbox, etc.
For example:
<window title="Bare ZK Calendar" border="normal">
<calendars/>
</window>
which renders:

The
bare <calendars> declaration takes the following default values: <calendars firstDayOfWeek="Sunday"
mold="default" >

ZK Calendar Essentials/Getting Started with ZK Calendar/The ZK Calendar Component


Calendar Component Attributes
Developers customize the calendars component by declaring its attributes, for example:
the first day of week to be displayed on the calendar, by default: firstDayOfWeek="Sunday"
the default mold (mold="default") displays a "date-time" format in which it displays hours of the day and days of
a week ; the monthly mold (mold="monthly") displays the days in a month
the time zone, for example: timeZone="Finland=GMT+2"
size of the calendar component, for example: width="400px" height="600px"
Triggered Calendar Events
The calendar component triggers three events when users select time slots on ZK Calendar:
onEventCreate
onEventEdit
onEventUpdate
Developers implement the corresponding event listeners to allow writing, editing, and updating (time updates) of
calendar events (appointments) to data models. These methods pass the object to the event listeners and information
such as begin date and end date of the selected time slot.
Calendar Event Data Objects
Developers implement the <javadoc type="interface">org.zkoss.calendar.api.CalendarEvent</javadoc> interface, or
use the default implementation <javadoc>org.zkoss.calendar.impl.SimpleCalendarEvent</javadoc> to set
information just as begin date and end date to the event data object after retrieving such information from the
<javadoc>org.zkoss.calendar.event.CalendarsEvent</javadoc>.
Calendar Event Date Model
Developers implement the <javadoc type="interface">org.zkoss.calendar.api.CalendarModel</javadoc> interface, or
use the default implementation <javadoc>org.zkoss.calendar.impl.SimpleCalendarModel</javadoc> to store event
data objects

ZK Calendar Essentials/Working with ZK Calendar

ZK Calendar Essentials/Working with ZK


Calendar
This section details all the methods to know how to build substantial applications which make use of Zk Calendars
many features.
<CollectionMiniIndex
book="Documentation:Books/ZK_Calendar_Essentials&#10;"
Essentials&#10;"> </CollectionMiniIndex>

page="ZK

Calendar

ZK Calendar Essentials/Working with ZK


Calendar/Initializing View Attributes
Laying out ZK Calendar
ZK Calendar has several options built in which enables us to specify how we want our information to be displayed.
ZK Calendar also enables us to embed a Toolbar as a child component into the calendar to provide users with a more
interactive experience.
The easiest way to control the look and performance of ZK Calendar is by changing its attributes.

ZK Calendar Attributes
The following table details ZK Calendars attributes and their usage.
Attribute
readonly

Usage
Sets whether it is readonly

Default Value
false

firstDayOfWeek Sets what the first day of the week is; e.g., SUNDAY in the
U.S., MONDAY in France

system default

currentDate

Sets the current date

today (depend on which timezone the system is using)

days

Sets the days, that is, how many column should be


displayed on the default mold

7 (i.e. one week)

dateFormatter

Sets the date formatter. In fact, there are five places in the
calendar must have different date display

<javadoc>org.zkoss.calendar.impl.SimpleDateFormatter</javadoc>

model

Sets the calendar model

null

mold

Sets the calendar mold

default

The best way to understand how attributes work is to follow an example. In this example we will concentrate on the
"mold" attribute.

ZK Calendar Essentials/Working with ZK Calendar/Initializing View Attributes

An Example: The Mold Attribute


The mold attribute dictates what view the user will see. There are two molds, the default and
The Default Mold
In the default mold the content of the calendar is separated into two parts. The main component area is where date
time events are displayed and the top of the Calendar component is used to display the daylong event.

ZK Calendar Essentials/Working with ZK Calendar/Initializing View Attributes


The Month Mold
In the month mold the date time event has no background color, the text is colored and the daylong event has a
background color with white text. When utilising the month mold, each row represents one week.

By just changing one attribute ZK affords us exceptional power. But how do we change this attribute? The next
section explains how.

Setting attributes
We are able to set attributes in a zul file or Java file. The following examples outline how to do this.
In ZUL Files
<calendars id="calendar" height="80%" firstDayOfWeek="Sunday"
timeZone="California=PDT-8" mold="default"
readonly="true" />
In Java Files
calendar.setMold("default");
calendar.setTimeZone("California=PDT-8");
calendar.setFirstDayOfWeek("Sunday");
calendar.setReadonly(true);

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data

ZK Calendar Essentials/Working with ZK


Calendar/Displaying ZK Calendar Event Data
The most important part of a scheduling application is to handle and display data. This sections walks through how
to manage, store and ultimately display data.
<CollectionMiniIndex
book="Documentation:Books/ZK_Calendar_Essentials&#10;"
Essentials/Working with ZK Calendar&#10;"> </CollectionMiniIndex>

page="ZK

Calendar

ZK Calendar Essentials/Working with ZK


Calendar/Displaying ZK Calendar Event Data/
Managing Event Data
The CalendarEvent interface
It is important when working with the calendar to effectively manage the event data of the calendar. The event data
is
contained
in
a
class
which
implements
<javadoc
type="interface">org.zkoss.calendar.api.CalendarEvent</javadoc>.
An implementing Object should provide the following functions:
Method

Usage

getBeginDate

Returns the beginning date of the calendar event.

getEndDate

Returns the end date of the calendar event.(exclusive)

getTitle

Returns the title of the calendar event.

getContent

Returns the content of the calendar event.

getHeaderColor

Returns the color of the header in the calendar event. Only allows the value being recognized by CSS.

getContentColor Returns the color of the content in the calendar event. Only allows the value being recognized by CSS.
getZclass

Returns the zclass of the calendar event.

isLocked

Returns whether the calendar event is locked or not.

A CalendarEvent implementation
The code snippet below details a basic class which would fulfill the contract of the <javadoc
type="interface">org.zkoss.calendar.api.CalendarEvent</javadoc> interface.
import java.util.Date;
import org.zkoss.calendar.api.CalendarEvent;
/**
* A non functional implementation of the CalendarEvent
*
*/
public class MyCalendarEvent implements CalendarEvent {

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data/Managing Event Data


public Date getBeginDate() {
return new Date();
}
public Date getEndDate() {
return new Date();
}
public String getTitle() {
return "";
}
public String getContent() {
return "";
}
public String getHeaderColor() {
return "";
}
public String getContentColor() {
return "";
}
public String getZclass() {
return "";
}
public boolean isLocked() {
return false;
}
}
In a real implementation the above class is useless as it does not contain any meaningful data. We could expand on
the class so it could save state information. However, ZK Calendar already provides a class named
<javadoc>org.zkoss.calendar.impl.SimpleCalendarEvent</javadoc> which provides the relevant functionality for
you. This class is discussed here.

10

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data/Managing Event


Data/SimpleCalendarEvent

ZK Calendar Essentials/Working with ZK


Calendar/Displaying ZK Calendar Event Data/
Managing Event Data/SimpleCalendarEvent
The <javadoc>org.zkoss.calendar.impl.SimpleCalendarEvent</javadoc> is an implementation of the interface
<javadoc type="interface">org.zkoss.calendar.api.CalendarEvent</javadoc>. It provides us with a readily available
class which we can use directly in ZK Calendar applications.

How to use SimpleCalendarEvent


Using <javadoc>org.zkoss.calendar.impl.SimpleCalendarEvent</javadoc> is a simple affair. The code below
demonstrates how to construct an instance and provide it with necessary data.
SimpleCalendarEvent sce = new SimpleCalendarEvent();
sce.setBeginDate(new Date());
sce.setEndDate(new Date());
//The color Strings should only be colors
//that CSS accept
sce.setContentColor("red");
sce.setHeaderColor("red");
sce.setContent("This is the content of the event");
sce.setTitle("This is the title of the event");
//is this event locked?
sce.setLocked(false);
Most of the values described above are self explanatory. However, we do need to pay particularly close attention to
<mp>setContentColor</mp> and <mp>setHeaderColor</mp> which only accept String values which represent valid
CSS colors. These can be hex or named strings as both are accepted by the CSS specification.

11

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data/Managing Event Data/Date


Formatting

ZK Calendar Essentials/Working with ZK


Calendar/Displaying ZK Calendar Event Data/
Managing Event Data/Date Formatting
To enable us to format dates how we require them ZK Calendar provides the interface <javadoc
type="interface">org.zkoss.calendar.api.DateFormatter</javadoc>.

The DateFormatter interface


The <javadoc type="interface">org.zkoss.calendar.api.DateFormatter</javadoc> interface requires 5 methods to be
implemented. These are as follows:
Method

Usage

getCaptionByDayOfWeek

Returns the caption of the day of week.

getCaptionByTimeOfDay

Returns the caption of the time of day.

getCaptionByDate

Returns the caption of the date.

getCaptionByDateOfMonth Returns the caption of the date of month.


getCaptionByPopup

Returns the caption of the popup title.

Each function enables us to customize the appearance of the calendar at any opportunity. Implementing an interface
such as this is excellent if you require fine grained control. If you do not require such level of control then ZK
Calendar provides you with an implementation.

The SimpleDateFormatter Class


ZK Calendar provides us with the <javadoc>org.zkoss.calendar.impl.SimpleDateFormatter</javadoc> class which
enables rapid development of ZK Calendar applications. The implementation is used by default within ZK Calendar.
In some circumstances you may require a more powerful implementation and therefore need to create a
customization.

Using a Customized DateFormatter Implementation


To make use of a customized <javadoc type="interface">org.zkoss.calendar.api.DateFormatter</javadoc>
implementation we need to inform ZK Calendar that we are using our own implementation of <javadoc
type="interface">org.zkoss.calendar.api.DateFormatter</javadoc>. To do this we make use of a custom
implementation we call the <mp>setDateFormatter</mp> on ZK Calendar, for example:
calendar.setDateFormatter(new MyDateFormatter());

12

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data/Managing Event Data/Multiple


Timezones

ZK Calendar Essentials/Working with ZK


Calendar/Displaying ZK Calendar Event Data/
Managing Event Data/Multiple Timezones
In ZK Calendar the default time zone is the first timezone which was added. If no time zone was entered then the
systems time zone is taken as default. All the dates in the Calendar component use UTC coordinated universal time
[1]
. If you wish to show the date and time with regard to your settings you need to use the function
<mp>getDefaultTimeZone()</mp> to retrieve the local time and use that to format your date and time.
For example:
SimpleDateFormat create_sdf = new SimpleDateFormat("HH:mm");
create_sdf.setTimeZone(calendars.getDefaultTimeZone());
Calendar cal =
Calendar.getInstance(org.zkoss.util.Locales.getCurrent());
String[] times = create_sdf.format(evt.getBeginDate()).split(":");
int hours = Integer.parseInt(times[0])*2;
int mins = Integer.parseInt(times[1]);
if (mins >= 30) hours++;
createEvent.getFellow("ppbt").setSelectedIndex(hours);
The above example is used to display the correct time of day in a Listbox.

References
[1] http:/ / en. wikipedia. org/ wiki/ UTC

13

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data/Storing Event Data in Memory

ZK Calendar Essentials/Working with ZK


Calendar/Displaying ZK Calendar Event Data/
Storing Event Data in Memory
It is easy to store scheduled data in memory and can be done by using the
<javadoc>org.zkoss.calendar.impl.SimpleCalendarModel</javadoc>. This model provides functions to add and
remove <javadoc type="interface">org.zkoss.calendar.api.CalendarEvent</javadoc>s.
The following code demonstrates how to generate and store
<javadoc>org.zkoss.calendar.impl.SimpleCalendarModel</javadoc>.

few

SimpleCalendarModel scm = new SimpleCalendarModel();


public void addToModel(CalendarEvent ce) {
scm.add(ce);
}
public CalendarEvent createRandomEvent() {
SimpleCalendarEvent sce = new SimpleCalendarEvent();
Random generator = new Random();
long timeNow = new Date().getTime();
long roundedTime = timeNow - (timeNow % 1000);
Calendar cal = Calendar.getInstance();
cal.setTimeInMillis(roundedTime);
cal.add(Calendar.HOUR, -(generator.nextInt(3) + 2));
sce.setBeginDate(cal.getTime());
System.out.println(cal.getTime());
cal.setTimeInMillis(roundedTime);
cal.add(Calendar.HOUR, generator.nextInt(3) + 1);
sce.setEndDate(cal.getTime());
System.out.println(cal.getTime());
//The color Strings should only be colors
//that CSS accept
sce.setContentColor("red");
sce.setHeaderColor("red");
sce.setContent("This is the content of the event");
sce.setTitle("This is the title of the event");
//is this event locked?
sce.setLocked(false);

random

events

in

the

14

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data/Storing Event Data in Memory
return sce;
}
public void createData() {
scm = new SimpleCalendarModel();
for(int i=0; i<3; i++) {
CalendarEvent ce = createRandomEvent();
addToModel(ce);
}
}
This code can then be incorporated to function as the in memory model for ZK Calendar. We discuss this in
Presenting Event Data

ZK Calendar Essentials/Working with ZK


Calendar/Displaying ZK Calendar Event Data/
Presenting Event Data
Having constructed a memory model we can now go ahead and adjust this code to work in a functional ZK Calendar
application. The code below is a fully working readonly calendar which creates random events when the button is
clicked. This gives a full example using a memory model with ZK Calendar.
<?xml version="1.0" encoding="UTF-8"?>
<zk xmlns="http://www.zkoss.org/2005/zul">
<window height="100%" width="100%">
<zscript>
<![CDATA[
SimpleCalendarModel scm = new SimpleCalendarModel();
public void addToModel(CalendarEvent ce) {
scm.add(ce);
}
public CalendarEvent createRandomEvent() {
SimpleCalendarEvent sce = new
SimpleCalendarEvent();
Random generator = new Random();
long timeNow = new Date().getTime();
long roundedTime = timeNow - (timeNow % 1000);
java.util.Calendar cal =
java.util.Calendar.getInstance();
cal.setTimeInMillis(roundedTime);

15

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data/Presenting Event Data


cal.add(java.util.Calendar.HOUR,
-(generator.nextInt(3) + 2));
sce.setBeginDate(cal.getTime());
System.out.println(cal.getTime());
cal.setTimeInMillis(roundedTime);
cal.add(java.util.Calendar.HOUR,
generator.nextInt(3) + 1);
sce.setEndDate(cal.getTime());
System.out.println(cal.getTime());
//The color Strings should only be colors
//that CSS accept
sce.setContentColor("red");
sce.setHeaderColor("red");
sce.setContent("This is the content of the event");
sce.setTitle("This is the title of the event");
//is this event locked?
sce.setLocked(false);
return sce;
}
public void createData() {
scm = new SimpleCalendarModel();
for(int i=0; i<3; i++) {
CalendarEvent ce = createRandomEvent();
addToModel(ce);
}
calendar.setModel(scm);
}
]]>
</zscript>
<calendars id="calendar" height="80%" firstDayOfWeek="Sunday"
timeZone="California=PDT-8" mold="default"
readonly="true" />
<button id="createData" label="Create Data" onClick="createData()" />
</window>
</zk>
The above code's output is shown below.

16

ZK Calendar Essentials/Working with ZK Calendar/Displaying ZK Calendar Event Data/Presenting Event Data

17

ZK Calendar Essentials/Working with ZK


Calendar/Implementing ZK Calendar Event
Listeners
In this section, we'll discuss:
the events triggered on the ZK Calendar component
the ZK MVC approach to handling events
how to devise an input dialog to create, edit, and update events on ZK Calendar
<CollectionMiniIndex
book="Documentation:Books/ZK_Calendar_Essentials&#10;"
Essentials/Working with ZK Calendar&#10;"> </CollectionMiniIndex>

page="ZK

Calendar

ZK Calendar Essentials/Working with ZK Calendar/Implementing ZK Calendar Event Listeners/Introducing ZK MVC

18

ZK Calendar Essentials/Working with ZK


Calendar/Implementing ZK Calendar Event
Listeners/Introducing ZK MVC
Introducing ZK Calendar MVC
ZK MVC pattern is an adaptation of the popular Model-View-Controller architecture in the ZK framework. The
ability to separate concerns in multifaceted web applications is a key advantage of employing a server-driven Ajax
framework. In this section, we'll walk through a basic ZK MVC application that generates your lucky numbers for
the next round of lotto mayhem.
The View
In ZK MVC pattern, Developers construct "view" by declaring ZK components in a ZUL file.
For our lotto example:
view.zul
<window title="ZK MVC" border="normal" width="300px" apply="org.zkoss.mvc.Controller">
<vbox id="view">
<button label="Get Your Lotto Number!" id="genBtn"></button>
</vbox>
</window>
Where we declare a Window component as a container for other widgets, a Vbox to stack up components vertically,
and a button to generate the lotto numbers. It is imperative to assign the Button component and the Vbox component
identification strings (id = " ") so that auto-wiring is possible.
The Model
"Model" in a ZK MVC application is no different from other MVC implementations. Under the ZK MVC approach,
developers work with the data manipulations in Java, not in ZUL.
Model.java
package org.zkoss.mvc;
import java.util.ArrayList;
public class Model {
public static ArrayList<Integer> genLottoList(){
ArrayList<Integer> numList = new ArrayList<Integer>();
while (numList.size() < 6){
Integer num = getNum();
while (numList.contains(num)){num = getNum();}
numList.add(num);
}
return numList;
}

ZK Calendar Essentials/Working with ZK Calendar/Implementing ZK Calendar Event Listeners/Introducing ZK MVC


public static int getNum(){
int num = ((int)(Math.random()*49)) + 1;
return num;
}
}
The Controller
ZK provides a convenient pattern for the MVC practice, in the "controller" class we need to:
extend the helper class <javadoc>org.zkoss.zk.ui.util.GenericForwardComposer</javadoc> so that events would
be forwarded to the corresponding event handlers
declare the ZK component fields for auto-wiring, in this example: Button getBtn; Vbox view;
name the event listeners, the event listener's name is in the format of "onEvent$ID", where "onEvent" is the event
fired, and "ID" is the ID of the ZK component triggered the event. In this example the event fired is "onClick" and
the ZK component that triggered the onClick event is the button with the ID "getBtn"
Controller.java
package org.zkoss.mvc;
import
import
import
import

org.zkoss.zk.ui.util.GenericForwardComposer;
org.zkoss.zul.Button;
org.zkoss.zul.Textbox;
org.zkoss.zul.Vbox;

public class Controller extends GenericForwardComposer {


private Button genBtn;
private Vbox view;
public void onClick$genBtn(){
Textbox text = new Textbox();
text.setWidth("180px");
text.setValue(""+Model.genLottoList());
text.setParent(view);
}
}
With these three essentials steps done, we can now turn our attention to implementing the event listeners. In the
event listener, we create a text box to contain the randomly generated lotto numbers, and set its width to 180 pixels.
We then call <mp>getLottoList()</mp> to obtain the lotto numbers and set them as the text box's value. Finally, we
set the Vbox (id = "view") as the text box's parent so that each text box generated will line up vertically. Please note
that the object Button and Vbox are automatically instantiated when the ZUL file (view.zul ) is parsed by ZK.

19

ZK Calendar Essentials/Working with ZK Calendar/Implementing ZK Calendar Event Listeners/Introducing ZK MVC


Running this example gives us:

This section demonstrated a simple way to implement the ZK MVC pattern, in the next, we'll see how this technique
is adapted in making a ZK Calendar.

ZK Calendar Essentials/Working with ZK


Calendar/Implementing ZK Calendar Event
Listeners/Declaring Events
Declaring Events
The ZK Calendar Event Listeners
The ZK Calendar component recognizes three events:
onEventCreate
This event is triggered when a user clicks an empty cell in the time schedule grid.
onEventEdit
This event is triggered when a user clicks on a cell in the time schedule grid that is already occupied by a scheduled
event.
onEventUpdate
This event is triggered when a user modifies a scheduled event's span, or when the scheduled event is dragged and
dropped to a different date.
Developers implement these event listeners either in a Java file, or in a ZUL file.
Implementation in Java
Consider the brief example below; we first specify the ID of the Calendar component in the ZUL file:
<calendars
...
...

id="calendarID">

then create a class that extends <javadoc>org.zkoss.zk.ui.util.GenericForwardComposer</javadoc> to engage data


binding and forward the triggered event (<javadoc>org.zkoss.calendar.event.CalendarsEvent</javadoc> object) to its
corresponding event listeners:
private org.zkoss.zul.Calendar calendarID;

20

ZK Calendar Essentials/Working with ZK Calendar/Implementing ZK Calendar Event Listeners/Declaring Events


public void onEventCreate$calendarID (CalendarsEvent event){
//invoke event scheduling input method
...
...
}
Implementation in ZUL
As an example declaring event listeners in ZUL:
<calendars id="calendarID">
<attribute name="onEventCreate"><! [CDATA[
CalendarsEvent evnt = (CalendarsEvent) event;
<!-- invoke event scheduling input method-->
]]>
</attribute>
...
...
</calendars>

ZK Calendar Essentials/Working with ZK


Calendar/Implementing ZK Calendar Event
Listeners/The CalendarsEvent Object
The CalendarsEvent Object
The <javadoc>org.zkoss.calendar.event.CalendarsEvent</javadoc> object is passed to the event handler when
onCreateEvent, onEditEvent, and onUpdateEvent is triggered by creating, editing, and updating event data on ZK
Calendar, respectively.
Developers could use the methods outlined below to retrieve information about the event being triggered.
Method

Usage

stopClearGhost

Stops to clear the dragging ghost command

clearGhost

Clears the dragging ghost

getBeginDate

Returns the updated beginning date. If the event name is onEventEdit, null is assumed

getEndDate

Returns the updated end date. If the event name is onEventEdit, null is assumed

getCalendarEvent Returns the calendar event. If the event name is onEventCreate, null is assumed
getX

Returns the x coordination of the mouse pointer relevant to the component

getY

Returns the y coordination of the mouse pointer relevant to the component

getDesktopWidth Returns the pixel width of the client's desktop


getDesktopHeight Returns the pixel height of the client's desktop

21

ZK Calendar Essentials/Working with ZK Calendar/Implementing ZK Calendar Event Listeners/Devising an Input


Method

22

ZK Calendar Essentials/Working with ZK


Calendar/Implementing ZK Calendar Event
Listeners/Devising an Input Method
Devising an Input Dialog
When a user selects a time slot on ZK Calendar, an input dialog is necessary for users to enter certain information for
that particular appointment; for example, the event title, the description, choosing a distinctive color to mark the
event, etc. We could accomplish this by creating a customized ZK component, called a ZK Macro Component, that
allows users to input the appointment related information. The information entered may then be displayed on ZK
Calendar and persisted in storage.
Making an Input Dialog
Constructing a Book-Event-Dialog
Consider implementing an input dialog for booking an appointment on ZK Calendar as an example. Here we make
the premise that a ZK Calendars component, with id = "cal", is already declared in a ZUL file named "calendar.zul"
<?page title="ZK Calendar"?>
<?component name="BookEventDialog" macro-uri="bookEvent.zul"?>

<window id="win" title="ZK Calendar" border="normal" width="800px" height="800px" apply="


<BookEventDialog id="bookingDialog"/>
<calendars firstDayOfWeek="Sunday" mold="default" id="cal" >
</calendars>
</window>
Create a new ZUL file named: bookEvent.zul
In bookEvent.zul,
declare and construct the book-event-dialog, be sure to give an id to the Window component <window
id="EventBooking"...>
denote the <javadoc>org.zkoss.zk.ui.util.GenericForwardComposer</javadoc> extension, in this case <window
id="EventBooking" apply="org.zkoss.cal.CalendarCtrl">
make the EventBooking window invisible before it is called <window id="EventBooking" visible="false">
<zk>

<window id="EventBooking" title="Event Booking" border="normal" mode="popup" apply=


<grid width="400px">
<rows>
<row>
Title: <textbox width="70%" id="tbTitle" />
</row>
<row>
Note: <textbox height="80px" width="70%" id="tbNote" />
</row>
<row>

ZK Calendar Essentials/Working with ZK Calendar/Implementing ZK Calendar Event Listeners/Devising an Input


Method

23

Submit:
<button id="btnAdd" label="Create" width="80px" height="24px"/>
</row>
</rows>
</grid>
</window>
</zk>
In calendar.zul,
define a ZK macro component named "BookEventDialog" and specify its corresponding ZUL file's URI, in this
case, just "bookEvent.zul"
<?component name="CreateDialog" macroURI="bookEvent.zul"?>

in calendar.zul, declare the macro component and assign an ID


<BookEventDialog id="bookingDialog">

In
CalendarCtrl.java
(the
controller
<javadoc>org.zkoss.zk.ui.util.GenericForwardComposer</javadoc>)

class

that

extends

declare the event booking window and the Calendars component


private Window bookEventWin;
private Calendars cal;
in the current execution, create the macro component "bookEvent.zul" and assign it to the declared Window,
bookEventWin.
bookEventWin = (Window)Executions.createComponents("bookEvent.zul",
win, null);
from there, we set the event booking window visible in our event Listener (<mp>onEventCreate$cal</mp> to
bring it to view when a user selects a time slot on calendar
bookEventWin.setVisible(true);
Positioning the Input Dialog
The CalendarsEvent provides the methods getX(), getY(), getDesktopWidth() and getDesktopHeight(). You can
utilize these API to calculate where the calendar event should be placed.
For example:
public void onEventCreate$cal(CalendarsEvent event){
int left = evt.getX();
int top = evt.getY();
if (top + 245 > event.getDesktopHeight())
top = event.getDesktopHeight() - 245;
if (left + 410 > event.getDesktopWidth())
left = event.getDesktopWidth() - 410;

ZK Calendar Essentials/Working with ZK Calendar/Implementing ZK Calendar Event Listeners/Devising an Input


Method
bookEventWin.setLeft(left + "px");
bookEventWin.setTop(top + "px");
In this sample the values 245 and 410 are dependent on the height and width of your component.

24

Article Sources and Contributors

Article Sources and Contributors


ZK Calendar Essentials Source: http://books.zkoss.org/index.php?oldid=112 Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Introduction Source: http://books.zkoss.org/index.php?oldid=218 Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Getting Started with ZK Calendar Source: http://books.zkoss.org/index.php?oldid=277 Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Getting Started with ZK Calendar/ Setting Up ZK Calendar Source: http://books.zkoss.org/index.php?oldid=258 Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Getting Started with ZK Calendar/ The ZK Calendar Component Source: http://books.zkoss.org/index.php?oldid=302 Contributors: Sphota, Tmillsclare,
Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar Source: http://books.zkoss.org/index.php?oldid=279 Contributors: Tmillsclare
ZK Calendar Essentials/ Working with ZK Calendar/ Initializing View Attributes Source: http://books.zkoss.org/index.php?oldid=263 Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data Source: http://books.zkoss.org/index.php?oldid=280 Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/ Managing Event Data Source: http://books.zkoss.org/index.php?oldid=184 Contributors:
Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/ Managing Event Data/ SimpleCalendarEvent Source:
http://books.zkoss.org/index.php?oldid=187 Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/ Managing Event Data/ Date Formatting Source: http://books.zkoss.org/index.php?oldid=191
Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/ Managing Event Data/ Multiple Timezones Source:
http://books.zkoss.org/index.php?oldid=193 Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/ Storing Event Data in Memory Source: http://books.zkoss.org/index.php?oldid=202
Contributors: Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Displaying ZK Calendar Event Data/ Presenting Event Data Source: http://books.zkoss.org/index.php?oldid=291 Contributors:
Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners Source: http://books.zkoss.org/index.php?oldid=281 Contributors: Sphota, Tmillsclare
ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners/ Introducing ZK MVC Source: http://books.zkoss.org/index.php?oldid=304
Contributors: Sphota, Tmillsclare, Zkwikiadmin
ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners/ Declaring Events Source: http://books.zkoss.org/index.php?oldid=290 Contributors:
Sphota
ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners/ The CalendarsEvent Object Source: http://books.zkoss.org/index.php?oldid=221
Contributors: Sphota
ZK Calendar Essentials/ Working with ZK Calendar/ Implementing ZK Calendar Event Listeners/ Devising an Input Method Source: http://books.zkoss.org/index.php?oldid=283
Contributors: Sphota

25

Image Sources, Licenses and Contributors

Image Sources, Licenses and Contributors


File:ZKCalEss_CalendarIntroduction.png Source: http://books.zkoss.org/index.php?title=File:ZKCalEss_CalendarIntroduction.png License: unknown Contributors: Zkwikiadmin
File:ZKCalEss_Simple_calendar_application.png Source: http://books.zkoss.org/index.php?title=File:ZKCalEss_Simple_calendar_application.png License: unknown Contributors:
Tmillsclare
Image: bareCalendar.png Source: http://books.zkoss.org/index.php?title=File:BareCalendar.png License: unknown Contributors: Sphota
File:ZKCalEss_Default_mold.jpg Source: http://books.zkoss.org/index.php?title=File:ZKCalEss_Default_mold.jpg License: unknown Contributors: Zkwikiadmin
File:ZKCalEss_Month_mold.jpg Source: http://books.zkoss.org/index.php?title=File:ZKCalEss_Month_mold.jpg License: unknown Contributors: Tmillsclare
File:ZKCalEss_MemoryModelResult.png Source: http://books.zkoss.org/index.php?title=File:ZKCalEss_MemoryModelResult.png License: unknown Contributors: Zkwikiadmin
Image: lottoMVC.png Source: http://books.zkoss.org/index.php?title=File:LottoMVC.png License: unknown Contributors: Sphota

26