Skip to content

Know your hCalendar

hCalendar

status

Specification

authors

Description

hCalendar is a 1 to 1 representation of the properties and values of iCalendar (IETF RFC 2445) in HTML. iCalendar is an interoperable format for calendaring and scheduling applications.

Usage

iCalendar is a reasonably complex standard, which is often not entirely implemented by supporting applications. As such, there is a current effort to create a simplified subset of iCalendar, “iCal Basic”. Aspects of iCalendar, while theoretically part of hCalendar, have yet to be implemented in HTML. As such, here we’ll only consider the fully implemented aspects of hCalendar.

The basic model of hCalendar is to “iCalendar object/property names in lower-case for class names, and to map the nesting of iCalendar objects directly into nested XHTML” (hCalendar specification).

hCalendar allows publishers to markup events, and other time/date based episodes (such as educational experience, and work experience).

hCalendars have an optional “vcalendar” root element. Where only a single calendar of events occurs on a page, where no root element is found, the page itself is assumed to be the root element. Where more than one calendar of events is found on a single page, the root element is any HTML element with a class value of “vcalendar”.

An hCalendar comprises 1 or more events. These are marked up in hCalendar as descendent elements of the root element, with a class value of “vevent”.

Required properties of events

At a minimum, a vevent requires a summary and a dtstart

summary
this is typically the name for the event
dtstart
start date: an ISO8601 formatted date/time for the commencement of the event. It is recommended that the abbr design pattern is used to give both a humanly readable version, and machine readable version of the date. For example <abbr title="20070207" class="dtstart">Feb. 6th 2007</abbr>.

common optional properties of events

description
provides a “more complete summary” of the event (iCalendar specification). An event may only have one description subproperty, so where for instance the description spans multiple paragraphs, a single div with class “description” should contain these pargraphs.
dtend
end date: the date/time at which the event ends, in ISO 8601 format. Remember that a date without a time is in effect midnight of the day before the date, so for timeless dates, use the date following the event date for it to be correct. It is recommended that the abbr design pattern is used to give both a humanly readable version, and machine readable version of the date. For example <abbr title="20070206" class="dtstart">Feb. 6th 2007</abbr>. (Due to a quirk of hCalendar, a DTEND date without a time value is midnight between the day before and the date specified, in effect, the day before, hence the mismatch between the title value and the humanly readable version). If a date and time value were used, the date part would be 20070206)
location
the location of the event. the ADR, GEO or hCard microformats can be used to mark these up in a more information rich manner.
url
a url for the event.

Examples

This is an example of an hCalendar for a single event. The containing vcalendar element would typically be optional (unless there were more than one distinct calendar on this page.) 

<div class=”vevent”>
<h3 class=”summary”><a href=”http://north.webdirections.org” class=”url”>Web Directions North</a></h3>

<div class=”description”>
<p>A Web design and development conference in Vancouver Canada.</p>
<p>Featuring a who’s who of international web experts….</p>
</div>
<p>From <abbr title=”20070206″ class=”dtstart”>Tuesday Feb. 6th</abbr> to <abbr title=”20070209″ class=”dtend”>Thursday Feb. 8th</abbr> 2007</p>
<p class=”location”>Renaissance Vancouver Hotel Harbourside</p>

</div>

Tools

Services using

Technorati Microformats Search (http://kitchen.technorati.com)
aggregates events marked up using hCalendar. Ping Pingerati (http://pingerati.net) so that technorati and other hCalendar aggregators know about your new or updated hCalendar marked up content
X2V (http://suda.co.uk/projects/X2V/)
by Brian Suda, converts hCalendar to iCalendar format, enabling importing into applications which support iCalendar of hCalendar cvontent, as well as subscription to hCalendar marked up calendars on web pages in applications like Thunderbird and iCal which support such subscriptions.
Life Lint Parser (http://lifelint.net/)
Similar to X2V, Life Lint converts hCalendar to iCalendar, RDF, and has optional Outlook 2002 compatibility (Outlook’s support for iCalendar format is not perfect).