Adding Events to Users Calendars – Part 1 – iCal/vCal

I’ve just been figuring out how to use iCal/vCal to add events to users calendars and the resources I found were a little dry so here’s a quick and dirty HOWTO.

Set up some code on your server to return the text below, and set the “Content-Type” header of the HTTP Response to text/calendar

Getting something working

First up I tried getting a basic event into Outlook (the calendar I have to hand). I found that without the DTSTAMP field Outlook threw a non-specific wobbly. When this field is included Outlook treats it as the creation time of the event. More info on the quirks of specific implementations can be found on the relevant Wikipedia article.

My first working file looked something like this:

PRODID:-//hacksw/handcal//NONSGML v1.0//EN
SUMMARY:Test event
DESCRIPTION:Nothing much

Note the VEVENT element nested inside the VCALENDAR element like in XML.

All-day events

This seems to work, although seems to be putting the dates into Outlook an hour later than I would’ve expected (and we’re in GMT not BST so it’s not that). In any case, I want to return these as all-day events since we don’t store the specific time of the event. The format for that seems to be DTSTART;VALUE=DATE:20070930, which makes sense. The VALUE=DATE seems to be a way of specifying the data type for a field, in this case DATE rather than DATE-TIME.

Setting reminders

Next I want to add a reminder to my calendar item. One week should do the trick. Looking at the code below you can see that I’ve nested a VALARM element within the VEVENT element. Using a TRIGGER value of “-PT7D“, I should now get a notification from my calendar a week before the event. You can also use other units, “-PT3H” would be three hours, “-PT5M” would be five minutes, you get the picture.

Alternatively you could input a specific time for the reminder to go off by overriding the TRIGGER field, like this: TRIGGER;VALUE=DATE-TIME:20080117T133000Z.

Final output

This is my final static version with an all-day event and a reminder.

PRODID:-//hacksw/handcal//NONSGML v1.0//EN
SUMMARY:Test event
DESCRIPTION:Nothing much
DESCRIPTION:Reminder to do something


That’s about as far as I need to go with this, now I just need to hook it into the database and link to it correctly. Let me know if you find this useful, or find mistakes, either way someone’s learning something.

Tip: If you’re trying to debug your iCal response, try using the Firebug plug-in for Firefox. The “Net” tab will show you the response your server is returning.


5 Responses to Adding Events to Users Calendars – Part 1 – iCal/vCal

  1. Hi Richard,

    Thanks for this quick & dirty examination of how to add events to user calendars.

    This is something I’ve been looking at trying to do for far too long but couldn’t seem to get that final stage working between getting the event elements coded correctly and written out properly – the various samples I’ve seen on the web all seemed to contradict each other.

    This article manages to boil everything down to their basics.


  2. Richard Marr says:

    No worries John, glad my notes helped.

    • mithil says:

      I am trying to add a reminder to my vcs file. I copied your Final output text as it is and saved it as .vcs
      It is not working for me, can you please help me?


      • Richard Marr says:

        Hi Mithil,

        I’ll help if I can but I don’t have as much information as you, you need to be a bit more specific. Are you generating this file from a web server or are you just creating a file by hand? What OS and calendar app are you using?


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: