Add to Calendar with a jQuery Widget

If you deal with any kind of event-based information on your websites, you would probably really like an easy way of letting users add it to their calendar.

Unlike link sharing—where there are some great drop-in solutions like AddToAny and AddThis—calendar integration unfortunately remains a bit rough around the edges. Varying standards with varying degrees of adoption; consideration for desktop and web-based calendar clients; and the complicating factor of timezones make it all a bit harder than it really should be.

AddToCal is a jQuery UI Widget that I put together to help me solve the problem and do things like you see in the screen clip on the right. It's freely shared and available on github.

Using it on a web page is as simple as including the js links, binding it to the DOM elements or classes on your page that contain "events", and provide an implementation of the getEventDetails method that knows how to extract the event details from your particular DOM structure.

The example also demonstrates how to use AddToCal in conjunction with the hCalendar microformat for event notation (try it out here).

I've currently included support for the web-based calendars by Google, Yahoo!, and Microsoft Live. If you can serve iCal or vCalendar format event links then AddToCal also links to 30boxes and iCal/vCalendar desktop software—including the iPad Calendar application;-)

Serving iCal and vCalendar links

What about iCal and vCalendar formats? These are complicated a little because we need a URL to the respective iCal and vCalendar format resources .. so we need to be able to serve them before AddToCal can link to them.

Thankfully, this can be relatively trivial once you get a handle on the file formats. Here's an example of how to implement with Ruby on Rails.

Say we have an Events controller and associated Event model that represents an activity people may like to add to their calendars. A simple iCal implementation with ERB means creating a views/events/show.ics.erb along these lines:

BEGIN:VCALENDAR
PRODID:-//AddToCal Example//EN
VERSION:2.0
METHOD:PUBLISH
BEGIN:VEVENT
DTSTART:<%= @event.start_time.rfc3339 %>
DTEND:<%= @event.end_time.rfc3339 %>
LOCATION:<%= event_url( @event ) %>
SEQUENCE:0
UID:
DTSTAMP:<%= Time.zone.now.rfc3339 %>
DESCRIPTION:<%= event_url( @event ) %>\n<%= @event.full_title %>
SUMMARY:<%= @event.synopsis %>
PRIORITY:5
CLASS:PUBLIC
END:VEVENT
END:VCALENDAR

Sharp eyes will note the unusual rfc3339 helper method I've provided to make it easy to get date/times in RFC3339 format as required by the iCal and vCal standards. You could extend Time::DATE_FORMATS, but here I've simply added the method to ActiveSupport::TimeWithZone

class ActiveSupport::TimeWithZone
  def rfc3339
    utc.strftime("%Y%m%dT%H%M%SZ")
  end
end

To support vCalendar, we also implement views/events/show.vcs.erb

BEGIN:VCALENDAR
PRODID:-//AddToCal Example//EN
VERSION:1.0
BEGIN:VEVENT
SUMMARY:<%= @event.full_title %>
PRIORITY:0
CATEGORIES:SHOW
CLASS:PUBLIC
DTSTART:<%= @event.start_time.rfc3339 %>
DTEND:<%= @event.end_time.rfc3339 %>
URL:<%= event_url( @event ) %>
DESCRIPTION;ENCODING=QUOTED-PRINTABLE:<%= event_url( @event ) %> =0A<%= @event.synopsis %>
LOCATION;ENCODING=QUOTED-PRINTABLE:<%= event_url( @event ) %>
END:VEVENT
END:VCALENDAR

Depending on your Rails version and web server, you may have to teach it about these MIME types e.g. add to config/initializers/mime_types.rb:

Mime::Type.register "application/hbs-vcs, text/calendar, text/x-vcalendar", :vcs

Blogarhythm: Remember - Jimi Hendrix