Getting Semantic With Microformats, Part 4: hCalendar ~ A Blog Not Limited

Here we are again, delving into the exciting (for me, at least) world of microformats. Based on what I planned at the outset, this article is about mid-way through the series. So far, I've discussed three implementations of microformats on A Blog Not Limited:

Specifying link-based relationships using the rel attribute in Part 1
Giving a "human face" to links using the XFN microformat in Part 2
Describing people, companies and places with the hCard microformat in Part 3

Not bad. But still barely scratching the surface of microformats.

So, let's dive right on in to the hCalendar microformat, which I use to add semantics and structure to my content about events and time/date-based activities.

Origins: iCalendar

iCalendar (or iCal) is a standard for sharing calendar data. Most frequently, it is used in email exchange, although it isn't limited to that medium.

Similar to hCard, hCalendar was introduced so that web publishers could include iCalendar data in their web pages.

hCalendar is a 1:1 representation of iCalendar, which allows parsers to extract event information from a web page so it can be used in calendar programs (among other uses).

Historical note: iCalendar is based on vCalendar (Virtual Calendar), which is an open source calendar application for posting and maintaining events and schedules online. vCalendar was developed alongside the vCard electronic business card format.

Date/Time-Based Activities

The hCalendar microformat describes the type of information about events (or anything that is date/time-based) that you would have on a calendar, including (but not limited to):

Summary
Date and time
Location
Detailed description
Recurrence

The Basics

Just like hCard, hCalendar has a few basic rules:

Properties and sub-properties are expressed as class values.
Because of the 1:1 relationship with iCalendar, the specified hCalendar properties are based on iCalendar property type names (i.e., vevent).
Property and sub-property names are case-sensitive.
The "root" property can't be combined with any of its properties. Thus,  is invalid.

And while this isn't a rule, it is important to keep in mind: the markup used doesn't matter.

The class values (properties/sub-properties) define the hCalendar microformat.

That said, I strongly encourage semantic (not to mention valid) markup.

The Profile

Update: 04/21/2010

Recently, the microformats community completed updates to the profile URIs for all microformats. The correct values have been updated in this article. See my Microformats Profile URIs Updated post for further details.

As with all microformats, it is recommended to reference the hCalendar profile in the <head> of web pages that include the microformat:

<head profile="http://purl.org/uF/hCalendar/1.0/http://microformats.org/profile/hcalendar">

The W3C allows multiple profile values, separated by white space, so you can list multiple profiles if you choose:

<head profile="http://gmpg.org/xfn/11 http://purl.org/uF/hCard/1.0/http://microformats.org/profile/hcard http://purl.org/uF/hCalendar/1.0/http://microformats.org/profile/hcalendar">

However, if you are referencing non-draft microformats (and hCalendar is non-draft), you can instead use the combined profile URL, which covers all non-draft microformats:

<head profile="http://purl.org/uF/2008/03/http://microformats.org/profile/specs">

If you are referencing both non-draft and draft microformats, you can use this combined profile with the profiles for new/draft microformats.

The Example

This blog is still relatively new. As such, I haven't had many opportunities to list event information.

In fact, I only have one live example, thanks to a recent BarCamp Albuquerque 3 article where I used the hCalendar microformat:

<div class="vevent">
Yes, it's short notice, but mark your calendars: <a href="http://barcamp.org/BarCampAlbuquerque" class="url summary">BarCamp Albuquerque 3</a> is this weekend.
<dl>
<dt>When:</dt>
<dd><abbr class="dtstart" title="2008-09-13T09:00:00">September 13</abbr>–<abbr class="dtend" title="2008-09-14T18:00:00">14</abbr>, from 9am–6pm both days</dd>
<dt>Where:</dt>
<dd class="location vcard"><a class="fn org url" href="http://www.chefwhite.com/cjw_cafe.php">CJW Cafe</a> on <a href="http://maps.google.com/maps" class="adr">4801 Alameda <abbr title="Boulevard">Blvd</abbr> <abbr title="Northeast">NE</abbr>, Albuquerque, <abbr class="region" title="New Mexico">NM</abbr> 87113</a></dd>
<dt>What:</dt>
<dd class="description">A <abbr class="duration" title="P2D">two-day</abbr> event all about the web — design (visual, experience, information architecture), technology (infrastructure, programming), social and new media, and other stuff that is just plain cool.</dd>
</dl>
</div>

