CalVis: Creating a customized AJAX UI for your Google Calendar

Austin Chau, Google Developer Programs
June 2008

Note - This is an open source project started by a Googler and not an offically supported library. We invite all who are interested to join and contribute :)

Introduction

Have you ever wanted to create a customized calendar experience on your website using Google Calendar data but not quite sure how to present the calendar data visually? There seems to be a good number of developers who share this dilemma. While the Google Calendar Data API is a powerful web service API as it allows you tap into the richness of all your Google Calendar data, it remains a pure read/write data API with no provision for data visualization.

In this article, I am going to demonstrate a sample library that I have written to alleviate this problem. I started the open source project, Calendar Visualization (CalVis), which aims to provide an easy and customizable user interface (UI) to present data from Google Calendar account. CalVis draws data directly from your Google Calendar account via the Google Calendar Data API. (Editor's Note: As of v3, Google Calendar no longer uses the Google Data format.) It makes use of the Google Data JavaScript client library underneath to communicate with Google Calendar, and is designed to maximize flexibility in customization.

CalVis is designed to spare developers from having to re-create the rich calendar UI experience. The developers can use it as customizable template container to overlay Google Calendar data. Developers can use CalVis to render calendar data and to achieve a deep level of customized integration with their sites. As you will learn, an interface that is built on top of CalVis is completely customizable through JavaScript, HTML and CSS. Developers would be able to quickly and easily deploy a customized calendar interface with a set of essential calendar control components to render calendar data.

Using CalVis

The following steps help you to get started on using CalVis for your development.

Step 1 - Load the Calendar Visualization library

First you need to include the loader in your HTML file. This loader dynamically loads the core classes of CalVis as well as its dependent libraries (such as Google Data JavaScript client library).

<script src="//gcal.appspot.com/calvis/calvis.js" type="text/javascript"></script>

Step 2 - Use CSS stylesheet to describe style attributes.

The default CSS file will produce a default look-and-feel just like this example. You can download this CSS file and customize it to have a completely different look-and-feel.

<link rel="stylesheet" type="text/css" href="//gcal.appspot.com/calvis/default.css" />

Step 3 - Lay out the visual structure of the calendar interface with HTML

CalVis has several predefined visual components that makes up the calendar interface. The structural arrangement of these interface components are defined by your HTML layout.

The UI components of CalVis are:

  • Login Control (only for private calendars)
    This is the HTML component that provides the login/logout link.
  • Status Control
    This is the HTML component that provides status information or errors.
  • Navigation Control
    This is the HTML component that renders the calendar navigation in respect to the current view.
  • View Control
    This is the HTML component that renders the calendar view selection, only month or week views are available in this release.
  • Calendar Body
    This is the HTML component that renders the actual calendar. With grids to designate individual date cells.
  • Event Display
    This is the HTML component that renders the event details upon an event trigger. Only "click" and "mouseover" event trigger is supported in this release.

An example of how to visually arrange these components using basic HTML table structure -

  <table style="width: 800px;">
    <tr>
      <td colspan="2" valign="top">
        <div style="float: left;" id="loginControlDiv"></div>
        <div style="float: right;" id="statusControlDiv"></div>
      </td>
    </tr>      
    <tr>
      <td valign="top">
        <div id="navControlDiv"></div>
      </td>
      <td valign="top" align="right">
        <div id="viewControlDiv"></div>
      </td>
    </tr>
    <tr>
      <td colspan="2" valign="top">
        <div id="calendarBodyDiv"></div>
      </td>
    </tr>
    <tr>
      <td colspan="2" valign="top">
        <div id="eventDisplayDiv"></div>
      </td>
    </tr>
  </table>
    

Step 4 - Initialize and configure CalVis with JavaScript

You can customize any of the behavior or appearance by using JavaScript. Keep in mind that before you can modify an object in JavaScript, it must first be loaded by the browser, so you first need to wait until all dependent libraries are loaded with the CalVis loader, this is done with the calvis.ready() method. This method takes a callback method that will be invoked when all libraries are loaded and CalVis is ready to be used.

window.onload = function() {
  calvis.ready(callback);
}

Inside the callback function, you will instantiate an instance of the calvis.Calendar object. Now you have to assign the various CSS IDs (these are defined from the HTML layout in Step 3) to map to the corresponding calendar UI components.

var calId = 'developer-calendar@google.com';

var calendar = new calvis.Calendar();

// set the CSS IDs for various visual components for the calendar container
calendar.setCalendarBody('calendarBodyDiv');
calendar.setStatusControl('statusControlDiv');
calendar.setNavControl('navControlDiv');
calendar.setViewControl('viewControlDiv');

Now you can specify which Google Calendar account CalVis should be pulling data from. To specify a public calendar -

// set the calenar to pull data from this Google Calendar account
calendar.setPublicCalendar(calId);  

To specify a private calendar, you also need to specify the HTML component that corresponds to the login button -

// set the calenar to pull data from this Google Calendar account
calendar.setPrivateCalendar(calId);
calendar.setLoginControl('loginControlDiv');

In order to display event details, you need to provide a callback method so that when an event listing on the calendar is triggered (either by 'click' or 'mouseover' event), the callback will be invoked to display the event details. An example of a event display callback-

calendar.setEventCallback('click', displayEvent);

function displayEvent(event) {    
  var title = event.getTitle().getText();  
  var date = event.getTimes()[0].getStartTime().getDate();
  var content = event.getContent().getText();  
  
  var eventHtml = [;
  eventHtml.push(date.toString());
  eventHtml.push('<br><br>');
  eventHtml.push('<b>Event title:</b> ');
  eventHtml.push(title);
  eventHtml.push('<br>');
  eventHtml.push('<br>');
  eventHtml.push('<b>Description:</b>');
  eventHtml.push('<p style="font-size: 11px;">');
  eventHtml.push(content); 
  eventHtml.push('</p>');
  eventHtml.push('<br>');

  document.getElementById('eventDisplayDiv').innerHTML = eventHtml.join('');
}      
Finally, you can set the default view of the calendar (either a 'month' or 'week' view) and invoke the render() method to display the calendar UI -
// set the default view to be "month"
calendar.setDefaultView('month');

// display the calendar
calendar.render();  

Customize styling

To customize the size, color or style of an individual date cell, you just need to modify the CSS styling attributes of a few predefined CSS classes. For instance, you can modify the width and height of each date cell in your month view by overriding the default CSS class monthViewCell and contentCell.

Demo

This demo demonstrates using CalVis with the default styling.

This demo demonstrates using CalVis with customization to create a mash-up with Google Maps and YouTube API.

Contribute

CalVis an open source project, whose source code is available for download via Subversion on Google Code Project Hosting.

Resources