value-class-pattern: Difference between revisions
(implied dtend date from dtstart, under strong consideration, note X2V has implemented this.) |
|||
Line 425: | Line 425: | ||
* [http://forabeautifulweb.com/blog/about/value_class_pattern/ For A Beautiful Web: Value Class Pattern] | * [http://forabeautifulweb.com/blog/about/value_class_pattern/ For A Beautiful Web: Value Class Pattern] | ||
* [http://microformats.org/blog/2009/05/12/value-class-pattern/ 2009-05-12 microformats.org: Value Class Pattern] | * [http://microformats.org/blog/2009/05/12/value-class-pattern/ 2009-05-12 microformats.org: Value Class Pattern] | ||
* [http://ablognotlimited.com/s/106 Getting Semantic With Microformats, Part 8: Value Class Pattern] | |||
==Related Pages== | ==Related Pages== |
Revision as of 21:37, 10 August 2009
<entry-title>Value Class Pattern</entry-title>
The value class pattern is derived from value-excerpting in hCard.
The editors believe the value-class-pattern to be feature complete and ready for use in markup. Implementers are encouraged to update accordingly and provide feedback. Note, the precise parsing behavior could change in response to implementer feedback, but the core methods are stable. You should watch this page for updates.
See also, the blog announcement.
- Editors
- Ben Ward
- Tantek Çelik
- Short URL
- http://tr.im/valueclass
Sometimes, only a part of an element's content is to be used as the value of a microformat property. This may occur when a property has optional subproperties, such as tel: type
and tel: value
in hCard. Other times, the most appropriate structure for a property may include other content.
For these purposes, the special class name value
is used to mark-up the relevant data excerpt from larger element content.
Simple Examples
Here is markup for a home phone number:
vCard fragment:
TEL;TYPE=HOME:+1.415.555.1212
hCard fragment:
<span class="tel">
<span class="type">Home</span>:
<span class="value">+1.415.555.1212</span>
</span>
In this case, the value
of tel
is +1.415.555.1212
, not Home: +1.415.555.1212
.
Sometimes the value for a microformats property must be split into multiple pieces in the content of the element representing that property. Multiple elements with a class name of "value" (value elements) can be used to extract and concatenate these pieces into a single value for microformats properties which expect simple strings or tel values.
Another example, this time using a localized (British) telephone number:
<span class="tel">
<span class="type">Home</span>:
<span class="value">+44</span> (0) <span class="value">1223 123 123</span>
</span>
In this case, the valid data for the telephone number is +441223123123, but the way in which phone number is presented in Britain will include the (0), for local dialling. That is, from anywhere in the world you may dial +441223123123, or from within Britain you may dial 01223123123. Common local publishing interferes with the data, since dialling +4401223123123 is an invalid number.
In the mark-up, two value
classes target the part of the telephone number string that makes an international, valid number, whilst allowing conventional presentation.
Another example, adding a place name to a geo co-ordinate:
<p>I'm loitering outside The Bricklayer's Arms
<span class="geo">
51° 30' 48.45", -0° 8' 53.23"
(<span class="value">51.513458;-0.14812</span>)
</span>
</p>
Whilst the entire string is a geo point, it's only the decimal encoded co-ordinates which must be consumed by a microformats parser, so the value
class isolates it from the degrees form, which the publisher includes for completeness.
Basic Parsing
- The value class pattern only applies to properties which are simple strings, enumerated values, telephone numbers, and datetimes. The value class pattern does not affect parsing of properties of type email, URL, URI, UID.
- Where an element with such a microformat property class name has a descendant with class name
value
(a "value" element), parsers should use the following portion of that element:- if the value element is an
img
orarea
element, then use the element'salt
attribute value. - if the value element is an
abbr
element, then use the element'stitle
attribute value. - for any other element, use its inner-text.
- if the value element is an
- Where there are multiple descendants of a property with class name of
value
(multiple value elements)- if the microformats property expects a simple string, enumerated value, or telephone number, then the values extracted from the value elements should be concatenated without inserting additional characters or white-space.
- if the microformats property expects a datetime value, see the Date Time Parsing section.
- Descendants with class of
value
must not be parsed deeper than one level. That is, where an elementfoo
with classvalue
has a descendantbar
with classvalue
, the content offoo
is taken as thevalue
. Nesting additional elements with class ofvalue
cannot be used to further isolate a property's value.
e.g.
<p class="description">
<span class="value">
<em class="value">Puppies Rule!</em>
<strong>But kittens are better!</strong>
</span>
</p>
In this example, description
has a child ‘value
’, and that child has a grandchild ‘value
’. However, the parsing of value
classes stops at the first level, so the data for description
is: <em class="value">Puppies Rule!</em><strong>But kittens are better!</strong>
, not just Puppies Rule!.
Date and time values
Some microformats properties expect an ISO8601 datetime value, e.g. hCalendar dtstart
and dtend
or hAtom published
.
Authors may use the value class pattern to separately specify the date and the time, which are then combined to specify a single datetime value.
Example, this hCalendar 'dtstart' property with 'value' elements:
<p>The weekly dinner will be on
<span class="dtstart">
<abbr class="value" title="2008-06-24">this Tuesday</abbr>
at <span class="value">18:30</span>
</span>
</p>
produces the following 'dtstart' value:
2008-06-24T18:30:00
and iCalendar converters produce the following DTSTART:
DTSTART:20080624T183000
The lack of a timezone indicates a "floating" datetime, that is a datetime independent of any particular timezone. Examples of floating datetimes could be an alarm clock you set to ring at 7am, or the common 9am-5pm workday.
Date and time parsing
For all date time properties (as defined in their respective microformats specifications), the following rules apply in addition to (and in some cases replacing) the above value class pattern parsing rules.
When a "value" element is found, parse a value from the element as follows:
- if the element is an
img
orarea
element, then use the element'salt
attribute value. - if the element is an
abbr
element, then use the element'stitle
attribute value. - for any other element, use its inner-text.
- if the value has both a specific ISO8601 date and a specific time, use those and stop looking for "value" elements.
- if the value has *only* a specific date, specifically, fits the following ISO8601 date patterns (i.e. as documented in the Wikipedia summary of ISO8601)
- YYYY-MM-DD
- YYYY-DDD
- then use that as the date value. For the purposes of the value class pattern, the hyphens "-" separating the year, month, day and/or ordinal day are required.
- ignore any further "value" elements that specify the date.
- if the value has *only* a specific time (with or without timezone), parse it for a time value that can match any of the following:
- HH:MM:SS-XX:YY
- HH:MM:SS+XX:YY
- HH:MM:SS-XXYY
- HH:MM:SS+XXYY
- HH:MM:SSZ
- HH:MM:SS
- HH:MM-XX:YY
- HH:MM+XX:YY
- HH:MM-XXYY
- HH:MM+XXYY
- HH:MMZ
- HH:MM
- HH is the 24 hour "hours" in the time, from 00 to 24, with optional leading 0 for values less than 10.
- MM are the minutes from 00 to 59
- SS are the optional seconds from 00 to 59 (60 for a leap second). If omitted, infer 00 seconds.
- XX is the time zone hours offset, from 00 to 12 with optional leading 0 for values less than 10.
- YY is the time zone minutes offset, from 00 to 59, though in practice only 00, 15, 30, 45 minute offsets are used in global timezones.
- Z is the literal 'Z' to indicate GMT.
- For the purposes of the value class pattern, the colons ":" separating the hour, minutes, seconds are required.
- However the colons ":" separating the hours and minutes of any timezone offset are optional and discouraged in order to make it less likely that a timezone offset will be confused for a time.
- Under strong consideration: case insensitive { }"am"|{ }"a.m." suffix to treat an HH value of 12 as 00, or a case-insensitive { }"pm"|{ }"p.m." suffix to add 12 to HH value less than 12 - per Wikipedia article on the 12 hour clock. Note: X2V has implemented this.
- HH:MM:SSam
- HH:MM:SSpm
- HH:MMam
- HH:MMpm
- HHam
- HHpm
- where "am" and "pm" mean "am or a.m." and "pm or p.m."
- when MM is omitted, infer 00 minutes.
- ignore any further "value" elements that specify the time.
- if the value has *only* a specific timezone, parse it for a time zone value that can match any of the following:
- -XX:YY
- +XX:YY
- -XXYY
- +XXYY
- -XX
- +XX
- Z
- XX is the time zone hours offset, from 00 to 12 with optional leading 0 for values less than 10.
- YY is the time zone minutes offset, from 00 to 59, though in practice only 00, 15, 30, 45 minute offsets are used in global timezones.
- Z is the literal 'Z' to indicate GMT.
- ignore any further "value" elements that specify the timezone.
If by parsing the "value" element(s), at least a specific date has been found, then the "value" is overall valid, and the parser assembles the overall datetime value by concatenating the specific date, "T" and specific time (if time was specified, with 00 seconds implied if no seconds are provided), and specific timezone (if timezone and a specific time was specified).
- YYYY-MM-DD - no time specified
- YYYY-MM-DDTHH:MM:SS - time specified but no timezone. This is a floating time.
- YYYY-MM-DDTHH:MM:SS-XXYY or
- YYYY-MM-DDTHH:MM:SSZ or
- YYYY-MM-DDTHH:MM:SS+XXYY - both time and timezone were specified.
iCalendar converters in addition must do the following:
- remove any dash "-" separators in the date.
- remove any colon ":" separators in the time.
- perform datetime math on any +/- relative timezone value, and produce an effective UTC value ending with "Z".
Atom converters in addition must do the following:
- normalize all date and datetime values to RFC 3339.
derivation and tests
The handling of date and time values in the value class pattern was originally brainstormed on the value-excerption-pattern-brainstorming page and derived from that analysis and feedback. For the curious, historical details may be found there, along with additional thoughts for extension.
See value-class-date-time-tests for test cases.
format specific optimizations
The following are format specific optimizations under strong consideration that make use of the value-class-pattern. Note: X2V has implemented this for hCalendar.
- short URL for this section
- http://tr.im/vcpfso
hCalendar dtend implied date
Typically events that start and end the same day only display the date of the event once (makes sense per the DRY principle) (real world examples: Upcoming, ... more examples with URLs would help for thoroughness).
Thus it would be convenient if we could imply an hCalendar event "dtend" date from its "dtstart" date when only the time (and optionally timezone) was specified for its "dtend", e.g.:
<span class="vevent">
The <span class="summary">party</span> will be on
<span class="dtstart">
<span class="value">2009-06-26</span>, from
<span class="value">19:00</span></span> to
<span class="dtend"><span class="value">22:00</span></span>.
</span>
To simplify this further for authors, hCalendar processors could treat the specifying of just the time per the value-class-pattern date and time value rules, and thus eliminate the need for the "value" span inside the "dtend" span:
<span class="vevent">
The <span class="summary">party</span> will be on
<span class="dtstart">
<span class="value">2009-06-26</span>, from
<span class="value">19:00</span></span> to
<span class="dtend">22:00</span>.
</span>
hCalendar to iCalendar converters should produce the following iCalendar fragment (as part of a valid .ics file) from either of the above two examples:
BEGIN:VEVENT
SUMMARY:party
DTSTART:20090626T190000
DTEND:20090626T220000
END:VEVENT
Note: X2V has implemented this.
Examples "in the wild":
- http://microformats.org/wiki/events/2009-08-12-nyc-workshop (real world example, but on this wiki).
hAtom updated implied date
Similarly, in blog posts that indicate both when they were "published" and "updated", the date is usually only displayed once, typically when "published" (real world examples with URLs would help for thoroughness).
Thus it would be convenient if we could imply an hAtom entry "updated" date from its "published" date when only the time (and optionally timezone) was specified for its "updated", e.g. for a blog post that was updated the same day:
<span class="hentry">
<span class="entry-summary">short blog post example</span>
was published on <span class="published">
<span class="value">2009-08-01</span> at <span class="value">12:06</span></span>
and updated at <span class="updated"><span class="value">12:10</span></span>.
</span>
To simplify this further for authors, hAtom processors could treat the specifying of just the time per the value-class-pattern date and time value rules, and thus eliminate the need for the "value" span inside the "updated" span:
<span class="hentry">
<span class="entry-summary">short blog post example</span>
was published on <span class="published">
<span class="value">2009-08-01</span> at <span class="value">12:06</span></span>
and updated at <span class="updated">12:10</span>.
</span>
Parsing value from a title
attribute
The value-title
class name allows the publisher to indicate the data value for a parent property is contained in the title
attribute of an element, rather than the inner-text.
This can be used to provide a synonym within content, or used to quietly publish alternate forms of information for microformats parsing, without affecting the consumption of content.
For example, you can use casual localization with dates:
<p>It was
<span class='dtstart'>
<span class='value-title' title='2008'>last year</span>
</span>
that I realised my addiction to cashew nuts would cost this country so dear.
</p>
Parsing rules for value-title
are the same as for value
above, with the following change:
- Where a microformats property has a child element with class name of
value-title
, the content of thetitle
attribute of that element must be parsed, rather than the portion of the element that would be parsed for a class name ofvalue
.
Using value-title
to publish machine-data
The initial usage of value-title
is used to publish alternate, parsable forms of property values in a visible context without the use of the abbr
element whose semantics already support interpretation of the 'title' attribute as an expanded, more precise form of the content.
Experience has found that there are some cases in microformats where a number of publishers want to include a precisely accurate and parsable value for a property but do not want it to be visible in their page, even as a tooltip.
For example, full ISO8601 datetimes may be confusing to readers of the page (as a tooltip or when read aloud by a screen reader), and enumerated values such as the type
subproperty of hCard's tel
property use US-English terms, which are not part of pages in any other language.
Since both of those scenarios have shown to be obstacles for a number of publishers, for these cases, and these alone, there exists a further extension of value-excerption. This extension allows the parsable form of the property to be published ‘silently’ immediately adjacent with the respective local visible content.
Here is an example, with the required use of a first child element with class name value-title
:
<p class='tel' lang='en-gb'>
<span class='type'>
<span class='value-title' title='cell'> </span>
mobile
</span>
<span class='value'>+44 7773 000 000</span>
</p>
The cell value is parsed for the 'type' subproperty, but mobile is presented to the user.
In the case of dates:
<p class='dtstart'>
<span class='value-title' title='2009-03-14T16:28-0600'> </span>
March 14th 2009, around half-past four
</p>
A microformats parser will read the ISO8601 format datetime 2009-03-14T16:28-0600, but users will only see March 14th 2009, around half-past four. Testing has shown that the ISO8601 datetime above does not get exposed to any user at all.
Parsing machine-data value-title
Browsers collapse the value-title
span down to a width of 0
, effectively providing no visual rendering, whilst keeping the element in the DOM. With no physical dimensions, there is no ‘hover’ state, so no tooltip is revealed. Furthermore, the empty element is not passed to assistive technology layers such as VoiceOver. Screen readers do not read the contents of the title attribute of an empty span
element.
We conducted thorough testing of these parsing behaviors to ensure accessibility.
Note: Whilst the value-title
element is more gracefully written without whitespace inner-text (or as self-closing <foo />
element in XHTML), current tools such as WYSIWYG editors and HTML-Tidy will erroneously discard such elements, resulting in parsable data being thrown away by some tools. As such, <span class='value-title'> </span>
, including a single whitespace character between the opening and closing tag, is the required pattern for authors, at this time.
Parsing this final value-title
extension imposes some stricter restrictions on usage. These restrictions exist to reduce the impact of DRY violations, reduce the opportunity for sites to spoof data, and encourage best practice for maintaining both forms of data accurately.
Where an element with class value-title
is to be parsed as data for a property, and that element also contains no non-whitespace content (hereafter referred to as ‘empty’), the following rules apply:
- The ‘empty’ value-title element must be the first, non-whitespace child of the property element. That is, it should follow immediately after the property is declared, before the human-readable form, and without any additional nesting.
- The ‘empty’ value-title element can only be used for specific properties. Microformat specifications must explicitly state which properties may be used with this extension of the value-class-pattern.
- Where an ‘empty’ value-title element is to be used as the single property value, it must be the only such
value
content. That is, the first instance of a conformingvalue-title
element overrides all othervalue
andvalue-title
siblings and/or cousins. - Tools written to perform Conformance Testing and/or Validation of microformats should attempt to compare the machine-data and human legible forms of the property data, and advise authors if the forms do not match.
limited use of value-title
Due to the fact that the value-title pattern hides some amount of data which tends to be a machine-specific duplicate of data that is provided in the human readable content, there are two microformats principles being compromised: visibility and DRY. Thus the applicability of this pattern is deliberately restricted to properties that have demonstrated through experience a need for it, with no known better alternative.
In general authors should:
- First, try to directly specify microformats property values inline (the most visible, no duplication),
- Then consider using the value-class pattern
- Including multiple value elements for date and time properties
- and then only if those methods are insufficient, consider the value-title pattern.
This document post-dates other microformat specifications, such that they may not yet indicate which properties permit use of this pattern. In the interim, only the following types of properties should allow the value-title pattern.
- ISO8601 date, datetime, timezone, and duration values
- Enumerated values (such as the hCard tel/email/adr 'type' subproperties)
- Co-ordinates (such as the geo 'latitude' and 'longitude' properties)
- Telephone number properties (e.g. the hCard 'tel' property)
The machine-data page has documentation of some of the properties of some specs which experience has shown need a solution like the value-title pattern.
There are some simple reference examples and tests for this pattern on value-class-pattern-tests.
In future use, specification authors may inherit use of value-title
by use of ISO8601 date and time formats, or reuse of other microformats, but specifications should _avoid_ introducing new data structures that depend on or encourage this pattern. New specifications are themselves expected to adhere to the principals of visibile data and DRY.
Test cases
See value-class-pattern-tests.
FAQ
This section is informative.
Frequently asked questions about the value-class-pattern. Once this section grows too big, we'll make a separate wiki page (like value-class-faq).
- Why use an 'empty' element? Why not embed data in the class attribute?
- The class attribute is inappropriate for embedded data values, as per the HTML4 specification, which states
class
is for ‘general purposing processing’, which is defined as ‘e.g. for identifying fields when extracting data from HTML pages into a database, translating HTML documents into other formats, etc.’. ‘General purpose processing’ does not extend to data itself. Furthermore, this method avoids inventing a new string pattern for embedding data.
- The class attribute is inappropriate for embedded data values, as per the HTML4 specification, which states
- Why use an 'empty' element? Why not make up a new attribute, like ‘data’?
- Microformats exist and function in valid HTML4 and XHTML1. Those are the current standards for web development, and microformats exist for use now. In the future, perhaps revisions of HTML will offer up another solution. For now, this method has been tested against browsers, and creates a consistent document structure (where machine-form and human-form data are siblings).
- The
title
attribute should only be used for content!- The
title
attribute is used for content and is read by microformats parsers. This exists for cases where data cannot be parsed with sufficient precision from just the commonly published, visible information. This pattern allows both forms of content to be included, whilst keeping it invisible to human consumers.
- The
You can also refer to the general Microformats FAQ and principles.
Examples in the wild
This section is informative.
The following sites and pages have started marking up content with the value-class-pattern, and are thus good places to go for examples with real world content to test with implementations (i.e. parsers). If you use the value-class-pattern in your content, feel free to add it to the top of this list. Once the list grows too big, we'll make a separate wiki page (like value-class-examples-in-wild).
- George Brocklehurst's activity stream and blog use "value-title" for hAtom
published
property - Ben Ward's home page uses:
- "value-title" for hCard
bday
property - "value-title" for hAtom
updated
property
- "value-title" for hCard
- microformats.org uses:
- "value-title" for hAtom
updated
property in [microformats.org blog postss]] - date and time value separation for hCalendar
dtstart
property in microformats.org recent and upcoming events wiki page
- "value-title" for hAtom
Add your site/page(s) that use the value-class-pattern here, along with a brief description of what value-class-pattern features you use, with which microformat(s) and which of its/their properties.
Implementations
This section is informative.
The following implementations have been developed which either generate or parse value-class-pattern property values. If you have an value-class-pattern implementation, feel free to add it to the top of this list. Once the list grows too big, we'll make a separate wiki page (like value-class-implementations).
- X2V v0.9.3 and later:
- implements Date and time values parsing, including am/pm time values
- thus passes Date and time values test cases.
- implements hCalendar implied dtend date
- Operator has *some* implementation of the value-class-pattern according to Michael Kaply, but precisely how much is implemented, for which properties (property types) and which microformats is not currently known.
- Optimus v0.8 and later implements
value-title
as announced by Dmitry Baranovskiy. - ... add your implementation(s) that parse or generate the value-class-pattern here, along with which features you support (hopefully all!) and note any limitations if any.
Blog Posts
Blog posts discussing the value class pattern, most recent first:
- 2009-05-17 Adactio: Microformation
- For A Beautiful Web: Value Class Pattern
- 2009-05-12 microformats.org: Value Class Pattern
- Getting Semantic With Microformats, Part 8: Value Class Pattern
Related Pages
This section is informative.
- value-class-pattern-tests
- value-excerption-pattern-issues
- hCard: Value Excepting
- value-excerption-pattern-brainstorming
- Machine Data in Microformats
References
This section is informative.