The Parts of the Sum

Let's break this example down into its parts.

The Root: `vevent`

You may notice that the root property in my example is vevent, rather than vcalendar. This is because hCalendar has an optional root element of vcalendar, which is only required if you are describing more than one calendar of events on a given page.

For a page with a single calendar of events, the vcalendar property is assumed on the page itself.

Since my example is a single event in a single "calendar," I contain all of my event information in <div class="vevent">. This indicates that all of the content contained within is describing a single event.

Again, the containing element could be anything (<dl>, <ul>, , , etc.) the <div> is just appropriate for my example.

Required Properties: `summary` & `dtstart`

The only required properties for hCalendar (other than the root vevent) are summary and dtstart.

`summary`

The summary property describes a brief synopsis of the event. The content contained by this property is typically what displays in a calendar program as the name or title of the event.

So in my example, "BarCamp Albuquerque 3" is contained by summary, so that is the information that displays as the name/title in my personal calendar:

Yes, it's short notice, but mark your calendars: <a href="http://barcamp.org/BarCampAlbuquerque" class="url summary">BarCamp Albuquerque 3</a> is this weekend.

`dtstart`

The dtstart property describes the date/time for the start of the event. In my example, "September 13":

<dd><abbr class="dtstart" title="2008-09-13T09:00:00">September 13</abbr>–<abbr class="dtend" title="2008-09-14T18:00:00">14</abbr>, from 9am–6pm both days</dd>

Date/Time Design Pattern

Update: 06/02/2009

The datetime design pattern is now deprecated in favor of the value class pattern. See part 8 of this series for more on this new pattern.

Note that containing element for dtstart is an <abbr>, where the contained information is "September 13" and the title attribute value is "2008-09-13T09:00:00":

<dd><abbr class="dtstart" title="2008-09-13T09:00:00">September 13</abbr>–<abbr class="dtend" title="2008-09-14T18:00:00">14</abbr>, from 9am–6pm both days</dd>

This is the currently recommended approach for defining date/time information in a microformat — known as the datetime design pattern (which is an extension of the abbr design pattern).

This pattern was developed to support one of the basic tenets of microformats: to design for humans first, machines second. All the while, aiming to provide both human- and machine-readable information.

The logic is that machines — such as web applications — will use the title value, while browsers will display the content contained by <abbr> to humans.

Also, as part of the specification for using this datetime pattern, date/time information should be specified in ISO 8601:

YYYY-MM-DDThh:mm:ss — "Y" represents the year integers, "M" represents the month integers, "D" represents the day integers, "h" represents hour integers, "m" represent minute integers and "s" represents seconds integers.
YYYY-MM-DDThh:mm:ssZ — "Z" is used to indicate GMT.
YYYY-MM-DDThh:mm:ss+hh (or -hh) — the "+hh" and "-hh" indicate time offset in hours from GMT.

To put this in more understandable terms, 2008-09-30T13:00:00 = September 30, 2008, 1:00 pm (local time).

The "T" character in these examples separates the date information from the time information.

If you only have a date, simply omit the "T" and time information following it. Similarly, if you only have a time, omit the "T" and the date information preceding it.

There are, however and unfortunately, some accessibility issues with this pattern, which I describe later in this article. For now, though, let's continue with my example.

The Rest of the Date/Time Properties

There are two additional (and optional) date/time properties I included: dtend and duration.

`dtend`

The dtend property describes the date/time for the end of the event. In my example, "September 14":

<dd><abbr class="dtstart" title="2008-09-13T09:00:00">September 13</abbr>–<abbr class="dtend" title="2008-09-14T18:00:00">14</abbr>, from 9am–6pm both days</dd>

`duration`

The duration property describes the length (in time) of the event. In my example, two days:

<dd class="description">A <abbr class="duration" title="P2D">two-day</abbr> event all about the web — design (visual, experience, information architecture), technology (infrastructure, programming), social and new media, and other stuff that is just plain cool.</dd>

