Integrating Google Calendar with ZK Timeline Component

{{Template:Smalltalk_Author|
|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
}}




=Introduction=

[http://www.google.com/calendar/ 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:

[[Image:Gcal.png]]


=ZK Google Calendar API: gcalz=

[http://code.google.com/apis/calendar/overview.html 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:

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

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 [http://simile.mit.edu/timeline/ MIT Timeline AJAX widget]. Importing data from Google Calendar into ZK Timeline component with '''gcalz''' is shown below.

[[Image: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:'''

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


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

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


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=

* [http://zkoss.org/smalltalks/gcalz/gcalz.war gcalz.war](without jar files inside)
* <tracker url="http://sourceforge.net/project/showfiles.php?group_id=152762&package_id=238807" > gcalz-0.7.zip</tracker>(from SourceForge.net - zk1)
* <tracker url="http://prdownloads.sourceforge.net/zk1/zk-2.4.1.zip?download" > ZK-2.4.1.zip</tracker>(ZK standard Library)

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


<comment>http://docs.zkoss.org/wiki/Integrating_Google_Calendar_with_ZK_Timeline_Component</comment>


[[Category:3rd Party Components]]
{{Template:Smalltalk_Footer|
|name=Potix Corporation 
}}