jQuery Microdata

Microdata DOM API

As specified by the W3C Working Group, document.getItems(itemtype) returns a collection of all the elements with an itemscope attribute in the current document that have the given itemtype attribute.

Each itemscope element has a properties object that provides access to all of the element's itemprop descendants (either contained directly or referenced elsewhere in the document using the itemref attribute).

properties[itemprop] returns a list of all the nodes that represent the given property.

.getValues() returns an array of values from that list of nodes.

.itemValue gets and sets the value of an individual node.

These methods and properties allow the program to access all the Microdata nodes and values in the document. However, in order to provide this flexibility, the DOM API can be quite long-winded when reading the value of a single property, which is most often what's needed. For example:

var artists = document.getItems('http://schema.org/MusicGroup');
var albumTitle = artists[0].properties['album'][0].properties['name'][0].itemValue;

jQuery Microdata

jQuery Microdata's items() method mimics document.getItems() but can be used with any element as the root:

$('#artists').items('http://schema.org/MusicGroup');

As jQuery methods apply to the set of all matched elements, the interface is simplified, as we can avoid specifying an index when there's only one matched element:

var artists = $('#artists').items('http://schema.org/MusicGroup');
var albumTitle = artists.eq(0).property('album').property('name').value();

The same value method, with an argument, is used to set values:

var artist = $('#artists').items('http://schema.org/MusicGroup').eq(0);
artist.property('name').value('The Beatles');
artist.property('album').property('name').value('Revolver');

The values() method returns the values of all the matched elements as an array:

var titles = $('#artists').items('http://schema.org/MusicGroup')
    .property('album').property('name').values();

jQuery Things

As a convenience method for reading and writing single properties of an item, the microdata() method (equivalent to jQuery's data() method, but working with data stored as microdata rather than in data-* attributes) can be used to either read a single property (one argument), set a single property (two arguments), or set multiple properties (first argument as an object):

$('#artists').items('http://schema.org/MusicAlbum').each(function() {
    var album = $(this);

    // get a value
    var title = album.microdata('name');

    // set a value
    album.microdata('url', 'https://www.google.com/search?q=' + title);

    // set multiple values
    album.microdata({
        name: 'Revolver',
        datePublished: '1966'
    });

    // get all the properties as a data object
    var data = album.microdata();
}