implementation-guidelines

Guidelines and Strategies for Implementing Microformats

NEEDS CLEANUP

This pages needs some clean up and re-organization in order to be useful as "guidelines" to implementers.

For now, this page currently contains a semi-random bunch of implementation thoughts.

If you are an implementer, feel free to jump in and help clean it up.

Thanks,

Tantek

Publishers

• Embedding in XHTML documents is the easiest thing to do with microformats.
• Microformats can be embedded in Atom entries:

 <entry>
   <title>Review of Some Object</title>
   <link href="http://microformats.org/wiki/" />
   <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
   <updated>20050730T1900-0700</updated>
   <content type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
     <div class="hreview">
       <h3 class="summary"><span class="item fn">Some Object</span> Being Reviewed</h4>
       <p>Reviewer: <span class="reviewer fn">author name</span> - 
       <abbr class="dtreviewed" title="20050730T1900-0700">July 30, 2005</abbr></p>
       <blockquote class="description"><p>The review content</p></blockquote>
       <span><span class="rating">5</span> out of 5</span>
     </div>
    </div>
   </content>
 </entry>

Questions:

• Should an XMDP profile be linked to the Atom entry?
• Should the hreview class appear in the content container div?

Identification

There are several user agent identification strategies. Currently, Firefox provides strong support for XPath based discovery methods. Some of these can be adapted to Internet Explorer 6 with a small loss in efficiency and others not at all. The following examples are in extreme summary form. It is suggested that you click through on the links for more explanation.

Firefox/Mozilla Strategies

The simplest method is just to use an XPath expression to identify the microformat. Here is an example that does just that:

var allDivs, thisDiv;

allDivs = document.evaluate(
    "//*[contains(@class, 'xfolkentry')]",
    document,
    null,
    XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE,
    null);
		
// Just run through all elements matched by the XPATH expression and change
// the background color to an attractive red.
for (var i = 0; i < allDivs.snapshotLength; i++) {
    thisDiv = allDivs.snapshotItem(i);
    // do something here.  For example, change the background color to red.
    thisDiv.style.backgroundColor = 'red';
}

A greasemonkey script that applies this strategy to de.lirio.us and an individual linkblog republished from del.icio.us is available here with a tutorial on how the script works and how to modify it for other microformats here. Alf Eaton uses this exact XPath strategy in an early script that he created for hreview.

However, as Alf Eaton also notes, the XPath-only strategy is subject to potential collisions where the class value that denotes the microformat's container element is contained in another class value. For example 'xfolkentry' is contained in 'mixfolkentry', and the XPath expression would identify both as an xfolk entry. While the danger of this particular collision occurring are slight, such may not be the case with other microformats.

To avoid collisions in microformat container values, Alf proposes an amendment to the above strategy that works well for microformats where the container element is identified by a class value. Alf's strategy is contained in the following code pattern (that does not run as is):

var mf = 'hreview';

var micropath = "//*[contains(@class,'" + mf + "')]";
var micromatch = new RegExp('\\b' + mf + '\\b');

var mc = document.evaluate(micropath, document, null,
XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
for (var i = 0; i < mc.snapshotLength; i++) {
    iNode = mc.snapshotItem(i);
    if (iNode.className.match(micromatch))
        doSomething();
}

Note that this solution introduces regular expression checking as a second test on the nodes isolated by the XPath expression. Modifying the first example to use this strategy in a bit of code that is runnable we get:

var allDivs, thisDiv;
var mf = 'xfolkentry';

var micropath = "//*[contains(@class,'" + mf + "')]";
var micromatch = new RegExp('\\b' + mf + '\\b');

allDivs = document.evaluate(
    micropath,
    document,
    null,
    XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE,
    null);
		
for (var i = 0; i < allDivs.snapshotLength; i++) {
    thisDiv = allDivs.snapshotItem(i);
    // do something here.  For example, change the background color to red.
    if (iNode.className.match(micromatch)) // apply the second test
    thisDiv.style.backgroundColor = 'red';
}

Internet Explorer Strategies

XPath-based strategies can be made to work sometimes in Internet Explorer with Dimitri Glazkov's javascript library that harnesses IE's built-in XPath support for traversing HTML DOM.

Parsing

Parsing Microformats can be as easy or as hard as you want it to be. Since many of the elementary building blocks are based on anchor tags, its possible possible to implement some fairly effective functionality without needing to mess around with the complexities of tag nesting and unknown class names. Simple rule: ignore anything you don't need.

hCard

see: hCard Parsing

See Also

• XMDP FAQ