Microformat

An HTML microformat is a convention for adding extra metadata to an HTML document so that it is easy to extract meaningful data from the document. Microformats typically use the class attribute to identify the data.

Metrici uses a generic microformat which makes it possible to encode any Java Script object in HTML. It is designed to support everything that JavaScript Object Notation (JSON) can support. The microformat allows a JavaScript object to be held within an HTML structure very flexibly, and allows the logical structure of the HTML to vary from the logical structure of the JavaScript object.

The typical use of this microformat is to pass data into client-side JavaScript processing such as charts. The advantages of this are:

  • The specification of the chart is entirely within the content of the document. All that is required is a relatively simple, generic processor to convert the data into the options required by the charting library.
  • It forces the chart to be driven by defined content, which makes is easier to support alternative charting libraries and to manage options through time.
  • Because it is just HTML, the content can be produced by processes that are not permitted to create scripts.
  • It makes testing easier for both the processes that produce the HTML and the processes that consume it.
  • It follows the principle of progressive enhancement. If JavaScript is not present, or if there is no script to interpret the data, then the plain data is still visible to the user.
  • It allows the data to be shown to the user in both its original form and its processed form, for example showing the user data as both a chart and a table.
  • Using a generic microformat makes it is easy to extend, for example adding options required by one charting library that can be ignored by another.

The microformat processor extracts a JavaScript object from an element in a HTML document (known as the microformat root element). The elements within the root element have additional classes which identify the logical structure of the data and the individual data items.

The processing is driven entirely by classes, and can be used with any HTML tags. Additional levels of HTML structure can be inserted without affecting the structure of the JavaScript object.

Processing rules

StepNameClassDescriptionExample
1. Root processing   The root element is interpreted as an object. Objects contain data, arrays and other objects, which must have names. {}
2. Data within an object mfData name The element is interpreted as an object property. The class immediately after the data class gives the name of the property, and the content of the element gives the value of the property.

By default, the data is assumed to be a string. The classes number and boolean can be used to denote numeric and boolean data types.

If no name is present, a name that is unique within the JavaScript object will be created.

 <span class="mfData name">Fred Bloggs</span>

Gives

name: "Fred Bloggs"
3. Object within an object mfObject name The element is interpreted as a nested object. The class immediately after the object class gives the name of the nested object. The content of the element gives the object content.

If an object of the same name already exists within the parent object, then this object is merged with that. This allows the data for an object to be held in non-contiguous parts of the HTML. This can be used to perform complex mappings between the HTML and JavaScript, though this should be avoided unless necessary.

If no name is present, a name that is unique within the JavaScript object will be created.

 

 <div class="mfObject person">
  :
</div>

Gives

person: {
  :
}
4. Array within an object mfArray name The element represents a nested array. The class immediately after the array class gives the name of the nested array. The content of the element gives the array content.

If an array of the same name already exists within the parent object, then this array is merged with that. This is useful where HTML rules prevents the creation of an enclosing element to represent the array. This is useful for defining some <td> elements within a <tr> as an array, but not all of them.

As well as declaring an array, the element may contain an mfData or mfObject class to denote that it contains data or an object, removing the need for an extra level of HTML markup.

If no name is present, a name that is unique within the JavaScript object will be created.

 <div class="mfArray groups">
  :
</div>

Gives

groups: [
  :
]

Example using array merging:

<tr class="mfObject">
  <td class="mfData caption">New Zealand</td>
  <td class="mfArray values mfData number">14</td>
  <td class="mfArray values mfData number">21</td>
  <td class="mfArray values mfData number">17.3</td>
</td>

Gives

{
  caption: "New Zealand",
  values: [14, 21, 17.3]
}
5. JSON data within an object mfJSON name The element contains data in JSON format. The class name immediately after the mfJSON class gives the name of the property.

<div class="mfJSON colors">
  ["red","yellow","green"]
</div>

Gives

colors: ["red","yellow","green"]
6. Data within an array mfData The element represents an array item. This is the same as data within an object, except that there is no name. <ul class="mfArray colors">
  <li class="mfData">gray</li>
  <li class="mfData">green</li>
  <li class="mfData">amber</li>
  <li class="mfData">red</li>
</ul>

Gives

colors: ["gray","green","amber","red"]
7. Object within an array mfObject The element represents an object within an array. This is the same as an object within an object, except that there is no name.  
8. Array within an array mfArray The element represents a nested array. This is the same as array within an object, except that there is no name.  
9. JSON data within an array. mfJSON The element contains data in JSON format. This is the same as JSON data within an object, except that there is no name.  

Programming

The mfparse.js script defines the mfparse jQuery plug-in.

This provides a new jQuery function mfparse() which returns the JavaScript object equivalent of the node.

$(".mychart").each(function(){
  var chartData = $(this).mfparse();
  // Do something with chartData
});

The mfparse.display.js and mfparse.display.css provide a convenient method for testing an mfparse structure. When you use the class mfParse, then the structure will be parsed and displayed as a series of nested tables.