As with the date/time, duration information is specified using the datetime design pattern, where the "machine-readable" information is indicated by the title value, and the "human-readable" information is contained by the <abbr>.

Also, the title duration value is speficied according to ISO 8601, which indicates the value is preceded by a "P" to indicate a period of time.

This period of time can be indicated in years (Y), months (M), weeks (W), days (D), hours (H), minutes (M) and/or seconds (S).

Here are a few examples to, hopefully, make this clearer:

P2Y = duration of two years
P10D = duration of 10 days
P3H = duration of three hours
P2W = duration of two weeks
P12DT8H30M = duration of 12 days, 8 hours and 30 minutes

Let's Talk Accessibility

I briefly mentioned in Part 3 that there has recently been some discussion about accessibility problems with the datetime design pattern.

The crux of the accessibility problem is how screen readers deal with title attribute values: they read/speak them.

So, where the datetime design pattern indicates putting the machine-readable ISO 8601 date/time information in the title, a screen reader speaks the value literally.

Imaging hearing this every time your screen reader came across <abbr title="2008-09-30">: "Two thousand eight dash zero nine dash thirty." And it is even worse for longer values with time information.

This is, arguably, not human-friendly to those users.

At present, these issues have not been resolved. There have been a few proposed alternatives, but the Microformats community continues to discuss the best approach for moving forward to resolve accessibility concerns and remain true to the spirit of microformats.

For me and my personal blog, my analytics indicate I don't have any screen reader visitors. So, I'm not currently concerned about my implementation of the datetime design pattern on this blog.

However, I work for a large corporation and lack of accessibility simply isn't acceptable (to me or my immediate supervisor, though I'm sure the "bobbleheads" could care less).

As such, I am anxious to see how these issues are resolved, so I can properly implement date/time information in microformats and still support any screen reader users.

Now, time to get back to the example and the remaining properties used …

The Rest of the Rest

My example includes four additional (also optional) properties: url, category, location and description.

`url`

The url property describes a link (<a>) for the event:

Yes, it's short notice, but mark your calendars: <a href="http://barcamp.org/BarCampAlbuquerque" class="url summary">BarCamp Albuquerque 3</a> is this weekend.

You may note that I included the url property along with the summary property. This is simply because the content contained by the <a> just happened to be the value for my summary. Other implementations could be different.

`category`

The category property describes the type of event. In my example, "BarCamp":

Yes, it's short notice, but mark your calendars: <a href="http://barcamp.org/BarCampAlbuquerque" class="url summary">BarCamp Albuquerque 3</a> is this weekend.

Unlike the properties I've mentioned thus far, category can be used an unlimited number of times. Some common examples of category values are:

Meeting
Expo
Vacation
Anniversary
Conference

In some sense, category is a way of "tagging" the event. So, if I had chosen to mark up my example to include a link to the main BarCamp site, I could've also used the rel-tag microformat to accompany category:

You may be wondering what is <a href="http://barcamp.org/" class="category" rel="tag">BarCamp</a> anyway?

Remember, rel-tag can only be used on links (<a>).

`location`

The location property describes where the event will take place.

<dd class="location vcard"><a class="fn org url" href="http://www.chefwhite.com/cjw_cafe.php">CJW Cafe</a> on <a href="http://maps.google.com/maps" class="adr">4801 Alameda <abbr title="Boulevard">Blvd</abbr> <abbr title="Northeast">NE</abbr>, Albuquerque, <abbr class="region" title="New Mexico">NM</abbr> 87113</a></dd>

In my example, I provide the name of the venue and its address. However, it can be just the venue, or just the address; both aren't required.

`description`

Finally, the description property describes a more detailed synopsis of the event than summary:

What I Didn't Include

There are several more commonly-used properties for hCalendar that I simply chose not to include in my example:

dtstamp indicates the date/time the hCalendar information was created.
last-modified indicates the date/time the provided hCalendar information was updated.
status indicates the event confirmation. Allowed values are "cancelled," "confirmed" and "tentative."
class indicates the event classification. Allowed values are "private," "public " and "confidential."
rrule indicates regular recurrence of an event. If this property is used, it has a required sub-property of freq to indicate the frequency of recurrence, which is further specified by qualifiers (i.e., count, interval).
rdate indicates events that recur irregularly. The title value reflects the irregular dates (comma-separated).

