Google Apps Platform

Google Calendar Sidebar Gadgets Reference 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.

Contents

Prerequisites

This document assumes:

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

Feature Library Description Syntax
setprefs Sets the value of a user preference programmatically. See Gadgets API Reference: Saving State for more information. Note: Calendar currently does not provide any UI for a user to modify the preferences. <Require feature="setprefs"/>
dynamic-height Gives a gadget the ability to resize itself. See Gadgets API Reference: Managing Gadget Height for more information. <Require feature="dynamic-height"/>
settitle Sets a gadget's title programmatically. See Gadgets API Reference: Setting a Gadget's Title for more information. <Require feature="settitle"/>
locked-domain The locked-domain library isolates your gadgets from other gadgets running on the same page. You can only use this feature with type="html" gadgets. We suggest that you add this feature requirement to your gadget if your gadget stores sensitive private user data. <Require feature="locked-domain"/>
views Allows specifying the location in a container where a gadget is displayed. See iGoogle Developer's Guide: Views for more information. Note: Calendar currently only supports the CANVAS and DEFAULT views. <Content type="html" view="home">
opensocial-0.8 Allows access to social networking functions from within gadgets. <Require feature="opensocial-0.8"/>
google.calendar-0.5 Provides access to the Google Calendar UI. (Documented below.) <Require feature="google.calendar-0.5"/>
google.calendar-0.5.read Provides read-only access to the Google Calendar UI. (Documented below.) <Require feature="google.calendar-0.5.read"/>
OAuth Authorization Allows making authenticated requests to third-party services via makeRequest(). For more information, see Writing OAuth Gadgets. <OAuth/>

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.

type name description
string email The contact's email address
string name The contact's human readible name
string status If the contact is an event attendee, this is response status. ("accepted" | "declined" | "tentative" | "organizer")

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.

type name description
number year The year (i.e. - 2009)
number month The month (1-12)
number date The day of the month (1-31)
number hour The hour (0-23)
number minute The minute (0-59)
number second The second (0-59). Note: Google Calendar does not display or set seconds in its UI. This field is Almost always 0. We put it in the API for consistency.

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.

type name description
string darkest The darkest color to use for this event's color scheme
string dark The dark color to use for this event's color scheme
string medium The medium color to use for this event's color scheme
string light The light color to use for this event's color scheme
string lightest The lightest color to use for this event's color scheme

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()).

type name composeEvent()? returned by default? description
string title Y Y The title of the event
string details Y N The body of the event
string location Y Y The location of the event
boolean allDay Y Y Is the event an "all day event" (AKA - untimed event). Default = false.
calendar.time startTime Y Y The start time of the event {year, month, day} OR {year, month, day, hour, min, second}. An example is {year: 2009, month: 12, date: 25} for Christmas, or {year: 2009, month: 10, date: 3, hour: 14, minute:30, second:0} for 2:30pm on Oct 3 (my birthday!).
calendar.time endTime Y Y The end time of the event. It has the same format as startTime above. Note that end times are EXCLUSIVE in all day events. For instance, a 1 day events starting on {year: 2009, month: 12, date: 25} would end on {year: 2009, month: 12, date: 26}. If the event lasted 3 days, then it would end on {year: 2009, month: 12, date: 28}.
string status N N The response status for the user who's calendar this event is on. ("accepted" | "declined" | "tentative" | "organizer").
Array<calendar.contact> attendees Y N Attendees for an event. In the form [{email : 'dave@gmail.com' }, {email : 'trevor@gmail.com' }]. Note that this is consistent with the format in other event APIs below.
string rrule Y Y A recurrence rule in the RFC 2445 format. For instance "RRULE:FREQ=WEEKLY;COUNT=10" repeats weekly for the next 10 weeks.
number attendeeCount N N The number of attendees in this event.
calendar.contact owner N N The contact information for the owner of the event.
calendar.contact calendar N Y The contact information for the calendar that the event lives on.
calendar.contact creator N Y The contact information for the person who created the event.
string id N Y The id for the event. Appropriate to pass to showEvent()
calendar.palette palette N Y The set of colors for this event

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.

type name required? description
string accessLevel N The user's access level to the calendar. If present, it is one of the following "root", "owner", "editor", "read", "freebusy", "none". Please see gAcl:role in the Calendar Data API documentation for more information on these enums.
string email Y The email address of the user
string name N The common name of the user
string tz N The timezone currently selected for this calendar. (Note that events will be returned based on the current user's timezone, regardless of what is listed here.)
string error N The error code. If this field is undefined, that indicates success. Expected error codes are google.calendar.Error.NO_PERMISSIONS and google.calendar.Error.INTERNAL_ERROR.
Array<calendar.event> events N An array of calendar.event objects belonging to the user. If the error field is not defined, then events will be present.

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.

type name required? description
Array<string> requestedFields N A list of additional fields that should be returned inside of the calendar.event object after calling getEvents(). Available fields are ['owner', 'status', 'attendeeCount', 'details', 'attendees']. If not specified, none of these fields will be returned.

Static class google.calendar

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)
Ask the user to add a calendar to their list of visible calendars.

