Value Class Pattern

(Difference between revisions)

Jump to: navigation, search
(Basic Parsing: value class pattern applies to enumerated values (like 'type' subproperty of tel property))
m (derivation and tests: missing word)
Line 163: Line 163:
=== derivation and tests ===
=== derivation and tests ===
-
The handling of date and time values in the class pattern was originally [[value-excerption-pattern-brainstorming#date_and_time_separation|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.
+
The handling of date and time values in the value class pattern was originally [[value-excerption-pattern-brainstorming#date_and_time_separation|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.
Date and time separation and concatenation tests are available: [[value-excerption-dt-separation-test]]
Date and time separation and concatenation tests are available: [[value-excerption-dt-separation-test]]

Revision as of 02:31, 3 May 2009

Document status: alpha.

The value class pattern is derived from value-excerpting in hCard. As such, it is already somewhat supported in parsers.

As of 2009-05-01, the editors believe the value-class-pattern to be "feature complete" and ready for use in markup and encourage implementers to update accordingly and provide feedback. However, the precise parsing behavior is not quite finalized, and the documentation is a work in progress. The pattern should be used with some caution.

Contents


Editors
Ben Ward
Tantek Çelik

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, using dtstart in hCalendar:

<span class="dtstart">
    Friday 25th May, 6pm
    [<span class="value">2008-05-25T18:00:00+0100</span>]
 </span>

Whilst the entire string ‘Friday 25th May, 6pm […]’ is date information, it's only the ISO 8601 encoded datetime which must be consumed by a microformats parser, so the value class isolates it.

Note that "dtstart" is a datetime property and thus subject to additional special value class pattern handling as described in the Date and time values section below.

Basic Parsing

  1. 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.
  2. 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:
    1. if the value element is an img or area element, then use the element's alt attribute value.
    2. if the value element is an abbr element, then use the element's title attribute value.
    3. for any other element, use its inner-text.
  3. Where there are multiple descendants of a property with class name of value (multiple value elements)
    1. 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.
    2. if the microformats property expects a datetime value, see the Date Time Parsing section.
  4. Descendants with class of value must not be parsed deeper than one level. That is, where an element foo with class value has a descendant bar with class value, the content of foo is taken as the value. Nesting additional elements with class of value cannot be used to further isolate a property's value.

e.g.

<p class="description">
  <foo class="value">
    <bar class="value">Puppies Rule!</bar>
    <strong>But kittens are better!</strong>
 </foo>
</p>

In this example, description has a child ‘value’, and that child has a grandchildvalue’. However, the parsing of value classes stops at the first level, so the data for description is: <bar class="value">Puppies Rule!</bar><strong>But kittens are better!</strong>.

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:

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

DTSTART:2008-06-24T18:30:00

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 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).

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.

Date and time separation and concatenation tests are available: value-excerption-dt-separation-test

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:

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:

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:

  1. First, try to directly specify microformats property values inline (the most visible, no duplication),
  2. Then consider using the value-class pattern
    1. including multiple value elements for date and time properties
  3. 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.

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.

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.
  • 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 future revisions of HTML will offer up another solution. For now, this method has been tested against browsers, and creates a consistant 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.

You can also refer to the general Microformats FAQ and principles.

Related Pages

Value Class Pattern was last modified: Wednesday, December 31st, 1969

Views