Customizing the Display of Google Calendar Feeds

by Hans DeBano

1. Google Calendar "Views"
2. What Degree of Customization do I Need for Displaying Calendar Data?
3. The Google AJAX Feed API
   1. An API Example: Displaying ASU's Student Academic Calendar in a Web Page
   2. API Example: Prerequisites
   3. API Example: HTML and JavaScript
   4. API Example: Notes
4. Server vs. Client-side Approaches to Displaying Feeds

One extremely useful feature of Google Calendar is the ability to expose a calendar publicly, to share with friends, family, clubs, etc. When a calendar has been shared with everybody, there are several "views" of it that Google automatically makes available. These different views of a public calendar include:

1. an embedded (HTML) view of the calendar that can be displayed in a web page
2. an iCal format of the calendar
3. an Atom (XML) feed of the calendar

In addition, it's also possible to use one of many available calendar Google Gadgets to display a calendar gadget on a web page.

This article will focus on view #3: the feed and how this can be customized to display calendar events on a web page. This approach, rendering an Atom/RSS feed on a web page, isn't limited to calendar events—the general strategy can also be employed to display any RSS or Atom feed, such as one of an almost unlimited number of news feeds, on a web page.

There are special circumstances, however, where it's important to have more customization over how the event data is displayed on a web page. For this purpose, the Google AJAX Feed API, described next, allows a high degree of customization in how feed data is ordered and displayed on the page. It also provides you with extensive control over the HTML markup wrapping the calendar data.

The Google Ajax Feed API allows you to download public RSS or Atom feeds using only JavaScript. The feed formats supported are:

• Atom 1.0
• Atom 0.3
• RSS 2.0
• RSS 1.0
• RSS 0.94
• RSS 0.93
• RSS 0.92
• RSS 0.91
• RSS 0.9

The Developer's Guide for this API is available at: http://code.google.com/apis/ajaxfeeds/documentation/ .

To get started using the API, you'll need to obtain an API key. To do this, you'll need a Google account, and once you've accepted Google's API Terms of Use, Google will display your new key on a web page. Then you'll be able to copy it from the web page and store it for future reference, as well as start using it in pages on your site.

The key applies to any directory (and its subdirectories) on your web site. You can create multiple API keys if you have multiple web sites.

The API documentation presents multiple code examples of using the Feed API.

Although the API has functionality for working with collections of feeds and discovering feeds, the instructions here will only relate to displaying a single feed on a web page.

Suppose that you want to display the next five upcoming events from ASU's Student Academic Calendar in a maroon box on your web page like this:

To fine-tune the fonts, spacing and colors used in the box, you'll want to use CSS. Furthermore, let's say that because you're picky about the HTML used to display the feed, you'll want the HTML markup for your div (the box) to use an unordered list and a "when" class on the event dates in each list item like this:

1. your Feed API key

This is the Google Ajax Feed API key that you obtained earlier. This is described above in "The Google AJAX Feed API."

2. the Google feed address (URL) of your calendar

Google's instructions describe how to get the public feed address, the "calendar address", of your calendar. (You'll be clicking on an "XML" button in the "Calendar Details" screen.) Note that ASU calendars will have a URL with a prefix like this: http://www.google.com/calendar/feeds/asu.edu...

It's important to note that various parameters can be added to the Google calendar feed address to customize the number, order and detail of events that it returns. The example JavaScript below uses the feed parameters: "orderby", "sortorder", "futureevents" and "max-results".

Equally important are the set of "projection names" that can be specified for a Google calendar feed. If you click on the XML button in "Calendar Details", the feed URL that you'll see is for the "basic" projection name. (You'll see "basic" as part of the URL.) You can replace "basic" with "full" or another projection name, as illustrated in the feed address used in the sample below.

3. CSS for formatting your feed div

You can use either external or inline CSS to control the appearance of your feed div. The styles might look something like this:

#feed {
  background: #903;
  border-top: 2px solid #eee;
  border-right: 2px solid #eee;
  color: #eee;
}

#feed a {
  color: #eee;
  text-decoration: none;
}

#feed a:hover {
  color: #ffb310;
  text-decoration: underline;
}

#feed h2 {
  margin: 16px 0 10px 20px;
  padding-right: 10px;
  font-size: 1.5em;
  font-weight: normal;
  color: #bababa;
}

#feed ul {
  margin: 0;
  padding: 10px 0 10px 0;
}

#feed ul li {
  list-style: none;
  margin-left: 0;
  padding-right: 15px;
  padding-left: 20px;
  font-size: 0.95em;
  line-height: 130%;
  color: #eee;
}

li span.when {
  color: #bababa;
}

4. the Atom elements containing your calendar data

The Google Data API specifies a namespace of allowed elements appearing in the calendar feed (and actually in more general contexts). If you use a projection value of "full", the feed XML will contain an extensive set of elements, one of which is "when". For example, the "when" element might appear in the Student Academic Calendar feed XML as: <gd:when startTime="2007-11-04" endTime="2007-11-05"/>. This element provides information about the starting and ending date (or datetime) of your event.

Your JavaScript can parse any of these Google elements present in the XML, depending on the level of customization desired.

5. JavaScript utility for parsing dates

The date and datetime values appearing in the Google "when" elements conform to a W3C subset of the ISO 8601 standards. Your JavaScript will need to parse this format if you'd like to manipulate those values. Fortunately, there is at least one example of this type of JavaScript parsing for your consumption.

• In line 6, you'll need to replace "{GOOGLEAPIKEYHERE}" with the value of your API key.
• In line 7, the JavaScript utility function used to parse ISO 8601 dates and datetimes was stored in an external file.
• The long URL for the Google feed is specified in line 11. It includes various feed parameters
• In line 12, "setResultFormat" can specify the feed results in XML, JSON, or a mixed-format. The example uses XML. The choice will determine how your JavaScript must parse the resulting feed
• Line 14 is a true "gotcha". If you don't specify "setNumEntries", the default will be to display only 4 feed entries. This is regardless of the value you specify in the "max-results" parameter of the feed URL itself.
• Line 16 specifies that the JavaScript modify an element in your HTML document with ID of "feed". You'll need to make sure there's such an element (the example used <div id="feed"> on line 65) or change "feed" to another value that is present in your HTML.
• The "for" loop on line 21 creates a list item (<li>) for each entry in the feed. These items are appended to the unordered list in line 54.
• Line 62 specifies the external CSS URL for formatting the display of the feed data. The same CSS appears above.