Calendar Sidebar Gadgets Developer's Guide

Greetings! Google Calendar is now a gadget container, including new APIs to help your gadgets interact with the Calendar user interface. This document will teach you how to write useful gadgets which run well and take full advantage of these APIs.

Prerequisites

This document assumes:

• You know a little JavaScript.
• You can post files to public Internet. If you do not have web hosting, then you can post gadgets with the Google Gadget Editor (GGE for short).
• You know a little about gadgets. If not, please see this excellent Getting Started guide for the gadgets.* API.

Definitions

Calendar

In this document, capitalized Calendar refers to Google Calendar, and lower cased calendar refers to a particular set of events.

Container

The parent web page, which has an iframe on it that contains your gadget. In this document, Google Calendar is the container. Other examples would be iGoogle or Gmail.

Content Type

Gadgets come in 2 flavors, type='html' and type='url'. The default is type="html", and it is strongly encouraged. Here is additional documentation.

Event

A calendar event with a start time, end time, and additional optional information (i.e. title, description, attendees, etc...)

Feature

A set of JavaScript functions which the container makes available to the gadgets. An example is setting the gadget's height with feature="dynamic-height". Google Calendar as a container supports many of them documented below.

Gadget

A web page, which runs in an iframe on the parent containers. (Note - this is a simplified definition.)

Gadget Specification / Gadget Spec

An XML file which contains the gadget metadata and display data. Here is the reference.

Public Internet

A web page which anyone on the Internet can access. An intranet or your local hard drive is not on the public Internet.

Relay

A file used to communicate between the gadget and the container. There is a canonical file to do this at "http://www.google.com/calendar/rpc_relay.html". If you use type='url' gadgets, you will need to copy this file to your web server.

Timed Event

An event with hours, minutes, and seconds.

Untimed Event

An event that does not have hours, minutes, and seconds.

Viewer

The user who is logged into Google Calendar, and thus is viewing your gadget.

Developing your gadget

Note: If you haven't already done so, first read the excellent Getting Started guide for the gadgets.* API.

1. Make a gadget spec. (Use the Hello World sample to get started.)
2. Publish the gadget spec to a location which is accessible on the public Internet. An intranet will not work. Your hard drive will not work. (Why? The Google servers will download the gadget. If they can't reach it, then Google Calendar can't display it.)
3. Ask Google Calendar to load the gadget by going to the following URL:

   http://www.google.com/calendar/render?gadgeturl=MY_GADGET_URL
   

   For example, the "Hello World" sample can be loaded using the URL (demo):

   http://www.google.com/calendar/render?gadgeturl=http://www.google.com/ig/modules/hello.xml
   

4. After clicking on the link, users will be prompted to authorize adding your gadget to their Calendar, at which point they should click they should click "Yes, add this gadget".
5. Your gadget will appear on the right hand side of the screen.

6. Tip: Google Calendar will cache your gadget spec for 1 hour. If you make changes to your gadget spec during this window, you can re-add it to Google Calendar by appending a random query parameter (e.g. timestamp) to its URL to override the cached version. Alternatively, you can use the OpenSocial Limited Invalidation API to programatically invalidate the gadget cache.

Publicizing your gadget

Publicizing the gadget uses almost the same method as developing it.

You can prompt a user to add your gadget by sending them to the following page:

http://www.google.com/calendar/render?gadgeturl=MY_GADGET_URL

For instance (demo):

http://www.google.com/calendar/render?gadgeturl=http://www.google.com/ig/modules/calendar/setdate.xml

Gadget Features that Google Calendar supports

Google Calendar supports many gadget features. Here are some of them:

Future Feature Versions

The Google Calendar Features are under active development. As such, we have launched google.calendar-0.5 and google.calendar-0.5.read. We plan to refine these features in the future. For instance, we may launch google.calendar-0.6. When we release a new version, we will announce it on this page. In addition, the old and new versions will be supported simultaneously for several months thereafter.

New versions will likely add or remove fields from the returned objects. Since most fields are explicitly optional, this should cause minimal disruption to most applications.

Warning: Since future versions of the Google Calendar Features may remove fields, we strongly recommend that you future-proof your application by checking that a field exists before using it.

Sample Calendar Sidebar Gadgets

1. [Source] [Add To Calendar] addCalendar demo
2. [Source] [Add To Calendar] composeEvent demo
3. [Source] [Add To Calendar] getPreferences demo
4. [Source] [Add To Calendar] showDate + showEvent demo
5. [Source] [Add To Calendar] subscribeToDates demo
6. [Source] [Add To Calendar] subscribeToDataChange demo
7. [Source] [Add To Calendar] subscribeToEvents demo
8. [Source] [Add To Calendar] getEvents demo
9. [Source] [Add To Calendar] getEvents opt_params demo
10. [Source] [Add To Calendar] My Friends
11. [Source] [Add To Calendar] Next Event
12. [Source] [Add To Calendar] Set Date
13. [Source] [Add To Calendar] World Time
14. [Source] [Add To Calendar] Year View

Static Structures

calendar.contact

Note that this is just a JSON object. We refer to it as calendar.contact for clarity. All of the fields are assumed to be optional unless otherwise stated.

calendar.time

Note that this is just a JSON object. We refer to it as calendar.time for clarity. Note that the hour, minute, and second field are optional in all day events.

calendar.palette

Note that this is just a JSON object. We refer to it as calendar.palette for clarity. All of the fields are assumed to be optional unless otherwise stated.

calendar.event

Note that this is just a JSON object. We refer to it as calendar.event for clarity. All of the fields are assumed to be optional unless otherwise stated.

The "composeEvent()?" column states whether it is appropriate to pass to the composeEvent() function. You can pass other fields, but they will be silently ignored.

