Using the Basic API
The following section uses the markup shown below to demonstrate how to extract
and use subject, properties, values and Projections using the RDFa
API. The following markup is used for the examples in this section and is
assumed to be served from a document located at
http://example.org/people.
<div prefix="foaf: http://xmlns.com/foaf/0.1/" about="#albert" typeof="foaf:Person">
<span property="foaf:name">Albert Einstein</span>
</div>
Retrieving Basic Data
Often, developers must determine whether or not a document contains the type
of data that they are interested in processing. The RDFa API provides a simple
mechanism to extract things like subjects, properties and values from the
current document. The return types for subjects and properties are
always sequences of strings. Values are typically converted into language-native
types. Strings and language-native types are used in order to make processing
the data easier on the developer.
For example to get all of the subjects expressed in a document, one can use
the following call:
var subjects = document.data.getSubjects();
To get the list of properties for each subject retrieved above, a developer
could process each subject in a loop, like so:
for(var i = 0; i < subjects.length; i++)
{
var subject = subjects[i];
var properties = document.data.getProperties(subject);
// ... process the properties ...
}
To retrieve only subjects containing a particular property, such as a name
property, a developer could do the following:
var subjectsWithNames = document.data.getSubjects("http://xmlns.com/0.1/foaf/name");
Once the subjects containing a particular property are known, queries can be
done on each subject to retrieve the values of properties:
var namedSubject = subjectsWithNames[0];
var names = document.data.getValues(namedSubject, "http://xmlns.com/0.1/foaf/name");
To retrieve all values for a particular property, such as all of the names
listed in the document, the following code could be executed:
var allNames = document.data.getValues(null, "http://xmlns.com/0.1/foaf/name");
There are many more combinations of arguments passed to the basic getter
methods for subjects, properties and values that allow high-level querying of
data in the document. While this method of working with data may be useful to
many developers, others may want to construct this data into a more
object-oriented view of the data. In order to support this scenario, the RDFa
API introduces Projections in the next section.
Working with Projections
Retrieving Projections by Type
A Projection is an object-oriented view of a particular subject
that is expressed in the document. For example, to get all projections that
express people in a document, a developer can do the following:
var people = document.data.getProjections("http://www.w3.org/1999/02/22-rdf-syntax-ns#type", "http://xmlns.com/foaf/0.1/Person");
A developer can also specify short-cuts to use when specifying the URI:
document.data.setMapping("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#type");
document.data.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
var people = document.data.getProjections("rdf:type", "foaf:Person");
Retrieving Projections by Subject
You can also get a Projection by its subject:
var albert = document.data.getProjection("http://example.org/people#albert");
You can also specify a relative IRI and the document IRI will be
automatically pre-pended:
var albert = document.data.getProjection("#albert");
Retrieving Projections by Property
You can get a list of Projections by their properties:
var peopleNamedAlbert = document.data.getProjections("foaf:name", "Albert Einstein");
Using Projections
You can retrieve property values from Projections like so:
var albert = document.data.getProjection("#albert");
var name = albert.get("foaf:name");
You can specify values that you would like to map to a
Projection:
var albert = document.data.getProjection("#albert", {"name": "foaf:name"});
var name = albert.name;
The DOM may change between calls to any of the RDFa API
data retrieval methods. These changes may cause subsequent
calls to the same methods to return different results. As with any call against
a DOM that is changing, developers are advised to program accordingly in order
to avoid race conditions and other issues resulting from a changing
data set.
Managing Elements with Data
Retrieving Elements Containing Data by Type
You can retrieve the DOM Element that is described above by doing the following:
var elements = document.getElementsByType("http://xmlns.com/foaf/0.1/Person");
or you can specify a short-cut to use when specifying the IRI:
document.data.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
var elements = document.getElementsByType("foaf:Person");
Retrieving Elements Containing Data by Subject
You can also get a list of Elements by the subject of the data:
var elements = document.getElementsBySubject("http://example.org/people#albert");
You can also specify a relative IRI and the document IRI will be
automatically pre-pended:
var elements = document.getElementsBySubject("#albert");
Retrieving Elements by Property
You can get a list of Elements by the properties and values that
they declare:
var elements = document.getElementsByProperty("foaf:name", "Albert Einstein");
Modifying DOM Elements
You can modify elements that are returned just like any other DOM Node,
for example:
var elements = document.getElementsByProperty("foaf:name", "Bob");
for(i = 0; i <= elements.length; i++)
{
var e = elements[i];
e.style.setProperty('color', '#00cc00', null);
}
The code above would change the color of all the areas of the page where the
item's name is "Bob" to green.