Sample:
google.calendar.addCalendar("en.usa#holiday@group.v.calendar.google.com", "US Holidays");
Parameters:
string idOrEmail - The id or email address of the calendar to add.
string opt_name - Optional title of the calendar to display when prompting the user for permission to add it.

composeEvent

<static> composeEvent(eventData)
The google.calendar API does not allow you to create events directly. However, it does allow you to open a "create event" form that has most fields already filled in. You can pass other fields, but they will be silently ignored.
Parameters:
calendar.event eventData - A JSON object containing key value pairs for the fields. The following 8 fields are accepted. All of them are optional (i.e. - if you pass none of them, then the compose window will pop up with nothing filled in).
  1. string title - The title of the event
  2. string details - The body of the event
  3. string location - The location of the event
  4. boolean allDay - Is the event an "all day event" (AKA - untimed event). Default = false.
  5. calendar.time startTime - The start time of the event {year, month, day} or {year, month, day, hour, min, second}. An example is {year: 2009, month: 12, date: 25} for Christmas, or {year: 2009, month: 10, date: 3, hour: 14, minute:30, second:0} for 2:30pm on Oct 3 (my birthday!)
  6. calendar.time endTime - The end time of the event. It has the same format as startTime above.
  7. Array<calendar.contact> attendees - Attendees for an event. In the form [{email : 'dave@gmail.com' }, {email : 'trevor@gmail.com' }]. Note that this is consistent with the format in other event APIs below.
  8. string rrule - A recurrence rule in the RFC 2445 format. For instance "RRULE:FREQ=WEEKLY;COUNT=10" repeats weekly for the next 10 weeks.

getPreferences

<static> getPreferences(callback)
Get the user's calendar preferences.

Sample:
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);
Parameters:
Function(Object) callback - A function which takes a JSON object. The calendar container will call this function with the results. The following fields MAY be returned. All of them are optional, and may be returned at the container's discretion.
  1. number timezone_offset - The number of milliseconds between GMT and local time.
  2. number current_time_offset - The number of milliseconds between the local system time and the time displayed in Google Calendar.
  3. string dateFormat - One of the following strings ('DMY', 'MDY', or 'YMD')
  4. boolean military - true = 24hour time. false = am/pm.
  5. number startdow - The day of the week that the container displays as the first date. 0 = sunday, 1 = monday, 6 = saturday.
  6. string viewer - The email address of the current logged in user (i.e. - "david@gmail.com").

refreshEvents

<static> refreshEvents()
Ask the calendar to check with the server for new events.

The main reason to call this function is that you made a Google Data PUT request from the gadget. The calendar will not show your changes immediately. You can call refreshEvents() to ask the calendar container to get event information from the server.

Sample:
// Make GDATA modification...
google.calendar.refreshEvents();

setRelay

<static> setRelay(relay)
If you are using type="html" gadgets, please ignore this function. It only applies to type="url" gadgets. This function allows the gadget to set the relay URL, which allows the container to talk to your gadget.
Parameters:
String relay - The URL of the rpc_relay.html file. You must download this file, and post it on your webserver. A good example is "http://www.google.com/calendar/rpc_relay.html". A copy of this file must be uploaded on the same host as your type="url" gadget. If you use type="url", and do not set this correctly, then the container can not talk to your gadget, and many if the following APIs will not work. As well, if your gadget uses HTTPS, then we recommend using a "https://" prefixed URL here to avoid browser security warnings.

showDate

<static> showDate(year, month, date)
Ask the calendar to display to a specific date on the screen. For instance, google.calendar.showDate(2008, 12, 25) would make the calendar show Christmas day in the past.

Sample:
// Ask the calendar to show christmas 2008
google.calendar.showDate(2008, 12, 25);
Parameters:
number year - The year to show (i.e. - 2008)
number month - The month to show (i.e. - 12 for december)
number date - The date to show (i.e. - 25)

showEvent

<static> showEvent(id)
Ask the calendar to show a specific existing event. The id (= event id) comes from getEvents() or subscribeToEvents() calls.

Sample:
// Event ID for Father's Day on the US holiday calendar.
var fathersDayId = 'aEAwNmFiZTU4OTE1NTUyZjc2NWFkYmY5NzM1NWIzOTI4M2E1MDk5ZWRlIGVuLnVzYSNob2xpZGF5QHY';
google.calendar.showEvent(fathersDayId);
Parameters:
string id - The id of the event to show.

subscribeToDates

<static> subscribeToDates(callback)
Ask the container to call the specified function when a new date range is displayed.