The "returned by default?" column indicates whether the field will be returned without explicitly requesting it using the requestedFields optional parameter (see the opt_params parameter for getEvents()).

calendar.getEventsResults

Note that this is just a JSON object. We refer to it as calendar.getEventsResults for clarity. This describes the objects returned by the getEvents() API.

calendar.getEventsOptParams

Note that this is just a JSON object. We refer to it as calendar.getEventsOptParams for clarity. This describes additional optional parameters accepted by the getEvents() API.

Static Class google.calendar

 SUMMARY     DETAIL

Provides operations for communicating with Google Calendar.

This feature is at version 0.5. As such, you can access these functions with feature="google.calendar-0.5". We plan to refine this feature in the future. When we release a new version, we will continue to support 0.5 for several months thereafter.

Method Summary

<static> addCalendar(idOrEmail, opt_name)

Ask the user to add a calendar to their list of visible calendars.

<static> composeEvent(eventData)

Open a "create event" page, and populate the fields.

<static> getPreferences(callback)

Get the user's calendar preferences.

<static> refreshEvents()

Ask the Google Calendar container to check with the server for new events.

<static> setRelay(relay)

Sets the relay URL, which allows type="url" gadgets to work.

<static> showDate(year, month, date)

Ask the Google Calendar container to display a specific date.

<static> showEvent(id)

Ask the container to show an event.

<static> subscribeToDates(callback)

Ask the container to call the specified function when new dates are visible on screen.

<static> subscribeToDataChange(callback)

Ask the container to call the specified function when new event data may be available.

Method Detail

addCalendar

<static> addCalendar(idOrEmail, opt_name)

composeEvent

<static> composeEvent(eventData)

getPreferences

<static> getPreferences(callback)

   function preferencesCallback(prefs) {
     var out = '';
     if ('startdow' in prefs) {
       out += "Day of week = " + prefs.startdow + "\n";
     }
     if ('military' in prefs) {
       out += "Military time = " + prefs.military + "\n";
     }
     alert(out);
   }

   // Ask the calendar for the preferences
   google.calendar.getPreferences(preferencesCallback);

refreshEvents

<static> refreshEvents()

setRelay

<static> setRelay(relay)

showDate

<static> showDate(year, month, date)

showEvent

<static> showEvent(id)

subscribeToDates

<static> subscribeToDates(callback)

   function datesCallback(dates) {
     var start = dates.startTime;
     var end = dates.endTime;

     var out = start.month + '/' + start.date + ' - ' +
         end.month + '/' + end.date;
     alert(out);
   }

   google.calendar.subscribeToDates(datesCallback);

subscribeToDataChange

<static> subscribeToDataChange(callback)

   function dateChangeCallback() {
     alert('New data is likely available');
   }
   google.calendar.subscribeToDataChange(dateChangeCallback);

Static Class google.calendar.utils

 SUMMARY     DETAIL

Utilities to help process dates.

Method Summary

Date toDate(datetime, opt_offset)

Convert a calendar API style date (calendar.time) to a JS style date.

calendar.time fromDate(d, opt_offset)

Convert a JS style date to a calendar API (calendar.time) style date.

Date getNow(opt_offset)

Get the current time adjusted by offset.

Method Detail

toDate

Date toDate(datetime, opt_offset)

fromDate

calendar.time fromDate(d, opt_offset)

getNow

Date getNow(opt_offset)

Static Class google.calendar.read

 SUMMARY     DETAIL

Functions to read data from the Google Calendar container.

This feature is at version 0.5. As such, you can access these functions with feature="google.calendar-0.5.read". We plan to refine this feature in the future. When we release a new version, we will continue to support 0.5 for several months thereafter.

Method Summary

<static> getEvents(callback, emailIds, opt_start, opt_end, opt_params)

Request the events for a set of users in a specific time period.

<static> subscribeToEvents(callback)

Ask the calendar to call the specified function when a new event is displayed.

Method Detail

getEvents

<static> getEvents(callback, emailIds, opt_start, opt_end, opt_params)

   function eventCallback(response) {
     var daveResponse = response[0];
     if ('error' in response[0]) {
       alert('Something went wrong');
       return;
     }

     var events = response[0]['events'];
     var out = '';
     for(var i = 0; i < events.length; ++i) {
       var e = events[i];
       if ('title' in e) {
         out += 'Title = ' + e.title + '\n';
       }
     }
     alert(out);
   }
   var startDate = {year: 2009, month: 12, date : 24, hour : 0, minute:0, second: 0};
   var endDate = {year: 2010, month: 1, date : 1, hour : 0, minute: 0, second: 0};
   google.calendar.read.getEvents(eventCallback, ["david@gmail.com"], startDate, endDate);

        var results = [
          {
            email : 'david@gmail.com',
            name : 'dave',
            events : [
              {
                title : 'Christmas',
                startTime : {year: 2009, month: 12, date : 25},
                endTime : {year: 2009, month: 12, date : 26},
                allDay : true,
                id: 'XXX'
              },
              {... another event ... },
              {... yet another event ... }
            ]
          },
          {
            email : 'bob@gmail.com',
            error : google.calendar.Error.NO_PERMISSIONS
          }
        ];

subscribeToEvents

<static> subscribeToEvents(callback)

   function subscribeEventCallback(calendarEvent) {
     var out;
     if (!calendarEvent) {
       // No event is onscreen.
       out = 'No Event Onscreen!';
     } else {
       var out = '';
       if ('title' in calendarEvent) {
         out += 'Title = ' + calendarEvent['title'] + '\n';
       }
       if ('location' in calendarEvent) {
         out += 'Location = ' + calendarEvent['location'] + '\n';
       }
     }
     alert(out);
   }
   google.calendar.read.subscribeToEvents(subscribeEventCallback);