And there are still others that can be utilized. Reference the hCalendar examples wiki for further detail.

hCalendar + hCard

Perhaps, by now, you've noticed that my hCalendar markup includes hCard properties and sub-properties:

As I mentioned in Part 3, combining microformats is easy and, where it makes contextual sense, adds more semantic value to the content (and you know how I feel about that).

Further, it gives the user just another bit of data that can be extracted and used, such as a vCard for their address book.

In this instance, the location property of hCalendar makes perfect sense to also be marked up with vcard. Even if I had only included the city, I could've still added hCard properties/sub-properties.

Natural Language

I talked about using microformats in natural language (in the flow of regular sentences) in Part 3, and hCalendar is no exception to this concept.

You will note in my example that some of the hCalendar information is directly in the flow of my content.

I could've put all of the hCalendar information in natural sentences, rather than "chunking" out some of the details in a <dl>:

<div class="vevent">
Yes, it's short notice, but mark your calendars: <a href="http://barcamp.org/BarCampAlbuquerque" class="url summary">BarCamp Albuquerque 3</a> is this weekend, <abbr class="dtstart" title="2008-09-13T09:00:00">September 13</abbr>–<abbr class="dtend" title="2008-09-14T18:00:00">14</abbr>, from 9am–6pm <abbr class="duration" title="P2D">both days</abbr>.
This year's BarCamp is all about the web: design (visual, experience, information architecture), technology (infrastructure, programming), social and new media, and other stuff that is just plain cool.
<a class="fn org url" href="http://www.chefwhite.com/cjw_cafe.php">CJW Cafe</a> (on <a href="http://maps.google.com/maps" class="adr">4801 Alameda <abbr title="Boulevard">Blvd</abbr> <abbr title="Northeast">NE</abbr>, Albuquerque, <abbr class="region" title="New Mexico">NM</abbr> 87113</a>) is hosting this event.
</div>

Add to Your Calendar

Also on the BarCamp Albuquerque 3 article, I provide a link for users to add the event to their calendar:

This link could be a direct URL to any iCalendar file (i.e., .ics, .ical, .ifb, .icalendar) with your event's information. For me, though, I used Technorati's Events Feed Service.

Using Technorati's technology, you simply prepend the URL of the page where your hCalendar microformat resides with http://feeds.technorati.com/events/ and t,hen use the resulting URL as the href value for your link (<a>):

<a href="http://feeds.technorati.com/events/http://www.ablognotlimited.com/articles/barcampalbuquerque-around-the-corner" title="Download .ics file">Add to your calendar</a>

When a user selects that link, the .ics file is dynamically created and they can download it:

Downloading BarCamp Albuquerque 3 event .ics file

Appearances Matter

I've said it a couple of times: the markup doesn't matter (though it should, ideally, be valid and semantic).