Sample:
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);
Parameters:
Function(Object) callback - A function which takes a JSON object. The calendar container will call back this function 1) immediately after you call subscribeToDates with the currently displayed range. 2) every time the user changes the visible date range
  1. calendar.time startTime - The earliest date displayed.
  2. calendar.time endTime - The latest date displayed.

subscribeToDataChange

<static> subscribeToDataChange(callback)
Ask the container to call the specified function when a new event data may be available. This will fire when:
  1. A calendar that the user is viewing has changed.
  2. The user has checked / unchecked a calendar.
  3. The user has added / removed a calendar.

Sample:
function dateChangeCallback() {
  alert('New data is likely available');
}
google.calendar.subscribeToDataChange(dateChangeCallback);
Parameters:
Function() callback - A function that the calendar container will call when new data is likely available.

Static class google.calendar.utils

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)
Convert a calendar API style date object (calendar.time) to a JS style date.

Sample:
var calendarDate = {year: 2008, month: 12, date:25};
var jsDate = google.calendar.utils.toDate(calendarDate);
Parameters:
calendar.time datetime - A calendar API style date / time.
number opt_offset - Optional offset in milliseconds. This is useful for timezone conversions.
Returns:
Date - A Javascript Date object.

fromDate

calendar.time fromDate(d, opt_offset)
Convert a JS style date to a calendar API (calendar.time) style date.

Sample:
var jsDate = new Date(2009, 11, 25, 0, 0, 0, 0);
var calendarDate = google.calendar.utils.fromDate(jsDate);
Parameters:
Date d - A Javscript Date object.
number opt_offset - Optional offset in milliseconds. This is useful for timezone conversions.
Returns:
calendar.time - A Calendar API style date.

getNow

Date getNow(opt_offset)
Retrieve the current time.

Sample:
var jsDate = google.calendar.utils.getNow();
Parameters:
number opt_offset - Optional offset in milliseconds. This is useful for timezone conversions.
Returns:
Date - A Javascript Date object.

Static class google.calendar.read

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)
Get events for:
  • A set of users
  • An optional time range

Sample: What is Dave doing on the last week of 2009?
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);
Parameters:
Function(Array<calendar.getEventsResults>) callback - A function which receives an array of calendar.getEventsResults. There will be one entry in the array per person that you requested in emailIds. Here is an example of the results that you will receive:
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
  }
];
String|Array<string> emailIds - The calendars whose events you want. You may also pass the string "@viewer" to see the current user's events. You may also pass the string "selected" to see the set of calendars that are visible and checked.
calendar.time opt_start - The start time. You are asking the container for all events which overlap the time range opt_start to opt_end (inclusive on the beginning, not exclusive on the end. If either opt_start or opt_end is missing, then the server will use (now) until (1 hour from now).
calendar.time opt_end - The end time. If either opt_start or opt_end is missing, then the server will use (now) until (1 hour from now).
calendar.getEventsOptParams opt_params - A JSON object containing additional parameters to be passed to this function. See the calendar.getEventsOptParams reference for a complete listing.

subscribeToEvents

<static> subscribeToEvents(callback)
Ask the container to call the specified function when a new event is displayed onscreen. Currently there are 3 situations which cause the callback to fire:
  1. The user opened an event page.
  2. The user clicked an event to make the 'bubble' appear.
  3. The user dragged or clicked on the grid to begin creating an event.

Sample:
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);
Parameters:
Function(calendar.event) callback - A function which takes a JSON object. This object describes the event onscreen. It has a subset of the following fields. All of them are optional. These fields are a superset of the ones in the composeEvent() function above. Note that the container will pass null if no event is onscreen.
  1. string title - The title of the event
  2. string details - The body of the event
  3. string location - The location of the event
  4. boolean allDay - Is the event an "all day event" (AKA - untimed event). Default = false.
  5. calendar.time startTime - The start time of the event {year, month, day} OR {year, month, day, hour, min, second}. An example is {year: 2009, month: 12, date: 25} for Christmas, or {year: 2009, month: 10, date: 3, hour: 14, minute:30, second:0} for 2:30pm on Oct 3 (my birthday!)
  6. calendar.time endTime - The end time of the event. It has the same format as startTime above.
  7. Array<calendar.contact> attendees - Attendees for an event. In the form [{email : 'dave@gmail.com' }, {email : 'trevor@gmail.com' }]. Note that this is consistent with the format in other event APIs below.
  8. string rrule - A recurrence rule in the RFC 2445 format. For instance "RRULE:FREQ=WEEKLY;COUNT=10" repeats weekly for the next 10 weeks.
  9. number attendeeCount - The number of attendees in this event.
  10. calendar.contact owner - The contact information for the owner of the event.
  11. calendar.contact calendar - The contact information for the calendar that the event lives on.
  12. calendar.contact creator - The contact information for the person who created the event.
  13. string id - The id for the event. Appropriate to pass to showEvent()
  14. calendar.palette palette - The set of colors used to draw this event.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.