From Documentation

Jump to: navigation, search




  • Author
    Ian Tsai, Engineer, Potix Corporation
  • Date
    July 16, 2007
  • Version
    1. Apache-Tomcat-5.5.X
2. ZK 2.4.1
3. gcalz-0.7.jar



Contents

Introduction

Google Calendar is a very popular time management service in Internet, and we can integrate this service into our ZK web application using Timeline component. This article uses a simple calender-browsing application to show how easy it is to build such an application. Google Calendar

The Google Calendar is shown below:

Gcal.png


ZK Google Calendar API: gcalz

Google Calendar API is an ATOM Service and you can use a RSS reader to read it. In this version of gcalz, we implemented Browse(for overview of schedule) and Read(for detail of schedule) methods for retrieving data from Google Calendar. The API of org.zkoss.gcalz.GCalUtil is shown below:

public class GCalUtil
    /**
     * GET meta user calendars use defult URL "http://www.google.com/calendar/feeds/default".
     * @param urlStr
     * @param service
     * @return
     * @throws IOException
     * @throws ServiceException
     */
    public static List<CalendarEntry> getMetaUserCalendars(CalendarService service) 
    throws IOException, ServiceException
    
    /**
     * Use username + password to connect to Google Calendar Service and getback  user's calendars.
     * @param user the email address of your Google account
     * @param Password
     * @return
     * @throws IOException
     * @throws ServiceException
     */
    public static List<CalendarEntry> getMetaUserCalendars(String username, String password) 
    throws IOException, ServiceException
    
    /**
     * A fast method to GET event list from user's main calendar.
     * Query URL form: "http://www.google.com/calendar/feeds/" + username + "/private/full"
     * @param username the email address of your Google account
     * @param password 
     * @return
     * @throws IOException
     * @throws ServiceException
     */
    public static List<CalendarEventEntry> getQuickMainCalendarEvents(String username, String password) 
    throws IOException, ServiceException

    /**
     * Use a calendar uri to query it's detail events.
     * @param targetCalendarUri
     * @param service
     * @return
     * @throws IOException
     * @throws ServiceException
     */
    public static List<CalendarEventEntry> getAllEvents(String targetCalendarUri, CalendarService service) 
    throws IOException, ServiceException

    /**
     * Generic type query in Google Base Data API
     * @param feedUri
     * @param service
     * @param clazz
     * @return
     * @throws IOException
     * @throws ServiceException
     */
    public static List
    getEntries(String feedUri, CalendarService service, Class clazz)
    throws IOException, ServiceException
    
    /**
     * Use username & password to create an Authened Service to connect to Google server.
     * @param user
     * @param pwd
     * @return
     * @throws AuthenticationException 
     */
    public static CalendarService createGCalService(String user,String pwd) 
    throws AuthenticationException

The most straight-forward way to access your schedules from Google Calendar is invoking getQuickMainCalendarEvents method, In this demo we use it to get calnedar data and convert it to Timeline's Data Model entries.


Integrating Timeline Component with Google Calendar

Timeline component is based on MIT Timeline AJAX widget. Importing data from Google Calendar into ZK Timeline component with gcalz is shown below.

Timelinez.png


The meanings of dot's color are shown below:

1.Red: working event, the event is currently happening.

2.Blue: Past event, the event is already closed.

3.Green: future event, the event is in the future.


How to Implement

The steps about how to integrate Google Calendar and ZK Timeline component are listed below:

1.Authenticate and access user's Google Calendar data using org.zkoss.gcalz.GCalUtil functions.

2.Convert Google's CalendarEventEntry to Timeline's OccurEvent.

3.Configure Timeline's OccurEvent's UI properties.


In order to accomplish such jobs, we implemented a controller class named org.zkoss.gcalz.GCalTimelineControl. The code clips below shows how it works:


gc_timeline.zul:

<zscript><![CDATA[
    
    import org.zkoss.gcalz.*;
    GCalTimelineControl control = new GCalTimelineControl();

    control.setPastIconUrl("img/dull-blue-circle.png");
    control.setFutureIconUrl("img/dull-green-circle.png");
    control.setWorkingIconUrl("img/red-circle.png");	
    
]]></zscript>
.
.
.
control.loadGCalendar(user.getValue(),pwd.getValue());//Core Main Function...
.
.
.
<timeline id="timeline" height="700px" width="860px">
	    
    <bandinfo id="bandinfo1" width="30%"  intervalUnit="hour"
        intervalPixels="38" model="${control.timelineModel}" eventSourceUrl="xmloutput.zul" >
    </bandinfo>
	    
    <bandinfo id="bandinfo2" width="35%" intervalUnit="day" intervalPixels="200"
        syncWith="bandinfo1" model="${control.timelineModel}" eventSourceUrl="xmloutput.zul" >
    </bandinfo>
    
    <bandinfo id="bandinfo3" width="35%" intervalUnit="month" intervalPixels="400"
        syncWith="bandinfo2" model="${control.timelineModel}" eventSourceUrl="xmloutput.zul" >
    </bandinfo>
    
</timeline>


Import Timeline Data

In addition, Timeline component provides two way to import data as follows:

1.Statically: In original MIT Timeline component, it uses XMLHttpRequest to query its unique form of data xml. Compare to ZK's Timeline component the same way to import data is to set <bandinfo>'s attribute eventSourceUrl to a URL with same xml format as it's original. You can see the data xml sample timeline_ex1.xml in demo package. In this demo, xmloutput.zul provides a way to get back user's Google Calendar data. Add parameters "user" and "pwd" like this:

  <bandinfo id="bandinfo1" width="30%"  intervalUnit="hour"
	  intervalPixels="38" model="${control.timelineModel}" >
	  <attribute name="eventSourceUrl">
		  xmloutput.zul?user=user@gmail.com&pwd=******
	  </attribute>
  </bandinfo>


2.Dynamically: As you can see in gc_timeline.zul which is in damo package or code clips before. Timeline ZK component <bandinfo> provide DataModel mechanism to synchronize java.util.List<OccurEvent> to it's ListModel. Use EL-expression or annotated data binding to set your data model.


Summary & Future Works

There's only Browse and Read functions provided in the current version of gcalz. According to Google Calendar API and Timeline ZK Component's Specification. It is possible to add Delete & Add functions. we'll implement it soon.


Download

Advanced

If you want more complicated data access mechanism. Use org.zkoss.gcalz.GCalManager as a DAO class. It supports multiple calendar schedule browsing and detail reading.




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