A week or so ago, I came across a Google “code playground” website (http://code.google.com/apis/ajax/playground/#retrieve_events), which allowed you to interactively “play” with AJAX code that accessed the Google APIs.  There were all kinds of things in there.  You could access maps, blogs, calendars, images, translations services, and so on, and so forth.  It was a lot of fun, and provided a really nice way to quickly investigate the available services and features.

I’m also helping out a musician with a website to promote his services as a soundtrack composer, and one of the things I wanted to have on his site was a calendar showing the details of his upcoming performances.  Now this is work as a favor, and most of the site is going to be pretty static, so I didn’t really want to go to the trouble of making it PHP or Ruby on Rails, or to use a web content management system like WordPress.  But I did want him to be able to update the calendar, and here was a nice, simple method, which would allow him to use a public Google calendar, which in turn would be accessed by some Javascript (using AJAX) to display a nicely formatted list of performance events.

Deconstructing the sample code, there were three main areas of interest.

1. A URL which provided access to the public calendar
2. Interrogation of the resultset, and formatting for display
3. Some setting of parameters for the query to the calendar service

For the purposes of testing, I created a dummy public calendar with four entries.  The  sample code listed the URL as:

var feedUri = 'http://www.google.com/calendar/feeds/developer-calendar%40google.com/public/full';

So I thought it would just be a matter of swapping in my Google ID for the string developer-calendar%40google.com.  Nope, that gave me an error indicating that the URL was wrong.  I poked around in the calendar settings for my Google account, and found that I could get the calendar address as XML, ICAL, or HTML.  In this case the calendar ID was the easy to remember! qjufu69ca69kgimjd6s7ujjjdg@group.calendar.google.com.  So I swapped that in, and bingo! No events were displayed!  I took another look and noticed that the parameters in the particular example used a date range for the query.  I altered the end date to some time in the far future and now I was displaying my dummy calendar events.
The sample code didn’t do anything more than display the “title” of the calendar event.  My application was going to need more than that.  I wanted to get everything from the date & time to the location, and notes.  For this I was going to need to look at the javadocs, or more accurately jsdocs.  There was a link to the API Developer’s Guide from the Code Playground page, but all the examples seemed to deal with adding parameters to a GET statement, and when I tried doing this, by appending the parameters to the URL, it just caused errors.  I wanted the list of methods associated with the class CalendarEventEntry, which were being returned in an array by the calendar query.  I can’t tell you exactly how I found it (probably by doing a Google search), but I found it in the end at http://code.google.com/apis/gdata/jsdoc/2.2/index.html. Selecting the “google.gdata.calendar” package, and then the “google.gdata.calendar.CalendarEventEntry” class revealed the list of available methods.  Now, my calendar entries had data in the “Description” field, but there was no getDescription() method.  There wasn’t a getDescription() method that was inherited from any of its superclasses either.  I looked up and down the list, there was a getContent() method inherited from the root atom.entry class.  I plugged that in, added the additional method getText(), since the call returned an atom.Text object, and out popped the descriptions from my calendar entry.  Great.

Now I wanted to get the date & time for each event.  Going back to the jsdocs, and realizing that I was looking for something associated with start and end times, I found the method getTimes(), this looked promising.  Unfortunately, I went round and round in circles trying to get the start time from the gdata.When object, but to no avail.  Finally, I found an example by searching, which revealed that I should be interrogating the zeroth element of the array like this event.getTimes()[0].getStartTime().  Why?  I don’t know, but it worked, and now I was able to build a pretty good display string showing the date, title, description, and start time:

html += event.getTimes()[0].getStartTime().getDate().toLocaleDateString() + " - " + event.getTitle().getText() + ' - ' + event.getContent().getText() + ' - ' + event.getTimes()[0].getStartTime().getDate().toLocaleTimeString();

I now noticed that the events weren’t being returned in chronological order.  I didn’t want to have to sort them myself, there must be a way of sorting them in the query.  Going back to the jsdocs for the CalendarEventQuery object, I saw that there were methods for setOrderBy and setSortOrder, but my inexperience, or lack of frequent practice using javadocs/jsdocs meant that I couldn’t see the one thing that was staring me in the face.  Time to phone a friend.  My friend explained to me that the section titled “Field Summary” held the equivalent of enum or constant declarations, and that this was where the secret to supplying the correct parameters to the setOrderBy and setSortOrder methods.  These static values were ORDERBY_START_TIME and SORTORDER_ASCENDING, so by popping these, using the proper syntax, I had:

query.setMinimumStartTime(startMin);
query.setMaximumStartTime(startMax);
query.setOrderBy(google.gdata.calendar.CalendarEventQuery.ORDERBY_START_TIME);
query.setSortOrder(google.gdata.calendar.CalendarEventQuery.SORTORDER_ASCENDING);

This set the date range, and the sort order.

So now I had everything in place to implement the AJAX Google calendar on a fairly static website.