Google Apps Platform

Google Calendar Event Gadgets Reference Guide

As more of our lives revolve around our calendars — when things are due, where we have to be right now — it's useful to see other information with our dates. This could mean seeing the weather forecast or not missing one of the Google Doodles. If you use Google Calendar you may be interested in Calendar Event Gadgets. This feature enables you to add just about any kind of content to your calendar and leverage the growing gadgets developer community. Intrigued? Read on! This article will go on to show you what they look like, what they can do, and how you can get in on the action.

Contents

Audience

This document is intended for anyone interested in learning more about Calendar Event Gadgets — what they are, how to use them, and how to write and adapt gadgets for Google Calendar.

What are Calendar Event Gadgets?

Calendar Event Gadgets are special events that appear as icons above a day's events. When clicked, the icon can pop up with any image, webpage, or a gadget. Try it out below!

Let's go over the extra fields that make Calendar Event Gadgets different than a run of the mill "Lunch with Steve" appointment in your calendar.

  • Icon: The URL to the icon that will be displayed at the top of the day.
  • URL: The URL to the content (gadget specification, webpage, or image).
  • Type: The type of the content that will pop up (ie. application/x-google-gadgets+xml, text/html, image/*).
  • Width: The width of the pop-up box.
  • Height: The height of the pop-up box.
  • User Preferences: Any user preference associated with the content if the content is a gadget.

Additionally, Calendar Event Gadgets are specified as all-day events. To specify all-day events, set the start time and end time one day apart. For example, if you want your Calendar Event Gadget to appear on 2007-03-14, then the start time is 2007-03-14 and the end time is 2007-03-15.

The only required field is the icon URL. In its most simple form, Calendar Event Gadget content can consist of just the icon above the day's events — like the Phases of the Moon calendar above. If you want to point to a webpage or image, the type, width, and height must also be provided. For example, the birthday reminder below pops up with an image (click the birthday hat).

How can I create Calendar Event Gadgets?

Let's say that you want to have your favorite gadget - Word of the Day, added as a Calendar Event Gadget in your calendar. (All in the pursuit of personal edification, of course.) There are many ways to add a gadget and varying degrees of difficulty.

We'll go into more detail about using the "of the day" Calendar Event Gadget creator, the various ways to use the iCalendar format, and the Calendar API v3. It's helpful to have programming knowledge and internet hosting in general, but there are many things you can do with minimal coding and no internet hosting. There is also a difference in how the Calendar Event Gadgets are added to users' calendars. Published iCalendar files and URLs generated by the "of the day" creator are maintained as separate calendars that users can add to their list of calendars. Importing an iCalendar file and using the Calendar API v3 inserts these events into the given calendar. If you just want to convert an existing gadget to a Calendar Event Gadget, the "of the day" Calendar Event Gadget creator is an easy way to do so without maintaining any additional files. If you want to provide a Calendar Event Gadget that pops up a picture on every US Holiday, publishing a static iCalendar file can be done without any coding.

Of course, doing more sophisticated things with the gadget itself may take expertise and hosting, but how to write gadgets is out of scope for this document. Please visit the gadgets documentation for a great starting place.

You should peruse all the available methods and decide which works best for you.

Using the iCalendar Format

iCalendar format is a standard for calendar data exchange. See below for the Word of the Day example converted into iCalendar format.

BEGIN:VCALENDAR
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME;VALUE=TEXT:Word of the Day
VERSION:2.0
BEGIN:VEVENT
DTSTART;VALUE=DATE:20070720
DTEND;VALUE=DATE:20070721
SUMMARY:Word of the Day - with pronunciation audio!
X-GOOGLE-CALENDAR-CONTENT-TITLE:Word of the Day
X-GOOGLE-CALENDAR-CONTENT-ICON:http://www.thefreedictionary.com/favicon.ico
X-GOOGLE-CALENDAR-CONTENT-URL:http://www.thefreedictionary.com/_/WoD/wod-module.xml
X-GOOGLE-CALENDAR-CONTENT-TYPE:application/x-google-gadgets+xml
X-GOOGLE-CALENDAR-CONTENT-WIDTH:330
X-GOOGLE-CALENDAR-CONTENT-HEIGHT:100
X-GOOGLE-CALENDAR-CONTENT-GADGET-PREF;NAME=Format:0
X-GOOGLE-CALENDAR-CONTENT-GADGET-PREF;NAME=Days:1
END:VEVENT
END:VCALENDAR

There are two ways to add events using iCalendar:

  • Import an iCalendar file directly into your calendar. This will actually add the gadget events to your calendar.
  • Provide the URL to an iCalendar file. This will add a calendar to your list of calendars on the left hand navigation.

Try importing the event above into your calendar by copying and pasting it into a text document. Save the document with an ".ics" extension, then upload it into your calendar. For instructions on how to import iCalendar files into your calendar, see here.

You can also provide the URL to a published iCalendar file - add the above event as a separate calendar by clicking here. Maintaining a published iCalendar file is a good way to add content programmatically. You can set up a script to periodically update content for anyone who's added your gadget to their calendar. The downside to this method is that updates may take a few hours for the new information to be parsed and viewable by your users.

Note: The uploaded file must be accessible publicly on the internet. It will not be indexed if located on, say, an intranet.

Using the Google Calendar API v3

Google Calendar allows client applications to view and update calendar events in the form of JSON feeds. Your client application can use the Google Calendar API v3 to create new events, edit or delete existing events, and query for events that match particular criteria. Requiring the most programming knowledge, the Calendar API v3 can be used to insert gadgets by specifying extra fields in a calendar event. Using JSON protocol, events are added to the user's calendar instead of included as an external calendar. Because write calls are being made to a user's calendar, user authentication has to be dealt with. For more information on authentication, please see the Account Authentication documentation and the Authorizing Requests to the Google Calendar API.

A standard calendar event entry in JSON format looks something like this:

{
 "summary": "Word of the Day",
 "start": {
  "date": "2013-09-18"
 },
 "end": {
  "date": "2013-09-19"
 },
  ...
}

The extra JSON elements in a calendar event entry for a Calendar Event Gadget would look like this for the Word of the Day gadget:

"gadget": {
 "type": "application/x-google-gadgets+xml",
 "title": "Word of the Day",
 "link": "http://www.thefreedictionary.com/_/WoD/wod-module.xm",
 "iconLink": "http://www.thefreedictionary.com/favicon.ico",
 "width": 300,
 "height": 136,
 "preferences": {
  "Format": "0",
  "Days": "1"
 }
}

To make your lives easier, API v3 offers client libraries in many different languages, making it possible to operate on gadgets programaticaly.

Creating and Inserting a Calendar Event Gadget using the Java Client Library

To insert Calendar Event Gadgets using the Java client library it is needed to fill a gadget field of the event resource with appropriate data. First we need to create an event resource which will contain a gadget.

Event event = new Event();

event.setSummary("Word of the Day");
DateTime start = DateTime.parseRfc3339("2007-03-14");
DateTime end = DateTime.parseRfc3339("2007-03-15");
event.setStart(new EventDateTime().setDate(start));
event.setEnd(new EventDateTime().setDate(end));

Note: The title that is set in the event is not seen in the normal display. It will only be displayed to describe the event in Agenda view, e-mail, pop-up, or SMS alerts associated with the event.

Next, create a Gadget object and set all the familiar fields associated with our Word of the Day example. The gadget's user preferences are stored in a HashMap as name/value pairs. After the gadget object is good to go, it can be added to the newly created event by using setGadget method.

Gadget gadget = new Gadget();

gadget.setTitle("Word of the Day");
gadget.setType("application/x-google-gadgets+xml");
gadget.setIconLink("http://www.thefreedictionary.com/favicon.ico");
gadget.setLink("http://www.thefreedictionary.com/_/WoD/wod-module.xml");
gadget.setWidth(300);
gadget.setHeight(136);

Map<String, String> prefs = new HashMap<String,String>();
prefs.put("Format", "0");
prefs.put("Days", "1");
gadget.setPreferences(prefs);

event.setGadget(gadget);

The Calendar Event Gadget can now be inserted by an authenticated service object. For more information about how to authenticate, see the Authorizing Requests to the Google Calendar API.

service.events().insert("primary", event).execute();

Tips and Best Practices

Here are some things to keep in mind when planning out a Calendar Event Gadget.

  • In general, it's better to maintain a separate calendar for people to add to their own instead of adding gadgets directly into their calendar. You can still use the API v3 and import iCalendar files directly into a public calendar you manage. You can avoid dealing with user authentication this way, and it is more manageable for the user.
  • Don't have the gadget appear every day. (This is different than appearing only on the current day.)
  • If you have the gadget appear every day, try to vary the icon (so that it carries relevant information).
  • Calendar Event Gadgets are designed to be all-day events, so if you want to describe a timed event, then you should have two separate events: one which is an all-day Calendar Event Gadget and one that is a non-Calendar-Gadget timed event
  • You can delete Calendar Event Gadgets through the UI in the Agenda view.

Further Resources

Hopefully, you've been inspired to create useful and fun additions using Calendar Event Gadgets; whether it be a daily event that shows today's top Digg stories, or new videos from your favorite artists on YouTube. The possibilities are only limited by what can be shown on a webpage. Try it out and give us feedback in the Google Calendar discussion group. Happy coding!

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.