hcalendar-brainstorming: Difference between revisions
AndyMabbett (talk | contribs) (→Other Implementations/Ideas: vVenue) |
m (Replace <entry-title> with {{DISPLAYTITLE:}}) |
||
(40 intermediate revisions by 10 users not shown) | |||
Line 1: | Line 1: | ||
{{DISPLAYTITLE: hCalendar Brainstorming }} | |||
[[to-do]]: this page could use just a bit more clean-up and reorganization. - Tantek | [[to-do]]: | ||
* this page could use just a bit more clean-up and reorganization. - Tantek | |||
* create "for hCalendar 1.0.1" and "for hCalendar 1.1" sections similar to the for hCard 1.0.1 and 1.1 sections in [[hCard brainstorming]] | |||
** and start considering/sorting hCalendar brainstorming proposals for 1.0.1 and 1.1 | |||
* update HTML source code examples to use "<source lang=html4strict>" feature of [[wiki2]]. | |||
* update iCalendar source code examples to use "<source lang=text>" | |||
This page is for trying out and documenting ways of using hCalendar which may involve more details than currently in the specification. | This page is for trying out and documenting ways of using hCalendar which may involve more details than currently in the specification. | ||
If you have a question, please check the [[hcalendar-faq|hCalendar FAQ]], and ask new questions on the [http://microformats.org/discuss/ mailing lists] first. | If you have a question, please check the [[hcalendar-faq|hCalendar FAQ]], and ask new questions on the [http://microformats.org/discuss/ mailing lists] first. | ||
== hCalendar authoring best practices == | == hCalendar authoring best practices == | ||
=== Tabular event calendars === | === Tabular event calendars === | ||
Line 31: | Line 28: | ||
*# parse its "headers" attribute as a space separated set of local IDs | *# parse its "headers" attribute as a space separated set of local IDs | ||
*# find the <code><td></code> and <code><th></code> elements referenced by those IDs (call them header cells) and consider them part of the element being parsed as follows: | *# find the <code><td></code> and <code><th></code> elements referenced by those IDs (call them header cells) and consider them part of the element being parsed as follows: | ||
*## Treat the header cells as children of the element, ordered by the order of ids in its "headers" attribute, immediately following the last child node (text or element) | *## Treat the header cells as children of the element, ordered by the order of ids in its "headers" attribute, immediately following the last child node (text or element) of the element. (The basic idea is that the content from those header cells is used to construct the VEVENT, but secondary to (AFTER) the content in the data cell itself, so that the data cell can customize/override part of the data in the header, e.g. if the header cell included both start time and location, and the event was being held at a different location). | ||
Real world example in the wild of a tabular event calendar marked up in this fashion: [http://we05.com/program.cfm Web Essentials 05 Session program]. | Real world example in the wild of a tabular event calendar marked up in this fashion: | ||
* See [[hcalendar-examples-in-wild#conference_schedules|hCalendar examples in the wild: conference schedules]]. | |||
* [http://web.archive.org/web/20051102094339/we05.com/program.cfm Web Essentials 05 Session program] (was at <nowiki> http://we05.com/program.cfm </nowiki> but that link went bad sometime in 2006-2007). | |||
** supported by [[X2V]] and [[Operator]] - two interoperable implementations. | |||
'''Note: We have gained sufficient experience with this that we should formalize this in both [[hcard-parsing]] and [[hcalendar-parsing]] since the table cell headers | '''Note: We have gained sufficient experience with this that we should formalize this in both [[hcard-parsing]] and [[hcalendar-parsing]] since the table cell headers technique is generic to all class name microformats. The specific use case of how to author a tabular display of events should be documented in [[hcalendar-authoring]]. Tantek''' | ||
==== rejected use of axis for more class names ==== | |||
The following step (which used to be #2 above after the "Treat the header cells..." step has been removed: | |||
* 2. Parse the "axis" attribute of a header cell as a comma-separated list of categories. These categories must be used in addition to (and before) any class names on that header cell for determining whether it is a property of the VEVENT. | |||
Reasons for removal: | |||
* The [http://microformats.org/discuss/mail/microformats-discuss/2008-March/011679.html axis attribute is for a human readable label / category], not a class name and thus this would be incorrect usage of the axis attribute. | |||
* No real world tabular event calendar example has ever needed the axis attribute for hCalendar parsing. | |||
* No implementation of tabular event calendar parsing has ever bothered to implement axis parsing (probably due to the lack of any real world examples that needed it). | |||
** This is not the case. It has been implemented by [http://buzzword.org.uk/cognition/ Cognition]. | |||
=== hCard locations === | === hCard locations === | ||
Line 93: | Line 102: | ||
Many online events (e.g. at http://upcoming.org/) indicate who is attending an event, and in fact, who is just "watching" as well in this case. Whereas RFC2445 says to use a "calendar address" (essentially an email address) for the "ATTENDEE" property, it has just enough hooks to make an hCard work instead (DIR for URL to the contact info etc.). Thus hCalendar attendees should be marked up with hCard so that the full semantics are conveyed. | Many online events (e.g. at http://upcoming.org/) indicate who is attending an event, and in fact, who is just "watching" as well in this case. Whereas RFC2445 says to use a "calendar address" (essentially an email address) for the "ATTENDEE" property, it has just enough hooks to make an hCard work instead (DIR for URL to the contact info etc.). Thus hCalendar attendees should be marked up with hCard so that the full semantics are conveyed. | ||
Inside an hCalendar event: | |||
<source lang=html4strict> | |||
<span class="attendee vcard"> | |||
<a class="url uid fn" href="http://example.org/u/1337"> | |||
<img class="logo" src="http://example.org/u/1337icon.jpg"> | |||
Carla Brown | |||
</a> | |||
</span> | |||
</source> | |||
But this is insufficient, as the ATTENDEE in iCalendar by itself implies nothing more than the person being an invitee since the default participation status (PARTSTAT attribute - see below) is "needs-action". | |||
==== participation status ==== | |||
There is the '''4.2.12 Participation Status''' (PARTSTAT attribute) of the ATTENDEE property, which can be used to indicate: | |||
* "NEEDS-ACTION" ; Event needs action (DEFAULT) | |||
* "ACCEPTED" ; Event accepted | |||
* "DECLINED" ; Event declined | |||
* "TENTATIVE" ; Event tentatively accepted | |||
* "DELEGATED" ; Event delegated | |||
Common event user interfaces have the following shared visible semantics which can be represented using the above PARTSTAT values: | |||
{| border="1" | |||
|- | |||
! common semantic | |||
! Upcoming.org | |||
! Evite.com | |||
! Socializr.com | |||
! Crush3r.com | |||
! pingg.com | |||
! <code>partstat</code> | |||
|- | |||
| RSVP unknown/unreplied | |||
| | |||
| NOT YET REPLIED | |||
| Not responded | |||
| undecided | |||
| | |||
| <code style="white-space:nowrap">needs-action</code> | |||
|- | |||
| RSVP No | |||
| | |||
| No | |||
| No | |||
| impossible / raincheck / not likely | |||
| no | |||
| <code>declined</code> | |||
|- | |||
| RSVP Maybe | |||
| Interested | |||
| Maybe / I Can't Decide | |||
| | |||
| play it by ear / will try to | |||
| maybe | |||
| <code>tentative</code> | |||
|- | |||
| RSVP Yes | |||
| Going | |||
| Yes | |||
| Yes | |||
| yes i plan to / count me in / will be early | |||
| yes | |||
| <code>accepted</code> | |||
|} | |||
Thus taking the above example, someone who has RSVP'd yes could/should be marked up with the PARTSTAT ACCEPTED value in order to distinguish them from the default, which is that someone is just an invitee, since the default for PARTSTAT is NEEDS-ACTION. | |||
<source lang=html4strict> | |||
<span class="attendee vcard"> | |||
<a class="url uid fn" href="http://example.org/u/1337"> | |||
<img class="logo" src="http://example.org/u/1337icon.jpg"> | |||
Carla Brown | |||
</a> | |||
(<span class="partstat"><span class="value-title" title="accepted">attending</span></span>) | |||
</span> | |||
</source> | |||
Someone who is simply "watching" or "interested" in an event can be marked up as following: | |||
<source lang=html4strict> | |||
<span class="attendee vcard"> | |||
<a class="url uid fn" href="http://example.org/u/2600"> | |||
<img class="logo" src="http://example.org/u/2600icon.jpg"> | |||
Michael Payne | |||
</a> | |||
(<span class="partstat"><span class="value-title" title="tentative">interested</span></span>) | |||
</span> | |||
</span> | |||
</source> | |||
However, if "tentative" is too strong of a semantic, then see below for using ROLE property which can be used to indicate non-participation. | |||
==== role non-participant ==== | |||
For watching, <code>ROLE=NON-PARTICIPANT</code> is the closest semantic in iCalendar RFC2445 - "NON-PARTICIPANT" is defined as "Indicates a participant who is copied for information purposes only" which sounds like "watching" to me. | |||
<source lang=html4strict> | |||
<span class="attendee vcard"> | |||
<a class="url uid fn" href="http://example.org/u/2600"> | |||
<img class="logo" src="http://example.org/u/2600icon.jpg"> | |||
Michael Payne | |||
</a> | |||
<span class="role"><span class="value-title" title="non-participant">(watching)</span> | |||
</span> | |||
</span> | |||
</source> | |||
Note: the <nowiki><span class="role"><span class="value-title" title="non-participant"> </span></span></nowiki> uses the [[value-class-pattern]] because we want to use the enumerated value of "non-participant" while indicating that information with the text "(watching)" in the UI. This isn't ideal, but it's currently the best of several alternatives taking into consideration proper use of semantic HTML (avoiding improper use), accessibility, and (expected) site presentation design. Note that the "non-participant" value is *right next to* the text that says "watching" which reduces the risk that the two versions of the same piece of data will get out of sync. | |||
This markup technique can be applied to real-world hCalendar markup, e.g. for http://upcoming.org/event/152831/ | |||
for the <nowiki><span>s</nowiki> that follow the "Attending" heading on that page | for the <nowiki><span>s</nowiki> that follow the "Attending" heading on that page | ||
< | <source lang=html4strict> | ||
<span class="attendee vcard"> | <span class="attendee vcard"> | ||
<a class="dynavatar_link | <a class="dynavatar_link" href="http://upcoming.org/user/48265/" id="user_48265" > | ||
<img | <img class="avatar logo" src="http://static.flickr.com/45/buddyicons/86708053%40N00.jpg" id="image_cbe16d4252b4b1aab58c787379d130f552994da2" align="" valign="" height="12" width="12" border="0" style="padding: 2px;" /> | ||
</a | </a> | ||
<a class="uid url nickname" href="http://upcoming.org/user/48265/" id="user_48265" title="Attending since Feb 15, 2007 02:15 PM" > | |||
<a class=" | |||
CPERIN</a> | CPERIN</a> | ||
</span | </span> | ||
</ | </source> | ||
and for the <nowiki><span>s</nowiki> that follow the WATCHING heading | and for the <nowiki><span>s</nowiki> that follow the WATCHING heading | ||
< | <source lang=html4strict> | ||
<span class="attendee vcard"><a class="dynavatar_link | <span class="attendee vcard"> | ||
</ | <a class="dynavatar_link" href="http://upcoming.org/user/29960/" id="user_29960"> | ||
<img class="avatar logo" src="http://static.flickr.com/16/buddyicons/39472722%40N00.jpg" id="image_2980a4eb9e608adc0341b318dfea501c5fed6621" align="" valign="" height="12" width="12" border="0" style="padding: 2px;" /> | |||
</a> | |||
<a class="uid url nickname" href="http://upcoming.org/user/29960/" id="user_29960" title="Watching since Feb 15, 2007 02:26 PM"> | |||
cee-dub</a> | |||
<span class="role"><span class="value-title" title="non-participant"> </span></span> | |||
</span> | |||
</source> | |||
Originally proposed/documented by [[User:Tantek|Tantek]] 19:34, 23 Feb 2007 (PST). '''Updated to use more readable code markup and [[value-class-pattern]] instead of abbr by [[User:Tantek|Tantek]] 23:04, 13 May 2009 (UTC) '''. | |||
==== Role property overlap ==== | ==== Role property overlap ==== | ||
Line 134: | Line 258: | ||
*# It will help avoid polluting existing hCard consuming applications. | *# It will help avoid polluting existing hCard consuming applications. | ||
* hCalendar consuming applications MUST IGNORE attendee role values that are outside the above list of four values. | * hCalendar consuming applications MUST IGNORE attendee role values that are outside the above list of four values. | ||
=== hCard organizer === | |||
In regards to representing '''RFC2445 4.8.4.3 Organizer''' (ORGANIZER property), using a real world example to develop a brainstorm proposal for how to use the respective [[hcalendar|hCalendar]] <code>'''organizer'''</code> property. | |||
Many online events (e.g. at [http://eventbrite.com/r/go Eventbrite]) indicate who is organizing or hosting an event. Whereas RFC2445 says to use a "calendar address" (essentially an email address) for the "ORGANIZER" property, it has just enough hooks to make an hCard work instead (CN for name of the contact, DIR for URL to the contact info etc.). Thus an hCalendar organizer should be marked up with hCard so that the full semantics are conveyed. | |||
Inside an hCalendar event: | |||
<source lang=html4strict> | |||
<span class="organizer vcard"> | |||
<a class="url uid fn" href="http://example.org/u/216"> | |||
<img class="logo" src="http://example.org/u/216icon.jpg"> | |||
John Smith | |||
</a> | |||
(<a class="email" href="mailto:jsmith@example.org">jsmith@example.org</a>) | |||
</span> | |||
</source> | |||
hCalendar to iCalendar processors should parse the embedded hCard and convert the fields accordingly when converting to iCalendar: | |||
* hCard "fn" to ORGANIZER CN | |||
* hCard "url uid" to ORGANIZER DIR | |||
* hCard "email" to ORGANIZER MAILTO | |||
* hCard "agent" "url uid" to ORGANIZER SENT-BY | |||
E.g. the example organizer hCard above would be converted to the following iCalendar: | |||
<source lang=text> | |||
ORGANIZER;CN=John Smith;DIR="http://example.org/u/216":MAILTO:jsmith@example.org | |||
</source> | |||
=== Photos and other attachments === | === Photos and other attachments === | ||
Line 146: | Line 301: | ||
<img src="http://farm1.static.flickr.com/183/411545406_c73ca4e613_t.jpg" | <img src="http://farm1.static.flickr.com/183/411545406_c73ca4e613_t.jpg" | ||
class="attach" | class="attach" | ||
alt=" | alt="The Wheel of Time" /> | ||
</a> | </a> | ||
</span> | </span> | ||
Line 161: | Line 316: | ||
class="attach" | class="attach" | ||
type="image/jpeg"> | type="image/jpeg"> | ||
The Wheel of Time</object> | |||
</a> | </a> | ||
</span> | </span> | ||
Line 187: | Line 342: | ||
ATTACHMENTS - - An iCalendar object can include references to Uniform | ATTACHMENTS - - An iCalendar object can include references to Uniform | ||
Resource Locators that can be programmed resources. | Resource Locators that can be programmed resources. | ||
==== event badges buttons ==== | |||
Events often have small graphics (badges or buttons) which are used to encourage other sites for promotional purposes. | |||
An hCalendar event can mark up its badge(s) with the "attach" property. Secondary sites that syndicate and republish such events could then automatically retrieve such attachments and use them in the visual appearance of the republication of such events. | |||
=== update for value class pattern === | |||
Update all hCalendar examples to make use of the [[value class pattern]] where such use would improve accessibility. | |||
=== how to use with HTML5 === | |||
Per [http://lists.w3.org/Archives/Public/public-html/2009Jun/0811.html Theresa O'Connor's email to public-html]: | |||
Add a section in hCalendar 1.0.1 describing how to use hCalendar in [[HTML5]], including optional use of HTML5's <time> element and/or microdata feature(s). Encourage [[HTML5]] to drop the "vevent" predefined microdata vocabulary and reference the updated hCalendar 1.0.1 spec instead. [[User:Tantek|Tantek]] | |||
== iCalendar generation best practices == | == iCalendar generation best practices == | ||
Along with the four base properties, you can define addtional properties through the use of the x-prop property. For best-practices for hCal to iCal transformers, it would be helpful if the transforming application added the following x-* properties: | Along with the four base properties, you can define addtional properties through the use of the x-prop property. For best-practices for hCal to iCal transformers, it would be helpful if the transforming application added the following x-* properties: | ||
Line 209: | Line 375: | ||
'''Note: We have gained sufficient experience with this that we should formalize this in [[hcalendar-parsing]]. Tantek''' | '''Note: We have gained sufficient experience with this that we should formalize this in [[hcalendar-parsing]]. Tantek''' | ||
: This doesn't seem like a good solution for the case when multiple hCalendars are published on a single HTML page. [[User:TobyInk|TobyInk]] 09:56, 4 Mar 2008 (PST) | |||
== iCalendar examples in hCalendar == | == iCalendar examples in hCalendar == | ||
Line 388: | Line 556: | ||
</nowiki></pre> | </nowiki></pre> | ||
=== | Is this how re-occuring weekly events (basically, my class teaching list) should be done? Note the use of DTEND and DTSTART to mark ending and starting times for the semester. Using markup from Harry Halpin's homepage http://www.ibiblio.org/hhalpin. | ||
<pre><nowiki> | |||
<span class="vevent"> | |||
<div class="rrule"><a | |||
href="http://www.inf.ed.ac.uk/teaching/courses/2007/lsi.html">Language | |||
Semantics and Implementation</a> meet at DHT | |||
7.18 <abbr | |||
class="freq" | |||
title="weekly">every</abbr> <abbr class="BYDAY" | |||
title="FR">F</abbr>ridays <abbr class="dtstart" | |||
title="1206Z1000">10:00</abbr>-<abbr class="dtstart" | |||
title="0409Z1100">11:00</abbr></div> | |||
</span> | |||
</nowiki></pre> | |||
:No, because "every" is not an abbreviation of "weekly"; that's an abuse of <code>abbr</code>. If "byday" is not case-sensitive, you could mark up the first two letters of "Friday" with a span (but what if the page was in French or Chinese?). You also have 2x <code>dtstart</code>. [[User:AndyMabbett|Andy Mabbett]] 09:47, 22 Feb 2008 (PST) | |||
=== use value class pattern === | |||
In any updates/additions to the iCalendar examples translated to hCalendar, make use of the [[value class pattern]] where it's use will improve accessibility. | |||
== inclusive dtend == | |||
Now resolved per the [[dtend-issue]]. dtends are now inclusive. The remainder of the section is being kept purely for historical purposes. | |||
As documented in [[hcalendar-issues]], in practice (e.g. http://barcamp.org ) it appears all too often (thus easy) to make the mistake of assuming a dtend date value is inclusive, and thus the last day of many events is left off. I am proposing a solution (which is a variant of the enddate suggestion which was made for a second version of hCalendar) in an attempt to help this move forward. [[User:Tantek|Tantek]] 07:46, 1 Sep 2008 (PDT) | |||
Abandoned <span id="dtlast">dtlast</span> brainstorm: | |||
In short, introduce the syntactic sugar "dtlast", which treats date values as *inclusive* for the last day of an event. Thus you would markup the last day of an event with "dtlast" - this use of the word "last" in the property name helps provide an easy mnemonic/reminder that it is inclusive. The prefix "dt" is simply a [[naming-convention]] used to indicate that the property is a datetime value. | |||
dtlast is NOT a new property. Rather, semantically "dtlast" is merely treated by parsers as an override for any "dtend" property setting on that hCalendar event, with the aforementioned slight difference in handling. Thus "dtlast" does not exist in any object model etc. - it is merely author shorthand for indicating an inclusive end date. | |||
That is the two are semantically equivalent: | |||
<code><nowiki><abbr class="dtend" title="2008-09-08">September 7th, 2008</abbr></nowiki></code> | |||
and <span id="previous_enddate_suggestion">previous enddate suggestion</span> | |||
<code><nowiki><abbr class="dtlast" title="2008-09-07">September 7th, 2008</abbr></nowiki></code> | |||
Note that this enables dtlast to be written up with a single internationally human readable value: | |||
<code><nowiki><span class="dtlast">2008-09-07</span></nowiki></code> | |||
Similarly, when generating hCalendar markup from iCalendar or from a database, markup generators may publish "dtlast" for an end day (when time is not provided). | |||
Abandoned <span id="previous_enddate_suggestion">previous enddate suggestion</span>. | |||
If ever there is an "hCalendar 2" standard, thought should be given to changing the way dtend is handled, where no hour is specified. Currently, we use: | |||
:<code><nowiki><abbr class="dtend" title="2007-02-01">31 January 2007</abbr></nowiki></code> | |||
which is counter-intuitive for publishers (as past evidence on [[hcalendar-examples-in-wild|examples in the wild]] and elsewhere [http://rbach.priv.at/Microformats-IRC/2007-03-29#T183612] has shown). In the interests of ''ease of authoring'', we should consider, perhaps with a new property name for clarity, using: | |||
:<code><nowiki><abbr class="enddate" title="2007-01-31">31 January 2007</abbr></nowiki></code> | |||
and making ''parsers'' responsible for converting to "2007-02-01" when exporting as iCalendar. [[User:AndyMabbett|Andy Mabbett]] 05:28, 29 Mar 2007 (PDT) | |||
Previously was also known as <span id="Simplification_of_date-end">Simplification of date-end</span>. | |||
== implied dtend == | |||
Per [[value-class-pattern#hCalendar_dtend_implied_date]], hCalendar 1.1 should permit implied dtend dates from the dtstart. | |||
== CSS Styles == | == CSS Styles == | ||
Line 462: | Line 652: | ||
This data will be found by any transforming application and will be properly encoded into an iCal file. | This data will be found by any transforming application and will be properly encoded into an iCal file. | ||
'''You SHOULD NOT do this because it violates the visibility | '''You SHOULD NOT do this because it violates the visibility principle.''' | ||
=== abbr dedotting === | |||
Some browsers (e.g. [[Firefox]]) have a browser default style sheet that puts a dotted border underneath <code>abbr</code> elements (appears like a dotted underline). Since hCalendar often uses abbr for abbreviating dates and or times, it i useful to include the following style rule to remove the dotted underline visual noise: | |||
<source lang=css> | |||
abbr {border:0} | |||
</source> | |||
== hCalendar for timelines == | == hCalendar for timelines == | ||
There have been some interesting discussions about how to use [[hcalendar|hCalendar]] for marking up timelines. | There have been some interesting discussions about how to use [[hcalendar|hCalendar]] for marking up timelines. Here are some pointers: | ||
* [http://www.foundhistory.org/2006/05/05/calendars-as-timelines/ Calendars as Timelines] | * [http://www.foundhistory.org/2006/05/05/calendars-as-timelines/ Calendars as Timelines] | ||
* [http://heml.org/heml-cocoon/ The Historical Event Markup and Linking (HEML) Project] | * [http://heml.org/heml-cocoon/ The Historical Event Markup and Linking (HEML) Project] | ||
* [http://clioweb.org/archive/2006/05/04/css-based-timelines/ CSS-Based Timelines] | * [http://v1.clioweb.org/archive/2006/05/04/css-based-timelines/ CSS-Based Timelines] | ||
See also [[history-microformat]]. | |||
== Other use cases == | == Other use cases == | ||
Line 481: | Line 679: | ||
*Date-time stamp photographs, such as those on Flickr and Wikimedia Commons. | *Date-time stamp photographs, such as those on Flickr and Wikimedia Commons. | ||
*... | *... | ||
== Examples from real world event sites == | |||
''' These should be moved to [[event-examples]]''' with any pre-hCalendar markup noted therein. | |||
When they add hCalendar markup, copy them to [[hcalendar-examples-in-wild]]. | |||
=== W3C Meetings === | |||
I just got email announcing the dates of another W3C meeting. I don't think it's marked up with hCalendar. I could mark it up myself, like I did for [http://www.w3.org/2005/12/allgroupoverview.html the TP day/week schedule], but it might not stick. Somehow I got [http://www.w3.org/2000/08/w3c-synd/ our syndicated news markup] (precursor to [[hAtom]]) to stick, i.e. to become part of the norm in the W3C comm team. I wonder if I could pull that off for calendars. | |||
My first thought is authoring tools, but I don't think I can wait that long. | |||
Next thought is instant-feedback checking tools... | |||
X2V is really handy, but can't be used for confidential pages (and many/most calendars I use are not public). | |||
So.. how about some in-browser javascript "yes, you got it right!" or "hmm... that looks like a date; is there an event you didn't mark up?" feedback? I think I saw something like that in hCalendar implementations. | |||
[[User:DanC|DanC]] 09:00, 3 Feb 2006 (PST) | |||
=== Laughing Squid === | |||
Laughing Squid had the following [http://laughingsquid.com/squidlist/calendar/9584/2005/4/7 multiple occurrence event example]: | |||
Thu, Apr 7 : Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm | |||
In addition, later on in the description, it says: | |||
April 7-21, 2005 | |||
This is actually quite a non-trivial example, because the event lasts for different durations on different days (4 hours, 7 hours, 6 hours). | |||
Because of the differing durations, the specification requires that *each* instance of this recurring event be explicitly specified. | |||
But first we markup the starting date and time explicitly: | |||
<pre> | |||
<abbr class="dtstart" title="20050407T1200-0700">Thu, Apr 7</abbr> : | |||
</pre> | |||
Then we put in the quite lengthy explicit specification of every other time the event occurs, marked up around the human readable description. | |||
<pre> | |||
<abbr class="rdate" title="20050407T1200-0700/PT7H, 20050408T1200-0700/PT7H, | |||
20050409T1200-0700/PT7H, 20050410T1200-0700/PT6H, 20050412T1200-0700/PT4H, | |||
20050413T1200-0700/PT4H, 200504014T1200-0700/PT7H, 20050415T1200-0700/PT7H, | |||
20050416T1200-0700/PT7H, 20050417T1200-0700/PT6H, 20050419T1200-0700/PT4H, | |||
20050420T1200-0700/PT4H, 20050421T1200-0700/PT7H" > | |||
Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm | |||
</abbr> | |||
</pre> | |||
The RDATE "PERIOD" format is fairly straightforward. You simply list *each* occurrence of the event, separated by commas. Each occurrence consists of the ISO8601 datetime of the start of the event, followed by a slash "/", followed by *either* the duration of the event (e.g. 7 hours = PT7H), *or* a complete ISO8601 datetime of the end of the event. I chose to use the duration of the event for this example for reason of brevity. | |||
Note that "value=period:" is unnecessary in the rdate value since the parser can infer "value=period:" from the presence of a "/" in the title attribute value. | |||
With simpler repeating events, or perhaps events which only repeat a day or two, their hCalendar markup may be more illustrative of how to do this in a general way. | |||
=== Repeating Events === | |||
Examples of web pages that discuss or note repeating events which we should figure out how to mark-up in a reliable and accessible way with hCalendar: | |||
* https://wiki.mozilla.org/Platform#Meetings | |||
* https://wiki.mozilla.org/Webapi#Meetings | |||
* ... | |||
Note that repeating events present a user-conceptual-understanding challenge, and likely should be avoided in user interfaces, and thus formats. E.g. | |||
* http://forum.bodybuilding.com/showthread.php?t=107926751 - discussion (and confusion about) of whether every other day in a week is 3, 3.5, or 4 days. | |||
== Open Questions == | == Open Questions == | ||
''' These should be moved to [[hcalendar-issues]]'''. | |||
=== Undecided Encodings of Certain Property Attributes === | === Undecided Encodings of Certain Property Attributes === | ||
There are several attributes that still need to be discussed about how to property encode them into HTML. | There are several attributes that still need to be discussed about how to property encode them into HTML. | ||
Line 503: | Line 764: | ||
=== General Questions === | === General Questions === | ||
'''These should be processed and move to either [[hcalendar-feedback]], [[hcalendar-issues]], or [[hcalendar-faq]].''' | |||
Q: Should Transforming applications purely extract the information and ignore validity? or should there be some checking, or should this be left to the importing application? (i.e. DTSTART;VALUE=DATE: This-Is-Not-a-proper-date) | Q: Should Transforming applications purely extract the information and ignore validity? or should there be some checking, or should this be left to the importing application? (i.e. DTSTART;VALUE=DATE: This-Is-Not-a-proper-date) | ||
Line 526: | Line 789: | ||
Q: Should the transforming application add any additional information to the iCalendar representation other than what was encoded in the HTML? (i.e. UID, the unique identifier might not be present in the HTML code, but could be generated by the transforming application and added to the iCal file. Should this be allowed? or should the transforming app ONLY be allowed to add X-PROPERTY properties?) IF it was not explicitly encoded in the HTML should it be left out? What about default values? | Q: Should the transforming application add any additional information to the iCalendar representation other than what was encoded in the HTML? (i.e. UID, the unique identifier might not be present in the HTML code, but could be generated by the transforming application and added to the iCal file. Should this be allowed? or should the transforming app ONLY be allowed to add X-PROPERTY properties?) IF it was not explicitly encoded in the HTML should it be left out? What about default values? | ||
Q: If we are looking at the most semantic way to encoding iCalendar data in HTML then several other attributes should be considered besides just 'class'. There are two other candidated, ID and REL. The ID tag MUST be unique within the XHTML file (this could be used for the UID property). The REL attribute can ONLY be applied to 'a' and 'link' tags, but might be helpful. Are | Q: If we are looking at the most semantic way to encoding iCalendar data in HTML then several other attributes should be considered besides just 'class'. There are two other candidated, ID and REL. The ID tag MUST be unique within the XHTML file (this could be used for the UID property). The REL attribute can ONLY be applied to 'a' and 'link' tags, but might be helpful. Are namespaces an option? xml:lang, xml:base, are there any others that might be more semantically correct to encode this data? | ||
Q: To help distinguish xparam values from other actual CSS styles, should we assume/mandate that all values in a class attribute within an encoded iCal component class attribute (<x class="vevent|vtodo|...">) be considered an xparam? | Q: To help distinguish xparam values from other actual CSS styles, should we assume/mandate that all values in a class attribute within an encoded iCal component class attribute (<x class="vevent|vtodo|...">) be considered an xparam? | ||
Line 544: | Line 807: | ||
</nowiki></pre> | </nowiki></pre> | ||
=== Recurring Events === | === Recurring Events === | ||
Line 634: | Line 870: | ||
A simple implementation of transforming/extracting vCal data from an XHTML file is available for testing. A bookmarklet is also available. The code will be updated as the spec is finalised. | A simple implementation of transforming/extracting vCal data from an XHTML file is available for testing. A bookmarklet is also available. The code will be updated as the spec is finalised. | ||
http://suda.co.uk/projects/X2V/ . You may also use http://feeds.technorati.com/events/ for parsing hCalendar events and returning an iCalendar stream. | http://suda.co.uk/projects/X2V/ . You may also use http://feeds.technorati.com/events/ for parsing hCalendar events and returning an iCalendar stream. | ||
=== Parsing === | === Parsing === | ||
Line 810: | Line 1,045: | ||
Perhaps with some way of figuring out who the to-do item is assigned to ("ATTENDEE"), who assigned it ("DELEGATED-FROM"), and a whitelisting of who, perhaps the "ORGANIZER" property, (and their domains/URLs) that a user would accept assignments from, a user could aggregate to-do items assigned from other folks. Then question remains how to update the status ("STATUS") (RFC 2445 4.8.1.11 Status) on that to-do item when it is (a) completed ("COMPLETED"), (b) abandoned/cut/rejected ("CANCELLED"), (c) some progress is made ("IN-PROCESS") etc. There certainly seems to be sufficient expressiveness in VTODO and its properties to do a decentralized to-do list / task distribution system. Could be very interesting for helping open source projects and other distributed teams do project management using the Web. | Perhaps with some way of figuring out who the to-do item is assigned to ("ATTENDEE"), who assigned it ("DELEGATED-FROM"), and a whitelisting of who, perhaps the "ORGANIZER" property, (and their domains/URLs) that a user would accept assignments from, a user could aggregate to-do items assigned from other folks. Then question remains how to update the status ("STATUS") (RFC 2445 4.8.1.11 Status) on that to-do item when it is (a) completed ("COMPLETED"), (b) abandoned/cut/rejected ("CANCELLED"), (c) some progress is made ("IN-PROCESS") etc. There certainly seems to be sufficient expressiveness in VTODO and its properties to do a decentralized to-do list / task distribution system. Could be very interesting for helping open source projects and other distributed teams do project management using the Web. | ||
== Non-Gregorian Calendars == | |||
=== Japanese Calendar === | |||
* [http://home.yomiuri.co.jp/wnews/20080711hg03.htm yomiuri] - newspaper | |||
* [http://urakoma.com/bbs.html urakoma.com] - form input | |||
=== Umm al-Qura (Saudi Arabia) Calendar === | |||
* [http://www.sama.gov.sa/ Sama] - Government site | |||
== TobyInk hCalendar revision == | |||
[[User:TobyInk]] has put together a [[User:TobyInk/hcalendar-1.1|draft revised hCalendar spec]] using ideas from this brainstorming page, and expanding the spec to cover todo items, freebusy and alarms. Recurrences are documented, as are nested hCards, nested hCalendar items and attachments (using [[rel-enclosure]]). | |||
* Expanding the spec to cover more items is a bad idea at this point outside of the [[process]]. In addition, any other changes should either come from resolution of [[hcalendar-issues]] or very well documented brainstorming items that are justified very well - if you know of any issues, add them to [[hcalendar-issues]] rather than assuming them and writing them into a spec (iteration). As editor of hCalendar, I think the next logical thing to do is to produce an iteration that takes into account resolved issues, and that's what I've listed as part of my plan on my [[to-do]] list. [[User:Tantek|Tantek]] 07:46, 1 Sep 2008 (PDT) | |||
** The hCalendar 1.1 draft does not attempt to add anything new to hCalendar (with the exception of [[User:TobyInk/hcalendar-1.1#VTODO_List_XOXO_Minimization|VTODO lists]], which is effectively an optimisation for quick and easy todo lists rather than proper extension). The hCalendar 1.0 spec is already ''"a 1:1 representation of the aforementioned iCalendar standard, in semantic HTML"'' — implying that all properties in iCalendar are allowed in hCalendar. The 1.1 draft merely ''documents the usage'' of some of the more esoteric properties in iCalendar and how they may be mapped to (X)HTML. (In fact, if anything it ''shrinks'' hCalendar rather than expands it, as it says that the VJOURNAL and VTIMEZONE components of iCalendar are not supported.) [[User:TobyInk|TobyInk]] 09:22, 1 Sep 2008 (PDT) | |||
** As it happens, the hCalendar 1.1 draft also acts as rough documentation of how hCalendar is supported in [http://buzzword.org.uk/cognition/ Cognition]. Although Cognition's implementation may vary from the draft in place to place, it is fairly close, and ultimately aims to implement the draft exactly (by improvements to Cognition rather than regressions in the spec!!) This may be useful for other parser programmers wishing to provide a roughly compatible implementation, and those looking for guidance on how to parse iCalendar features which are not covered by the official hCalendar spec. [[User:TobyInk|TobyInk]] 09:22, 1 Sep 2008 (PDT) | |||
== for hCalendar 1.1 == | |||
* Apply simplifications, fixes from | |||
** the above, and | |||
** [http://tools.ietf.org/html/rfc5545 RFC5545 iCal Basic], which drops a lot of the non-event related stuff. | |||
== for hCalendar 2 == | |||
* incorporate hCalendar 1.1 updates/changes into the [[microformats-2]] hCalendar vocabulary | |||
== References == | == References == | ||
Line 817: | Line 1,077: | ||
=== Informative References === | === Informative References === | ||
* [http://wiki.oreillynet.com/foocamp04/index.cgi?HTMLForCalendars HTMLForCalendars (FOO camp)] - presented just a few days before this, hopefully these efforts can be | * [http://wiki.oreillynet.com/foocamp04/index.cgi?HTMLForCalendars HTMLForCalendars (FOO camp)] - presented just a few days before this, hopefully these efforts can be combined | ||
* [http://www.imc.org/pdi/ Personal Data Interchange (PDI) at the Internet Mail Consortium] | * [http://www.imc.org/pdi/ Personal Data Interchange (PDI) at the Internet Mail Consortium] | ||
Line 825: | Line 1,085: | ||
* [http://www.ietf.org/rfc/rfc2447.txt iMIP RFC2447] | * [http://www.ietf.org/rfc/rfc2447.txt iMIP RFC2447] | ||
* [http://www.ietf.org/rfc/rfc3283.txt Guide to Internet Calendaring RFC3283] | * [http://www.ietf.org/rfc/rfc3283.txt Guide to Internet Calendaring RFC3283] | ||
=== Authors === | |||
Authors of the original hCalendar brainstorming page on the Technorati wiki which was copied here with the launch of microformats.org 2005-06-20: | |||
* [http://suda.co.uk/ Brian Suda] ([[User:Brian]]) | |||
* [http://tantek.com/log/ Tantek Çelik] ([[User:Tantek]]) | |||
Authors since 2005-06-20 are reflected by this wiki page's history. | |||
== Other Implementations/Ideas == | == Other Implementations/Ideas == | ||
Line 834: | Line 1,100: | ||
== Blogs About Calendaring == | == Blogs About Calendaring == | ||
* http://staff.washington.edu/oren/weblog2/ | * http://staff.washington.edu/oren/weblog2/ | ||
== Related Pages == | == Related Pages == | ||
{{hcalendar-related-pages}} | {{hcalendar-related-pages}} |
Latest revision as of 16:24, 18 July 2020
- this page could use just a bit more clean-up and reorganization. - Tantek
- create "for hCalendar 1.0.1" and "for hCalendar 1.1" sections similar to the for hCard 1.0.1 and 1.1 sections in hCard brainstorming
- and start considering/sorting hCalendar brainstorming proposals for 1.0.1 and 1.1
- update HTML source code examples to use "<source lang=html4strict>" feature of wiki2.
- update iCalendar source code examples to use "<source lang=text>"
This page is for trying out and documenting ways of using hCalendar which may involve more details than currently in the specification.
If you have a question, please check the hCalendar FAQ, and ask new questions on the mailing lists first.
hCalendar authoring best practices
Tabular event calendars
Many calendars are posted in tabular form, where the headings on the columns and rows have property values that apply to the cells which themselves are events. E.g. many conferences have multiple tracks and post names of rooms (LOCATION) as column headers, and time slots (DTSTART, DTEND) as row headers.
Here is a description of how to parse such markup into an iCalendar stream. This has been implemented in X2V and deployed.
TO DO: document a "How To" for publishers looking to mark up tabular event listings.
To enable mark these up with hCalendar, we must parse additional semantic attributes from HTML4.
When parsing, in addition to the special case rules documented in hcard-parsing:
- If the element is a table data cell
<td>
, then:- parse its "headers" attribute as a space separated set of local IDs
- find the
<td>
and<th>
elements referenced by those IDs (call them header cells) and consider them part of the element being parsed as follows:- Treat the header cells as children of the element, ordered by the order of ids in its "headers" attribute, immediately following the last child node (text or element) of the element. (The basic idea is that the content from those header cells is used to construct the VEVENT, but secondary to (AFTER) the content in the data cell itself, so that the data cell can customize/override part of the data in the header, e.g. if the header cell included both start time and location, and the event was being held at a different location).
Real world example in the wild of a tabular event calendar marked up in this fashion:
- See hCalendar examples in the wild: conference schedules.
- Web Essentials 05 Session program (was at http://we05.com/program.cfm but that link went bad sometime in 2006-2007).
Note: We have gained sufficient experience with this that we should formalize this in both hcard-parsing and hcalendar-parsing since the table cell headers technique is generic to all class name microformats. The specific use case of how to author a tabular display of events should be documented in hcalendar-authoring. Tantek
rejected use of axis for more class names
The following step (which used to be #2 above after the "Treat the header cells..." step has been removed:
- 2. Parse the "axis" attribute of a header cell as a comma-separated list of categories. These categories must be used in addition to (and before) any class names on that header cell for determining whether it is a property of the VEVENT.
Reasons for removal:
- The axis attribute is for a human readable label / category, not a class name and thus this would be incorrect usage of the axis attribute.
- No real world tabular event calendar example has ever needed the axis attribute for hCalendar parsing.
- No implementation of tabular event calendar parsing has ever bothered to implement axis parsing (probably due to the lack of any real world examples that needed it).
- This is not the case. It has been implemented by Cognition.
hCard locations
In iCalendar (and thus hCalendar), the LOCATION property is just a text string. In practice however, much event content contains some amount of structure for the location, often a specific venue with name, address etc. Venues are often organizations and are thus conducive to being marked up as hCards.
Taking the example from the hCalendar spec:
<span class="vevent"> <a class="url" href="http://www.web2con.com/"> <span class="summary">Web 2.0 Conference</span>: <abbr class="dtstart" title="2005-10-05">October 5</abbr>- <abbr class="dtend" title="2005-10-08">7</abbr>, at the <span class="location">Argent Hotel, San Francisco, CA</span> </a> </span>
Clearly the "Argent Hotel" is a venue, and thus could be marked up as an hCard itself:
<span class="location vcard"> <span class="fn org">Argent Hotel</span>, <span class="adr"><span class="locality">San Francisco</span>, <span class="region">CA</span></span> </span>
Thus in the context of the entire vevent this example would become:
<span class="vevent"> <a class="url" href="http://www.web2con.com/"> <span class="summary">Web 2.0 Conference</span>: <abbr class="dtstart" title="2005-10-05">October 5</abbr>- <abbr class="dtend" title="2005-10-08">7</abbr>, at the <span class="location vcard"> <span class="fn org">Argent Hotel</span>, <span class="adr"><span class="locality">San Francisco</span>, <span class="region">CA</span></span> </span> </a> </span>
The advantage of marking up the location with explicit hCard semantics is that it enables much better identification and pivoting of locations of events.
For a real world example of this in practice see Jeremy Keith's excellent SXSW 2006 event page: http://austin.adactio.com/ where all the events contain locations marked up as hCards with geo properties as well which then aid in locating the precise locations on a map.
Note: We have gained sufficient experience with this that we should formalize this in hcalendar-authoring. Tantek
hCard attendees
In regards to representing RFC2445 4.8.4.1 Attendee (ATTENDEE property), and RFC2445 4.2.16 Participation Role (ROLE type), using a real world example to develop a brainstorm proposal for how to use the respective hCalendar attendee
property and role
subproperty.
Many online events (e.g. at http://upcoming.org/) indicate who is attending an event, and in fact, who is just "watching" as well in this case. Whereas RFC2445 says to use a "calendar address" (essentially an email address) for the "ATTENDEE" property, it has just enough hooks to make an hCard work instead (DIR for URL to the contact info etc.). Thus hCalendar attendees should be marked up with hCard so that the full semantics are conveyed.
Inside an hCalendar event:
<span class="attendee vcard">
<a class="url uid fn" href="http://example.org/u/1337">
<img class="logo" src="http://example.org/u/1337icon.jpg">
Carla Brown
</a>
</span>
But this is insufficient, as the ATTENDEE in iCalendar by itself implies nothing more than the person being an invitee since the default participation status (PARTSTAT attribute - see below) is "needs-action".
participation status
There is the 4.2.12 Participation Status (PARTSTAT attribute) of the ATTENDEE property, which can be used to indicate:
- "NEEDS-ACTION" ; Event needs action (DEFAULT)
- "ACCEPTED" ; Event accepted
- "DECLINED" ; Event declined
- "TENTATIVE" ; Event tentatively accepted
- "DELEGATED" ; Event delegated
Common event user interfaces have the following shared visible semantics which can be represented using the above PARTSTAT values:
common semantic | Upcoming.org | Evite.com | Socializr.com | Crush3r.com | pingg.com | partstat
|
---|---|---|---|---|---|---|
RSVP unknown/unreplied | NOT YET REPLIED | Not responded | undecided | needs-action
| ||
RSVP No | No | No | impossible / raincheck / not likely | no | declined
| |
RSVP Maybe | Interested | Maybe / I Can't Decide | play it by ear / will try to | maybe | tentative
| |
RSVP Yes | Going | Yes | Yes | yes i plan to / count me in / will be early | yes | accepted
|
Thus taking the above example, someone who has RSVP'd yes could/should be marked up with the PARTSTAT ACCEPTED value in order to distinguish them from the default, which is that someone is just an invitee, since the default for PARTSTAT is NEEDS-ACTION.
<span class="attendee vcard">
<a class="url uid fn" href="http://example.org/u/1337">
<img class="logo" src="http://example.org/u/1337icon.jpg">
Carla Brown
</a>
(<span class="partstat"><span class="value-title" title="accepted">attending</span></span>)
</span>
Someone who is simply "watching" or "interested" in an event can be marked up as following:
<span class="attendee vcard">
<a class="url uid fn" href="http://example.org/u/2600">
<img class="logo" src="http://example.org/u/2600icon.jpg">
Michael Payne
</a>
(<span class="partstat"><span class="value-title" title="tentative">interested</span></span>)
</span>
</span>
However, if "tentative" is too strong of a semantic, then see below for using ROLE property which can be used to indicate non-participation.
role non-participant
For watching, ROLE=NON-PARTICIPANT
is the closest semantic in iCalendar RFC2445 - "NON-PARTICIPANT" is defined as "Indicates a participant who is copied for information purposes only" which sounds like "watching" to me.
<span class="attendee vcard">
<a class="url uid fn" href="http://example.org/u/2600">
<img class="logo" src="http://example.org/u/2600icon.jpg">
Michael Payne
</a>
<span class="role"><span class="value-title" title="non-participant">(watching)</span>
</span>
</span>
Note: the <span class="role"><span class="value-title" title="non-participant"> </span></span> uses the value-class-pattern because we want to use the enumerated value of "non-participant" while indicating that information with the text "(watching)" in the UI. This isn't ideal, but it's currently the best of several alternatives taking into consideration proper use of semantic HTML (avoiding improper use), accessibility, and (expected) site presentation design. Note that the "non-participant" value is *right next to* the text that says "watching" which reduces the risk that the two versions of the same piece of data will get out of sync.
This markup technique can be applied to real-world hCalendar markup, e.g. for http://upcoming.org/event/152831/
for the <span>s that follow the "Attending" heading on that page
<span class="attendee vcard">
<a class="dynavatar_link" href="http://upcoming.org/user/48265/" id="user_48265" >
<img class="avatar logo" src="http://static.flickr.com/45/buddyicons/86708053%40N00.jpg" id="image_cbe16d4252b4b1aab58c787379d130f552994da2" align="" valign="" height="12" width="12" border="0" style="padding: 2px;" />
</a>
<a class="uid url nickname" href="http://upcoming.org/user/48265/" id="user_48265" title="Attending since Feb 15, 2007 02:15 PM" >
CPERIN</a>
</span>
and for the <span>s that follow the WATCHING heading
<span class="attendee vcard">
<a class="dynavatar_link" href="http://upcoming.org/user/29960/" id="user_29960">
<img class="avatar logo" src="http://static.flickr.com/16/buddyicons/39472722%40N00.jpg" id="image_2980a4eb9e608adc0341b318dfea501c5fed6621" align="" valign="" height="12" width="12" border="0" style="padding: 2px;" />
</a>
<a class="uid url nickname" href="http://upcoming.org/user/29960/" id="user_29960" title="Watching since Feb 15, 2007 02:26 PM">
cee-dub</a>
<span class="role"><span class="value-title" title="non-participant"> </span></span>
</span>
Originally proposed/documented by Tantek 19:34, 23 Feb 2007 (PST). Updated to use more readable code markup and value-class-pattern instead of abbr by Tantek 23:04, 13 May 2009 (UTC) .
Role property overlap
Both vCard and iCalendar contain the term ROLE. Their definitions are similar enough to consider collapsing.
Therefore the following is proposed:
- The hCard "role" property and the hCalendar "role" subproperty of the "attendee" (and any other applicable) property are considered equivalent. This is essentially an explicit declaration of the status quo and clarification in the context of the above proposal to use hCard to mark up the details of an hCalendar event attendee.
- hCard consuming applications MAY ignore the following "role" property values, as such values most likely apply only to the context of an hCalendar event attendee, and probably do not indicate the role of the hCard in general. Values are shown in ALL CAPS per convention from RFC2445 but are case-insensitive per hCard/hCalendar conventions for enumerated property values.
CHAIR
REQ-PARTICIPANT
OPT-PARTICIPANT
NON-PARTICIPANT
- hCalendar authors MUST OMIT the role value "REQ-PARTICIPANT" for the hCard of an attendee of an hCalendar event, because:
- It is simpler/unnecessary - "REQ-PARTICIPANT" is the default value for the hCalendar "role" subproperty, and thus any conforming hCalendar consuming application would presume that value by default anyway for all "attendee" hCards.
- It will help avoid polluting existing hCard consuming applications.
- hCalendar consuming applications MUST IGNORE attendee role values that are outside the above list of four values.
hCard organizer
In regards to representing RFC2445 4.8.4.3 Organizer (ORGANIZER property), using a real world example to develop a brainstorm proposal for how to use the respective hCalendar organizer
property.
Many online events (e.g. at Eventbrite) indicate who is organizing or hosting an event. Whereas RFC2445 says to use a "calendar address" (essentially an email address) for the "ORGANIZER" property, it has just enough hooks to make an hCard work instead (CN for name of the contact, DIR for URL to the contact info etc.). Thus an hCalendar organizer should be marked up with hCard so that the full semantics are conveyed.
Inside an hCalendar event:
<span class="organizer vcard">
<a class="url uid fn" href="http://example.org/u/216">
<img class="logo" src="http://example.org/u/216icon.jpg">
John Smith
</a>
(<a class="email" href="mailto:jsmith@example.org">jsmith@example.org</a>)
</span>
hCalendar to iCalendar processors should parse the embedded hCard and convert the fields accordingly when converting to iCalendar:
- hCard "fn" to ORGANIZER CN
- hCard "url uid" to ORGANIZER DIR
- hCard "email" to ORGANIZER MAILTO
- hCard "agent" "url uid" to ORGANIZER SENT-BY
E.g. the example organizer hCard above would be converted to the following iCalendar:
ORGANIZER;CN=John Smith;DIR="http://example.org/u/216":MAILTO:jsmith@example.org
Photos and other attachments
To associate a photo or other chunk of content/media (movie, podcast, agenda document, etc.) with an event, use the ATTACH property (defined in RFC2445 section 4.8.1.1 Attachment), e.g. (whitespace added for readabilty)
<span class="vevent"> <abbr class="dtstart" title="20070215T1900-0800">15 February 2007</abbr>: <span class="summary">Futurist meetup event</span> to discuss <a href="http://www.flickr.com/photos/tantek/411545406/"> <img src="http://farm1.static.flickr.com/183/411545406_c73ca4e613_t.jpg" class="attach" alt="The Wheel of Time" /> </a> </span>
To explicitly indicate the content type of the image, you can instead use the object tag:
<span class="vevent"> <abbr class="dtstart" title="20070215T1900-0800">15 February 2007</abbr>: <span class="summary">Futurist meetup event</span> to discuss <a href="http://www.flickr.com/photos/tantek/411545406/"> <object data="http://farm1.static.flickr.com/183/411545406_c73ca4e613_t.jpg" class="attach" type="image/jpeg"> The Wheel of Time</object> </a> </span>
This event might be displayed as:
15 February 2007: Futurist meetup event to discuss
Note: the above example with object tag should be equivalent to the following iCalendar snippet (BEGIN/END:VCALENDAR omitted):
BEGIN:VEVENT DTSTART:20070215T1900-0800 SUMMARY:Futurist meetup event ATTACH;FMTYPE=image/jpeg:http://farm1.static.flickr.com/183/411545406_c73ca4e613_t.jpg END:VEVENT
Cardinality
The ATTACH property can appear more than once. Though section 4.8.1.1, which defines ATTACH doesn't state how often ATTACH can appear, section 3.5 clearly indicates that the authors intended multiple attachments:
ATTACHMENTS - - An iCalendar object can include references to Uniform Resource Locators that can be programmed resources.
event badges buttons
Events often have small graphics (badges or buttons) which are used to encourage other sites for promotional purposes.
An hCalendar event can mark up its badge(s) with the "attach" property. Secondary sites that syndicate and republish such events could then automatically retrieve such attachments and use them in the visual appearance of the republication of such events.
update for value class pattern
Update all hCalendar examples to make use of the value class pattern where such use would improve accessibility.
how to use with HTML5
Per Theresa O'Connor's email to public-html: Add a section in hCalendar 1.0.1 describing how to use hCalendar in HTML5, including optional use of HTML5's <time> element and/or microdata feature(s). Encourage HTML5 to drop the "vevent" predefined microdata vocabulary and reference the updated hCalendar 1.0.1 spec instead. Tantek
iCalendar generation best practices
Along with the four base properties, you can define addtional properties through the use of the x-prop property. For best-practices for hCal to iCal transformers, it would be helpful if the transforming application added the following x-* properties:
X-FROM-URL
- X-FROM-URL. The value of this property would be the URL of the page where the iCal representation was generated.
X-FROM-URL:http://example.com/page-containing-hCal-encoding.html
Note: We have gained sufficient experience with this that we should formalize this in hcalendar-parsing. Tantek
X-WR-CALNAME
- X-WR-CALNAME. iCal.app recognizes this property as the "calendar name" for subscribed calendars. Thus transforming applications *should* take the
<title>...</title>
from the page being parsed, optionally append " events", and use that value for the X-WR-CALNAME property in the resulting feed. E.g. if the page had<title>Example Home Page</title>
then the .ics output should have as part of the vcalendar object:
X-WR-CALNAME:Example Home Page
Note: We have gained sufficient experience with this that we should formalize this in hcalendar-parsing. Tantek
- This doesn't seem like a good solution for the case when multiple hCalendars are published on a single HTML page. TobyInk 09:56, 4 Mar 2008 (PST)
iCalendar examples in hCalendar
This is a growing example case written in iCal format and transformed to the corresponding XHTML. These conversions are open to community input. See hcalendar-examples for current work.
BEGIN:VEVENT CATEGORIES:foo,bar SUMMARY: Short Title DESCRIPTION: Full Description DTSTART;VALUE=DATE:20040101 DTEND:20040101T235959Z RRULE:FREQ=YEARLY;UNTIL=20080102T000000Z URL;WORK:http://example.com ATTENDEE;ROLE=CHAIR:MAILTO:JohnDoe@example.com GEO:37.386013;-122.082932 END:VEVENT
<p class="vevent"> <!-- @@ how to deal with Whitespace issues in lists 'foo, bar' --> Categories: <ul class="categories"> <li>foo</li> <li>bar</li> </ul> <a href="http://example.com" class="summary">Short Title</a> <span class="description">description</span> <span class="geo"><span class="Lat">37.386013</span> <span class="Lon">-122.082932</span></span> <!-- This currently does not take into consideration the VALUE=DATE --> <!-- The transforming application could attempt to detect the proper format and add params as needed? --> Date: <em class="dtstart">20040101</em> - <em class="dtend">20040101T235959Z</em> <!-- any thoughts to better encode attendee --> <!-- the ROLE must be of a known type, but one of type is x-name (user-specified) --> <!-- therefore there is no solid way to know "chair" refers to a ROLE parameter --> <a class="attendee chair" href="mailto:JohnDoe@example.com">John Doe</a> <!-- this messy, but works. Is there a better way? --> <p class="rrule">The event will be held <span class="freq">yearly</span> until <span class=""until">20080102T000000Z</span>.</p> </p>
@@-need to look at nested tag examples
XHTML <span class="description"><span class="summary">Short Title</span> to a longer article</span> vCal SUMMARY:Short Title DESCRIPTION:Short Title to a longer article
Examples from RFC 2445
- These examples are now all available on hcalendar-examples.
With the abbr's title attribute being used rather than the node value, the actual data could vary and still represent the same vcalendar.
BEGIN:VCALENDAR VERSION:2.0 PRODID:-//hacksw/handcal//NONSGML v1.0//EN BEGIN:VEVENT DTSTART:19970714T170000Z DTEND:19970715T035959Z SUMMARY:Bastille Day Party END:VEVENT END:VCALENDAR
<span class="vcalendar"> <span class="vevent"> <abbr class="dtstart" title="19970714T170000Z">July 14th</abbr> <abbr class="dtend" title="19970715T035959Z"></abbr> <span class="summary">Bastille Day Party</span> </span> </span>
UID handling
The UID in iCal is represented in HTML as the id attribute in these examples. Any valid id in HTML is a valid UID in iCal, but not the contrapositive, a valid UID is NOT a valid HTML id. HTML ids can only start with a letter, not a number.
BEGIN:VEVENT UID:19970901T130000Z-123401@host.com DTSTAMP:19970901T1300Z DTSTART:19970903T163000Z DTEND:19970903T190000Z SUMMARY:Annual Employee Review CLASS:PRIVATE CATEGORIES:BUSINESS,HUMAN RESOURCES END:VEVENT
<span class="vcalendar"> <span class="vevent" id="19970901T130000Z-123402@host.com"> <abbr class="dtstamp" title="19970901T1300Z"></abbr> <abbr class="dtstart" title="19970903T163000Z">September 3rd, 4:30pm</abbr>- <abbr class="dtend" title="19970903T190000Z">7:00pm</abbr> <span class="summary">Annual Employee Review</span> <span class="class">private</span> <ul class="categories"> <li>BUSINESS</li> <li>HUMAN RESOURCES</li> </ul> </span> </span>
BEGIN:VCALENDAR BEGIN:VEVENT UID:19970901T130000Z-123402@host.com DTSTAMP:19970901T1300Z DTSTART:19970401T163000Z DTEND:19970402T010000Z SUMMARY:Laurel is in sensitivity awareness class. CLASS:PUBLIC CATEGORIES:BUSINESS,HUMAN RESOURCES TRANSP:TRANSPARENT END:VEVENT END:VCALENDAR
<span class="vcalendar"> <span class="vevent" id="19970901T130000Z-123402@host.com"> <abbr class="dtstamp" title="19970901T1300Z"></abbr> <abbr class="dtstart" title="19970401T163000Z">April 1st 4:30pm</abbr>- <abbr class="dtend" title="19970402T010000Z">1:00am</abbr> <span class="summary">Laurel is in sensitivity awareness class.</span> <span class="class">PUBLIC</span> <ul class="categories"> <li>BUSINESS</li> <li>HUMAN RESOURCES</li> </ul> <span class="transp">Transparent</span> </span> </span>
RRULE handling
The way RRULE is encoded should be discussed.
BEGIN:VEVENT UID:19970901T130000Z-123403@host.com DTSTAMP:19970901T1300Z DTSTART:19971102 SUMMARY:Our Blissful Anniversary CLASS:CONFIDENTIAL CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION RRULE:FREQ=YEARLY END:VEVENT
<span class="vcalendar"> <span class="vevent" id="19970901T130000Z-123403@host.com"> <abbr class="dtstart" title="19970901T1300Z"></abbr> <abbr class="dtend" title="19971102">November 2nd</abbr> <span class="summary">Our Blissful Anniversary</span> <span class="class">CONFIDENTIAL</span> <ul class="categories"> <li>ANNIVERSARY</li> <li>PERSONAL</li> <li>SPECIAL OCCASION</li> </ul> <span class="rrule"><span class="freq">YEARLY</span></span> </span> </span>
Is this how re-occuring weekly events (basically, my class teaching list) should be done? Note the use of DTEND and DTSTART to mark ending and starting times for the semester. Using markup from Harry Halpin's homepage http://www.ibiblio.org/hhalpin.
<span class="vevent"> <div class="rrule"><a href="http://www.inf.ed.ac.uk/teaching/courses/2007/lsi.html">Language Semantics and Implementation</a> meet at DHT 7.18 <abbr class="freq" title="weekly">every</abbr> <abbr class="BYDAY" title="FR">F</abbr>ridays <abbr class="dtstart" title="1206Z1000">10:00</abbr>-<abbr class="dtstart" title="0409Z1100">11:00</abbr></div> </span>
- No, because "every" is not an abbreviation of "weekly"; that's an abuse of
abbr
. If "byday" is not case-sensitive, you could mark up the first two letters of "Friday" with a span (but what if the page was in French or Chinese?). You also have 2xdtstart
. Andy Mabbett 09:47, 22 Feb 2008 (PST)
use value class pattern
In any updates/additions to the iCalendar examples translated to hCalendar, make use of the value class pattern where it's use will improve accessibility.
inclusive dtend
Now resolved per the dtend-issue. dtends are now inclusive. The remainder of the section is being kept purely for historical purposes.
As documented in hcalendar-issues, in practice (e.g. http://barcamp.org ) it appears all too often (thus easy) to make the mistake of assuming a dtend date value is inclusive, and thus the last day of many events is left off. I am proposing a solution (which is a variant of the enddate suggestion which was made for a second version of hCalendar) in an attempt to help this move forward. Tantek 07:46, 1 Sep 2008 (PDT)
Abandoned dtlast brainstorm:
In short, introduce the syntactic sugar "dtlast", which treats date values as *inclusive* for the last day of an event. Thus you would markup the last day of an event with "dtlast" - this use of the word "last" in the property name helps provide an easy mnemonic/reminder that it is inclusive. The prefix "dt" is simply a naming-convention used to indicate that the property is a datetime value.
dtlast is NOT a new property. Rather, semantically "dtlast" is merely treated by parsers as an override for any "dtend" property setting on that hCalendar event, with the aforementioned slight difference in handling. Thus "dtlast" does not exist in any object model etc. - it is merely author shorthand for indicating an inclusive end date.
That is the two are semantically equivalent:
<abbr class="dtend" title="2008-09-08">September 7th, 2008</abbr>
and previous enddate suggestion
<abbr class="dtlast" title="2008-09-07">September 7th, 2008</abbr>
Note that this enables dtlast to be written up with a single internationally human readable value:
<span class="dtlast">2008-09-07</span>
Similarly, when generating hCalendar markup from iCalendar or from a database, markup generators may publish "dtlast" for an end day (when time is not provided).
Abandoned previous enddate suggestion.
If ever there is an "hCalendar 2" standard, thought should be given to changing the way dtend is handled, where no hour is specified. Currently, we use:
<abbr class="dtend" title="2007-02-01">31 January 2007</abbr>
which is counter-intuitive for publishers (as past evidence on examples in the wild and elsewhere [1] has shown). In the interests of ease of authoring, we should consider, perhaps with a new property name for clarity, using:
<abbr class="enddate" title="2007-01-31">31 January 2007</abbr>
and making parsers responsible for converting to "2007-02-01" when exporting as iCalendar. Andy Mabbett 05:28, 29 Mar 2007 (PDT)
Previously was also known as Simplification of date-end.
implied dtend
Per value-class-pattern#hCalendar_dtend_implied_date, hCalendar 1.1 should permit implied dtend dates from the dtstart.
CSS Styles
Since the hCal properties are added in as HTML class names, you can style them with CSS class selectors along with other HTML class names. You are free to style these properties in any fashion you want (see specific notes), but here are a few examples that you can use.
Preserving White-space
If you are encoding data that requires tabs, returns, or other white-space to be perserved you can use the following CSS property to do so in HTML.
<span style="white-space: pre"> This white-space will be preserved </span>
white-space can take one of three different parameters; normal, pre, and no-wrap.
Not recommended
The following CSS styling techniques are not recommended:
Hiding Data
It is possible to encode additional data without it being displayed in the HTML, by using the CSS style property 'display'.
<span style="display:none">Hidden Data</span>
This data will be found by any transforming application and will be properly encoded into an iCal file.
You SHOULD NOT do this because it violates the visibility principle.
abbr dedotting
Some browsers (e.g. Firefox) have a browser default style sheet that puts a dotted border underneath abbr
elements (appears like a dotted underline). Since hCalendar often uses abbr for abbreviating dates and or times, it i useful to include the following style rule to remove the dotted underline visual noise:
abbr {border:0}
hCalendar for timelines
There have been some interesting discussions about how to use hCalendar for marking up timelines. Here are some pointers:
See also history-microformat.
Other use cases
Please add your suggestions!
hCalendar microformats could be used to:
- Sequence waypoints for a GPS "track" - see geo-waypoint-examples for details
- Mark up "last updated" dates on web pages (does anyone have examples of this being done already?).
- Date-time stamp photographs, such as those on Flickr and Wikimedia Commons.
- ...
Examples from real world event sites
These should be moved to event-examples with any pre-hCalendar markup noted therein.
When they add hCalendar markup, copy them to hcalendar-examples-in-wild.
W3C Meetings
I just got email announcing the dates of another W3C meeting. I don't think it's marked up with hCalendar. I could mark it up myself, like I did for the TP day/week schedule, but it might not stick. Somehow I got our syndicated news markup (precursor to hAtom) to stick, i.e. to become part of the norm in the W3C comm team. I wonder if I could pull that off for calendars.
My first thought is authoring tools, but I don't think I can wait that long. Next thought is instant-feedback checking tools... X2V is really handy, but can't be used for confidential pages (and many/most calendars I use are not public). So.. how about some in-browser javascript "yes, you got it right!" or "hmm... that looks like a date; is there an event you didn't mark up?" feedback? I think I saw something like that in hCalendar implementations.
DanC 09:00, 3 Feb 2006 (PST)
Laughing Squid
Laughing Squid had the following multiple occurrence event example:
Thu, Apr 7 : Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm
In addition, later on in the description, it says:
April 7-21, 2005
This is actually quite a non-trivial example, because the event lasts for different durations on different days (4 hours, 7 hours, 6 hours).
Because of the differing durations, the specification requires that *each* instance of this recurring event be explicitly specified.
But first we markup the starting date and time explicitly:
<abbr class="dtstart" title="20050407T1200-0700">Thu, Apr 7</abbr> :
Then we put in the quite lengthy explicit specification of every other time the event occurs, marked up around the human readable description.
<abbr class="rdate" title="20050407T1200-0700/PT7H, 20050408T1200-0700/PT7H, 20050409T1200-0700/PT7H, 20050410T1200-0700/PT6H, 20050412T1200-0700/PT4H, 20050413T1200-0700/PT4H, 200504014T1200-0700/PT7H, 20050415T1200-0700/PT7H, 20050416T1200-0700/PT7H, 20050417T1200-0700/PT6H, 20050419T1200-0700/PT4H, 20050420T1200-0700/PT4H, 20050421T1200-0700/PT7H" > Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm </abbr>
The RDATE "PERIOD" format is fairly straightforward. You simply list *each* occurrence of the event, separated by commas. Each occurrence consists of the ISO8601 datetime of the start of the event, followed by a slash "/", followed by *either* the duration of the event (e.g. 7 hours = PT7H), *or* a complete ISO8601 datetime of the end of the event. I chose to use the duration of the event for this example for reason of brevity.
Note that "value=period:" is unnecessary in the rdate value since the parser can infer "value=period:" from the presence of a "/" in the title attribute value.
With simpler repeating events, or perhaps events which only repeat a day or two, their hCalendar markup may be more illustrative of how to do this in a general way.
Repeating Events
Examples of web pages that discuss or note repeating events which we should figure out how to mark-up in a reliable and accessible way with hCalendar:
Note that repeating events present a user-conceptual-understanding challenge, and likely should be avoided in user interfaces, and thus formats. E.g.
- http://forum.bodybuilding.com/showthread.php?t=107926751 - discussion (and confusion about) of whether every other day in a week is 3, 3.5, or 4 days.
Open Questions
These should be moved to hcalendar-issues.
Undecided Encodings of Certain Property Attributes
There are several attributes that still need to be discussed about how to property encode them into HTML.
For example the RSVP and ROLE attrbutes: ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT:MAILTO:jsmith@host.com or ATTENDEE:CUTYPE=GROUP:MAILTO:john@host.com
Other attributes include:
- Delegate-To
- Delegate-from
- Sent-By
- Member
- Partstat
- CN
- DIR
Then all the enumerated possible values for each of these
General Questions
These should be processed and move to either hcalendar-feedback, hcalendar-issues, or hcalendar-faq.
Q: Should Transforming applications purely extract the information and ignore validity? or should there be some checking, or should this be left to the importing application? (i.e. DTSTART;VALUE=DATE: This-Is-Not-a-proper-date)
A: The simpler the better. Other than checking for perhaps X(HT)ML validity, it should be a simple translator, because presumably the receiving iCalendar application has to have malformed .ics handling already. Let's avoid duplicating that. -- Tantek Çelik
Q: What about multiple of the instances same vCal entity? (two instances of DTSTART) Is this left up to the importing application, or should the XSLT transformation fail?
A: Same as previous. Leave it up to the importing application to interpret it per the iCalendar spec, e.g. what does RFC2445 say about two instances of DTSTART? -- Tantek Çelik
From RFC2445: 4.1.2 Multiple Values Some properties defined in the iCalendar object can have multiple values. The general rule for encoding multi-valued items is to simply create a new content line for each value, including the property name. However, it should be noted that some properties support encoding multiple values in a single property by separating the values with a COMMA character (US-ASCII decimal 44). Individual property definitions should be consulted for determining whether a specific property allows multiple values and in which of these two forms.
Other than that, it does not mention what to do ABOUT invalid data, or which of the multiple entries takes precedence. The only mention of duplicate instances is in the RRULE and EXDATE rules where events exclusions/inclusions overlap. Then duplicate instances are ignore. If it is explicitly written for those items, but NOT for things like DTSTART, then it is difficult to assume duplicate instances are ignored for them as well.
Each of the Components (VEVENT, ...) define which properties can exisit and in what quantity. So multiple DTSTART properties are NOT allowed. -- Brian Suda
Q: Should vCal entitles be represented in XHTML in classes ONLY on block-level element? or should some like VEVENT be block-level and others be of any? does this impact the semantics at all?
A: I don't think the (X)HTML notion of "block-level" should have any bearing whatsoever on vCal entities. You should be able to say <span class="vevent"> or <div class="vevent"> and either should work.
Q: Should the transforming application add any additional information to the iCalendar representation other than what was encoded in the HTML? (i.e. UID, the unique identifier might not be present in the HTML code, but could be generated by the transforming application and added to the iCal file. Should this be allowed? or should the transforming app ONLY be allowed to add X-PROPERTY properties?) IF it was not explicitly encoded in the HTML should it be left out? What about default values?
Q: If we are looking at the most semantic way to encoding iCalendar data in HTML then several other attributes should be considered besides just 'class'. There are two other candidated, ID and REL. The ID tag MUST be unique within the XHTML file (this could be used for the UID property). The REL attribute can ONLY be applied to 'a' and 'link' tags, but might be helpful. Are namespaces an option? xml:lang, xml:base, are there any others that might be more semantically correct to encode this data?
Q: To help distinguish xparam values from other actual CSS styles, should we assume/mandate that all values in a class attribute within an encoded iCal component class attribute (<x class="vevent|vtodo|...">) be considered an xparam?
A: If you are using other CSS styles (e.g. "center", "bluebox", "greenline", etc.) nested within an iCal component, those should be avoided and the styles applied to the list of iCal properties instead/also?
.center, .vevent { text-align: center; }
Q: What about cases where the words "yesterday", "last year", or "last week" was used? How should we represent this? Is this overkill or not appropriate for hcard ? - User:B.K._DeLong
A: I took a stab at "yesterday" and just added a dtstart of the previous day. Not sure how to represent a single year or whole week - User:B.K._DeLong
<abbr class="dtstart" title="20050114">Yesterday's</abbr>
Recurring Events
Recurring events are tricky. First, there's the question of whether to follow For types with multiple components, use nested elements with class names equivalent to the names of the components a la
<div class="rrule">every <em class="interval">1</em> <em class="freq">WEEKLY</em> on <em class="byday">TU</em> until <em class="until">2004-11-01</em></div>
... or ...
<abbr class="rrule" title="FREQ=WEEKLY;COUNT=17;INTERVAL=2;BYDAY=TH"> every other Thursday for 34 weeks</abbr>
... as in Tantek's 1 Aug msg.
DanC has been experimenting with representing his PDA calendar in hCalendar:
- in palmagent, there's dangerSync.py which uses the XMLRPC interface and spits out RDF data. Then asHCal.xsl converts that to hCalendar
- then in the RDF Calendar workspace, there's glean-hcal.xsl that turns hCalendar into RDF Calendar, and finally,
- in SWAP there's toIcal.py that turns RDF Calendar to .ics format.
So I can go from my sidekick to .ics with one Makefile.
events-test.html is a test file that has all the constructs from my PDA data, in hCalendar. In particular, it uses the nested element representation of recurring events. glean-hcal.xsl would be much less fun to write if it had to parse title="FREQ=WEEKLY;COUNT=17;INTERVAL=2;BYDAY=TH".
Then there's the question of "every tuesday afternoon at 2pm Chicago time". This isn't expressible using datetime-design-pattern. There are some good reasons for that, but it leaves a rather large and uncomfortable gap in hCalendar.
Encoding Questions
The way dates are encoded is not always the most user friendly. If i want to encode january 1st, 2005, that is 20050101
, which is displayed as 20050101. If we are marking-up comma seperated values, like FN, with each sub-element inside their own tag, then the date should be allowed the same.
(However, FN is in the RFC2426 spec and vCard schema, these individual date terms are not, therefore the reasoning in the last sentence is incorrect. -Tantek)
20050101 <span class="dtstart"><span class="Year">2005</span><span class="Month">01</span><span class="Day">01</span></span>
With this encoding, then YYYYMMDD schema can be rearranged for different cultures, DD-MM-YYYY for UK, MM-DD-YYYY for US, etc.
02-01-2005 <span class="dtstart"><span class="Month">02</span>-<span class="Day">01</span>-<span class="Year">2005</span></span> 01-02-2005 <span class="dtstart"><span class="Day" title="first">01</span>-<span class="Month" title="Feb">02</span>-<span class="Year">2005</span></span>
Both of the above encodings are equal, the '-' seperator is ignored by the transforming application. -- Brian Suda
Agreed that the way dates are encoded is not always the most user friendly, but there is an easier solution to this, once you think of what is actually going on in the difference between ISO8601 dates, and dates the way humans use them. Humans typically use an abbrevation or shorthand for a date, like "tomorrow", or "Tuesday", or "the 4th", or perhaps "July 4th". Thus it makes sense to permit this in hCalendar, using the <abbr>
tag which provides the ability to markup the human-familiar short form of some data or language, while preserving the long form in the 'title' attribute.
E.g. for the above example of a start date of January 1st, 2005, you could use this markup:
<abbr class="dtstart" title="20050101">January 1st, 2005</abbr>
Which would display as January 1st, 2005
but would provide the respective ISO8601 date in the title attribute. - Tantek
TO DO
XMDP Profile
- hCalendar XMDP profile (hcalendar-profile) needs to be created.
Applications
A simple implementation of transforming/extracting vCal data from an XHTML file is available for testing. A bookmarklet is also available. The code will be updated as the spec is finalised. http://suda.co.uk/projects/X2V/ . You may also use http://feeds.technorati.com/events/ for parsing hCalendar events and returning an iCalendar stream.
Parsing
Need to write up an hcalendar-parsing document, similar to hcard-parsing.
Relationships with other microformats
In a Technology Review interview, TBL said "It would have the relationships between the event and the various people chairing it.".
We should have examples of how hCalendar events can indicate such relationships, both in the format and in the presentation.
E.g.:
* Would it just link to URLs for the various people? (e.g. to their homepages/blogs etc.) * Would it include hCards for the various people? * Would it link to hCards for various people? * Perhaps allow all the above?
Mime-Type
According to RFC2445, the proposed media type value is 'text/calendar'.
A standard vCalendar file has an extension of .vcs and MIME type of text/x-vCalendar. If you use iCalendar, the MIME type is "text/Calendar" and the extension is .ics.
Text/X-vCalendar Content Type
The vCalendar object can also be passed as a non-standard MIME media type. This would be useful in order to clearly identify the vCalendar object in an electronic mail message body part. A non-standard, vCalendar object should be identified as the MIME type/subtype "text/x-vCalendar".
@@ - i have to do some more investigation, but (i think) vCalendar is a subset of iCalendar, so many of the same encodings will work for both, but this document is dealing with iCalendar RFC2445 representation!
Button
We need to come up with a nice [ hCal | friendly ]
button to indicate that event info on a page/site is using hCalendar. - Tantek.
Possibilities:
[ hCal | friendly ]
[ hCal | aware ]
[ hCal | inside ]
[ Valid | hCalendar ]
- though that would require writing an hCalendar validator which people could link to.[ <icon> | hCalendar ]
where <icon> could be some generic calendar looking thing, or it could be a PHP generated image with the actual date in the icon, kind of like how the Apple iCal icon updates in the dock automatically.
And then we have to pick colors and all that stuff - Tantek.
Other ideas:
[ hCal | enabled ]
[ hCal | available ]
- kind of an off-hand reference to being available for meetings, etc.
- Eric
Including More of iCalendar
Free/Busy information
See Neil Jensen's analysis of how to represent the iCalendar VFREEBUSY object in hCalendar.
In order to show free/busy information, we could either use the existing vevent class (with empty location, summary, etc. properties) or create a new vfreebusy class. We should create a new vfreebusy class because it is consistent with the XHTML design principles, particularly point #4, "Use class names based on names from the original schema...".
In the iCalendar standard, the vfreebusy calendar component frequently has more than one freebusy property, and also may have a number of other properties such as organizer. For example:
BEGIN:VFREEBUSY ORGANIZER:jsmith@host.com DTSTART:19980313T141711Z DTEND:19980410T141711Z FREEBUSY:19980314T233000Z/19980315T003000Z FREEBUSY:19980316T153000Z/19980316T163000Z FREEBUSY:19980318T030000Z/19980318T040000Z URL:http://www.host.com/calendar/busytime/jsmith.ifb END:VFREEBUSY
So, our hCalendar representation should include separate elements for the vfreebusy calendar component (defined once) and the freebusy property (possibly defined many times):
<span class="vfreebusy"> <span class="freebusy"> <abbr class="dtstart" title="20050721T1000-0800"> July 21, 2005 - 10:00 </abbr> - <abbr class="dtend" title="20050721T1100-0800"> 11:00 </abbr> </span><br/> <span class="freebusy"> <abbr class="dtstart" title="20050722T1000-0800"> July 22, 2005 - 10:00 </abbr> - <abbr class="dtend" title="20050722T1100-0800"> 11:00 </abbr> </span><br/> </span>
According to RFC2445 section 4.8.4.3, "When publishing a "VFREEBUSY" calendar component, the [ORGANIZER] property is used to specify the calendar that the published busy time came from." The organizer property type is CAL-ADDRESS, and can include "non-standard, language, common name and directory entry reference" property parameters. CAL-ADDRESS is "...a URI as defined by [RFC 1738] or any other IANA registered form...".
From what I've seen, Microsoft Outlook typically populates this property with the email address of the calendar owner, which initially made me think of using hCard to specify the organizer. However, given that the property refers to the calendar and not necessarily the person who owns or has published it, I think we should use a new organizer element, as shown below:
BEGIN:VFREEBUSY ORGANIZER:jsmith@host.com FREEBUSY:20050314T133000Z/20050314T163000Z END:VFREEBUSY
becomes
<span class="vfreebusy"> organizer: <span class="organizer">jsmith@host.com</span> <span class="freebusy"> <abbr class="dtstart" title="20050314T133000Z"> March 14, 2005 - 13:30 </abbr> - <abbr class="dtend" title="20050314T163000Z"> 16:30 </abbr> </span><br/> </span>
Hmmm, this looks a little funny when the organizer is so obviously an email address, but at least it is semantically correct. The other problem that I can now see occurring is when the organizer property has parameters, for example (from the iCalendar spec):
ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith@host1.com
Perhaps it's best to use the same approach described in "Human vs. ISO8601 dates problem solved"; use the abbr element like so:
<span class="vfreebusy"> <span class="freebusy"> organizer: <abbr class="organizer" title="CN=JohnSmith;DIR=ldap://host.com:6666/o=3DDC%20Associ ates,c=3DUS??(cn=3DJohn%20Smith):MAILTO:jsmith@host1.com">jsmith@host1.com</abbr> <abbr class="dtstart" title="20050314T133000Z"> March 14, 2005 - 13:30 </abbr> - <abbr class="dtend" title="20050314T163000Z"> 16:30 </abbr> </span> </span>
A different reading, particularly of section 4.6.4 "Free/Busy Component", is that the organizer property refers to a calendar user, not the calendar itself. In that section we find this: "When used to publish busy time, the "ORGANIZER" property specifies the calendar user associated with the published busy time".
Under this reading, an hCard might be appropriate. But if for some reason a simpler representation is wanted, using an <a> tag instead of <span> or <abbr> is closer semantically, more consistent with expected web presentation of uri-type data, and easily handles the ORGANIZER examples in the RFC. For example:
ORGANIZER;CN="John Smith":MAILTO:jsmith@host.com
becomes
<a class="organizer" href="mailto:jsmith@host.com">John Smith</a>
and
ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith@host1.com
becomes
<a class="organizer" href="mailto:jsmith@host.com" title="DIR=ldap://host.com:6666/o=3DDC%20Associates,c=3DUS??(cn=3DJohn%20Smith)">John Smith</a>
To-Do information
The Policy Aware Web (PAW) Project Meeting - 23 Aug 2005 uses class="vtodo" to capture action items. Clearly recording action items from a meeting and publishing them as minutes is a good practical example use of the VTODO object on the web.
What's the scenario for usage though?
What kind of indexer/aggregator application would find these VTODO items and what would it do with them?
Perhaps with some way of figuring out who the to-do item is assigned to ("ATTENDEE"), who assigned it ("DELEGATED-FROM"), and a whitelisting of who, perhaps the "ORGANIZER" property, (and their domains/URLs) that a user would accept assignments from, a user could aggregate to-do items assigned from other folks. Then question remains how to update the status ("STATUS") (RFC 2445 4.8.1.11 Status) on that to-do item when it is (a) completed ("COMPLETED"), (b) abandoned/cut/rejected ("CANCELLED"), (c) some progress is made ("IN-PROCESS") etc. There certainly seems to be sufficient expressiveness in VTODO and its properties to do a decentralized to-do list / task distribution system. Could be very interesting for helping open source projects and other distributed teams do project management using the Web.
Non-Gregorian Calendars
Japanese Calendar
- yomiuri - newspaper
- urakoma.com - form input
Umm al-Qura (Saudi Arabia) Calendar
- Sama - Government site
TobyInk hCalendar revision
User:TobyInk has put together a draft revised hCalendar spec using ideas from this brainstorming page, and expanding the spec to cover todo items, freebusy and alarms. Recurrences are documented, as are nested hCards, nested hCalendar items and attachments (using rel-enclosure).
- Expanding the spec to cover more items is a bad idea at this point outside of the process. In addition, any other changes should either come from resolution of hcalendar-issues or very well documented brainstorming items that are justified very well - if you know of any issues, add them to hcalendar-issues rather than assuming them and writing them into a spec (iteration). As editor of hCalendar, I think the next logical thing to do is to produce an iteration that takes into account resolved issues, and that's what I've listed as part of my plan on my to-do list. Tantek 07:46, 1 Sep 2008 (PDT)
- The hCalendar 1.1 draft does not attempt to add anything new to hCalendar (with the exception of VTODO lists, which is effectively an optimisation for quick and easy todo lists rather than proper extension). The hCalendar 1.0 spec is already "a 1:1 representation of the aforementioned iCalendar standard, in semantic HTML" — implying that all properties in iCalendar are allowed in hCalendar. The 1.1 draft merely documents the usage of some of the more esoteric properties in iCalendar and how they may be mapped to (X)HTML. (In fact, if anything it shrinks hCalendar rather than expands it, as it says that the VJOURNAL and VTIMEZONE components of iCalendar are not supported.) TobyInk 09:22, 1 Sep 2008 (PDT)
- As it happens, the hCalendar 1.1 draft also acts as rough documentation of how hCalendar is supported in Cognition. Although Cognition's implementation may vary from the draft in place to place, it is fairly close, and ultimately aims to implement the draft exactly (by improvements to Cognition rather than regressions in the spec!!) This may be useful for other parser programmers wishing to provide a roughly compatible implementation, and those looking for guidance on how to parse iCalendar features which are not covered by the official hCalendar spec. TobyInk 09:22, 1 Sep 2008 (PDT)
for hCalendar 1.1
- Apply simplifications, fixes from
- the above, and
- RFC5545 iCal Basic, which drops a lot of the non-event related stuff.
for hCalendar 2
- incorporate hCalendar 1.1 updates/changes into the microformats-2 hCalendar vocabulary
References
Normative References
Informative References
- HTMLForCalendars (FOO camp) - presented just a few days before this, hopefully these efforts can be combined
- Personal Data Interchange (PDI) at the Internet Mail Consortium
- Markup language design notes
- A Touch of Class
- iTIP RFC2446
- iMIP RFC2447
- Guide to Internet Calendaring RFC3283
Authors
Authors of the original hCalendar brainstorming page on the Technorati wiki which was copied here with the launch of microformats.org 2005-06-20:
Authors since 2005-06-20 are reflected by this wiki page's history.
Other Implementations/Ideas
- OpenPSA calendar screenshot
- RDF Calendar Workspace - some older work done with RDF, not really applicable to the simple XHTML case, but perhaps worthy of analysis for when and why they may have diverged from established iCalendar schemas.
- 2003 RDF icalendar work, xCal references
- vVenue (proposal to add vCard-adr like properties to iCalendar)
Blogs About Calendaring
Related Pages
- hCalendar - specification
- hCalendar intro - plain English introduction
- hCalendar authoring - learn how to add hCalendar markup to your existing events.
- hCalendar creator (hCalendar creator feedback) - create your own hCalendar events.
- hCalendar cheatsheet - hCalendar properties
- hCalendar examples in the wild - an on-going list of websites which use hCalendars.
- hCalendar implementations - websites or tools which either generate or parse hCalendars
- hCalendar FAQ - If you have any questions about hCalendar, check here.
- hCalendar parsing - normative details of how to parse hCalendar.
- hCalendar profile - the XMDP profile for hCalendar
- hCalendar singular properties - an explanation of the list of singular properties in hCalendar.
- hCalendar tests - a wiki page with actual embedded hCalendar events to try parsing.
- hCalendar "to do" - jobs to do
- hCalendar advocacy - encourage others to use hCalendar.
- iCalendar implementations
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. These thoughts, issues, and questions are kept in separate pages.
- hCalendar Brainstorming - brainstorms and other explorations relating to hCalendar
- hCalendar issues - issues with the specification