hcalendar-brainstorming

From Microformats Wiki
Jump to navigation Jump to search

hCalendarBrainstorming

Authors

BEST-PRACTICES

Along with the four base properties, you can define addtional properties through the use of the x-prop property. For best-practices it would be helpful if the transforming application added an x-prop named 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

Examples

This is a growing example case written in iCal format and transformed to the corresponding XHTML. These conversions are open to community input. 

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

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>

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. 

<nowiki>
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

<pre><nowiki> <span class="vcalendar"> <span class="vevent" id="19970901T130000Z-123402@host.com"> <abbr title="dtstamp" class="19970901T1300Z"></abbr> <abbr title="dtstart" class="19970903T163000Z">September 3rd, 4:30pm</abbr>- <abbr title="dtend" class="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 title="dtstamp" class="19970901T1300Z"></abbr>
    <abbr title="dtstart" class="19970401T163000Z">April 1st 4:30pm</abbr>-
    <abbr title="dtend" class="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>

@@ 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 title="dtstart" class="19970901T1300Z"></abbr>
    <abbr title="dtend" class="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>


CSS Styles

Since the hCal properties are added in as CSS styles, you can style them along with any normal CSS style. You are free to style these properties in any fashion you want, but here are a few examples that you can use.

Hiding Data

If you want to encode additional data without it being displayed in the HTML, you can use 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.

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.

Tutorials

How to include hCal encodings into your favourite Blogging Software.

Open Questions

General Questions

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

or
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 namespac<ETH>H �n 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; }

Encoding Questions

The way dates are encoding 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 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


TODO

A HTML head profile needs creation and a home.

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/

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

References

Normative References

Informative References

Other Implementations/Ideas
Retrieved from "http://microformats.org/wiki/index.php?title=hcalendar-brainstorming&oldid=1080"