And while the class values (properties/sub-properties) are essential to the microformat, the CSS you use to style your hCalendar information is solely for presentation (not to say that isn't important).

I would recommend, though, utilizing the class values that are required for hCalendar in your CSS, rather than adding new classes for styling. This just gives you leaner CSS.

For an example of how you can style a calendar of events, take a look at the wonderful work Jeremy Keith did for cascading calendars.

Ultimately, you can do anything your heart desires. the presentation of your hCalendar is only limited to your CSS skills.

Why Bother? The Benefits, Of Course

While I've covered most of these benefits previously in this series, they are all worth repeating … primarily because microformats are so very simple to implement and they offer such potential.

I wish more people knew about them and used them. It would help increase the number of tools and applications that use them.

Here We Go Again: Semantics

Yep, semantics. You must think it is my favorite concept. Well, you'd be right.

Microformats take existing standards, like XHTML elements, and add even more semantic value to the content they contain. This, from my perspective, helps web publishers create better sites that are more usable for and accessible to both humans and machines (like search engines).

Further, embracing semantics (even without microformats, but in the markup itself) supports standards; standardized ways of developing sites. This not only benefits users (and that includes machines), but designers/developers and teams. It benefits everyone.

And, again, these approaches lay (a semantically rich) foundation for The Semantic Web, while simultaneously allowing us to take advantage of today's web and technologies.

Cool Shit

I do understand that semantics and standards are mostly philosophical discussions for some folks. Ultimately, you either "get it" or you don't.

If you are in the latter camp, consider some of the useful and rather cool tools available today that leverage the hCalendar microformat.

Browser Add-Ons

There are a handful of browser tools that extract hCalendar information from a web page so that it can be exported and used applications that support iCalendar.

The Operator add-on for Firefox extracts hCalendar information and allows you to add it to your preferred calendar application (it does the same with hCard information for your address book):
Also for Firefox, the Tails Export add-on detects hCalendar information (as well as hCard) and extracts it for export to your calendar application:
The Safari microformats plugin works simliarly to the Firefox add-ons, extracting hCalendar (and hCard) information for you to add to your calendar program.
The brower-independent microformats bookmarklet, too, extracts hCalendar information that you can export to your calendar application:

Other Services

Brian Suda's X2V is an XSLT stylesheet that extracts hCalendar information from a web page to create an iCalendar .ics file.
Technorati offers a microformats search engine that indexes microformat information (hCalendar, hCard and hReview) from submitted URLs and makes that information available to search.
Elias Torres created a hCalendar + Google Calendar Reminders GreaseMonkey script that identifies hCalendar information on a web page and provides an icon to add that event to your Google Calendar.
Another GreaseMonkey script from Les Orchard allows you to modify Firefox form textarea fields to become hCalendar generators: Magic Microformat Forms.

There are still more hCalendar implementations I haven't mentioned.

Peer Pressure

If these resources haven't turned your head, then maybe a bit of peer pressure will. Many of today's leading services are utilizing hCalendar (and other microformats):

Yahoo!'s Upcoming events site uses hCalendar, so as users browse events they can import them into their calendar application.
MapQuest Local also supports hCalendar, as well as hCard and geolocation microformats.
TripIt uses hCalendar markup for its itineraries.
Last.fm uses hCalendar for its concert announcements.
Social networking giant, Facebook, uses hCalendar for event information.

And there are even more hCalendar examples in the wild than these.

C'mon, you know you wanna do it. Just try it. Trust me, you'll like it.

Tools to Make It Easier

So, if I've managed to "sell" you on microformats, you may be pleased to know that there are a few tools out there to make it easier for you to implement (opposed to hand-coding everything, not to mention remembering all the properties/sub-properties):

The hCalendar Creator, courtesy of the Microformats community, is a form that generates hCalendar markup and properties/sub-properties from information you submit. Copy and paste. Couldn't be simpler.
Both the pnh_mf plugin and JMC_Event_Manager give you an easy way to add microformat content, including hCalendar, to your Textpattern blog/site.
WordPress, too, has a couple of plugins that help web authors add microformats to their WordPress blogs/sites: Structured Blogging (which is also available for MovableType) and WP-Microformats.
Courtesy of WaSP, there is a Dreamweaver microformats extension, which was designed for DW 8, but they say will work for MX and above.
The Conference Schedule Creator helps you create a complete conference schedule with all events marked up with hCalendar.

Coming in Part 5

That's all I've got for hCalendar (isn't it enough?).

Next time, in Getting Semantic With Microformats, Part 5, I'll be detailing the hAtom microformat for syndicated content such as blog posts.

Until then …

Update: 10/18/2008

Christophe Ducamp has translated this article in French: Parvenir à la Sémantique avec les Microformats, 4ème partie – hCalendar.

Unfortunately, I don't read French, so I can't attest to the translation. But in the spirit of spreading the good word about microformats, I'm going to promote the translation and hope it is accurate. The way I see it, the more people who know about microformats, the better.

Update: 11/27/2008

Jan Sládek has translated this article in Czech: Kódujme sémanticky s mikroformáty: 4. část - hCalendar.

I don't read Czech either, so I can't speak for the translation. But the intention is good, so I'm promoting it.

Update: 12/07/2008

Jia Mi has translated this article in Chinese: 使用微格式来丰富网站语义：hCalendar.

A Blog Not Limited

to web design, standards & semantics