Ever wanted to offer your readers the possibility to add a specific event to their Windows Live Calendar? Evan of Windows Live Hotmail team tells you just how to do that.
All it takes for this to work is a single link in your Web page. Here’s what the URL looks like:
When users click that link, they will go right to Windows Live Calendar with an “Add Event” dialog pre-filled with your data (see below). All they have to do is click Save. If they’d like, they can also customize reminders, write remarks in the Details, or make any other changes they’d like before saving it. Nifty eh?
So, what is all this gobbledygook in the URL and how do you make it work for you?
Looking at the url we first see rru=addevent. This is required and means the first thing to do after logging in is to bring up the “add new event” form. The additional parameters specify your data:
dtstart Start date and time dtend End date and time summary The title of the event location The location of the event description The detailed description of the event So all you need to do is complete the URL with your event’s information in these parameters, making sure it is URL-encoded properly , and you’re ready to go!
Now go ye forth and – no, wait, there’s still one trick here. What about those dates? How do you format the date text? Well, since this was primarily intended for automated use by businesses and developers the date parsing isn’t very forgiving. It accepts dates in a format that you might normally only see buried in a .ics file, something called an ISO8601 date. The format for this is:
YYYYMMDDTHHMMSSZ
YYYY is the 4 digit year, MM is the 2 digit month, DD is the 2 digit day. T is literally the letter T (must be upper case). HHMMSS are hour, minute, and second in 24-hour time. The Z also has to be upper case and it means the entire string is a UTC time. So yes, to use this API you have to first convert your start (and end) time into UTC before you can use this API. You can also omit the Z and leave the time in local time, but this means the event is in “floating” time. A “floating” event at 2pm will happen at 2pm in each and every time zone. It is good if all the visitors are local or if you want an event to occur at midnight no matter where users are located, but not so good for coordinating worldwide events.
Let’s try to make one for MIX09:
1. Convert times to UTC.
How can we do this the easy way? Let’s use an online time converter. First question which time zone to convert from? PST? No no not PST, Daylight Savings Time starts on Sunday, March 8 so we’ll have to use PDT, which is UTC-7:
Start keynote on Day 1 (March 18): 9.00am DST = 16:00 UTC
End Conference, March 20: 3:15pm DST = 22:15 UTC
2. Other needed parameters:
title = MIX09
location = Las Vegas
3. Put everything in the URL:
<a href=http://calendar.live.com/calendar/calendar.aspx?rru=addevent&dtstart=20090318T160000Z&dtend=20090320T221500Z&summary=MIX09&location=Las%20Vegas target="_blank">Add MIX09 to Windows Live Calendar</a>
4. End result
Add MIX09 to Windows Live Calendar
As you can see it gets converted to my time zone when I add this Event to my Windows Live Calendar by clicking the URL.
Some tips for best usage from Evan:
- Set the target of the link to be “_new” or “_top”. Calendar uses the entire browser window to avoid layout issues and cross site scripting bugs. So you should plan for that up front – this target will remind you that this link is going to break users out of your UI entirely. And when the user is finished we leave her in the Calendar UI rather than returning her to your site, you may wish to target “_new” to maintain site continuity in the original window/tab.
- For the same reason, don’t try to load the link in just one part of your UI if you are using frames. We’ll break out of the frame and take over your whole UI.
Thanks Evan, I’m sure this will come in handy for many of us.
