Sams Teach Yourself XML in 21 Days

Recommended Book

Sams Teach Yourself XML in 21 Days, 3rd Edition

Learn More Buy

Recommended Book

Recommended Book 

Sams Teach Yourself XML in 21 Days, 3rd Edition

Learn More Buy

Introducing XPointers

When you use XLinks, you can link to a particular document, but many times, you want to be more precise than that. XPointers let us point to specific locations inside a document, and they are coming into more common use; for example, SMIL 2.0 allows, but does not require, XPointers, and SVG also supports some aspects of XPointers.

There isn't much software that supports XPointers in depth today, although yesterday, when you used XPointers to point to path definitions, you saw that Adobe's SVG Viewer 3 does. Here are two other packages that support XPointers:

• Amaya (http://www.w3c.org/Amaya) supports XPointers but does not support the full XPath specification that you can use with general XPointers.
• Fujitsu's XLip (http://www.labs.fujitsu.com/free/xlip/en/index.html) has a full implementation.

The XPointer specification has had a contentious past, and it seems to have been one of the W3C specifications that got too complex for itself. It was abandoned at one point and split into parts to make it easier to implement. (You can find the story at http://www.w3.org/XML/2002/10/LinkingImplementations.html.) The XPointer specification is now divided into three recommendations and a working draft:

• http://www.w3.org/TR/xptr-framework/— The XPointer framework, which gives general background and points to the other three schemes.
• http://www.w3.org/TR/xptr-element/— The element scheme.
• http://www.w3.org/TR/xptr-xmlns/— The namespace scheme.
• http://www.w3.org/TR/xptr-xpointer/— The general XPointer scheme.

The XPointer framework specification introduces the idea of XPointers and indicates how to use barenames (that is, element names) as XPointers. And it points to the other three parts of the specification that you can use in XPointers: the element scheme, the namespace scheme, and the general XPointer scheme. We'll take a look at these ways of creating XPointers today, starting with barenames.

Using Barenames

The XPointer Framework specification (http://www.w3.org/TR/xptr-framework) says that you can use barenames—that is, just the names of elements—as XPointers. You can append an XPointer to the end of a URI by preceding it with a #, as in the following fictitious example, which points at the <data> element in www.XMLPowerCorp.com/insurance.xml:

<insurance xmlns:xlink = "http://www.w3.org/1999/xlink"
    xlink:type = "simple"
    xlink:show = "new"
    xlink:href = "http://www.XMLPowerCorp.com/insurance.xml#data">
    Health Insurance
</insurance>

Besides using barenames like this, you can also use the element, namespace, and general XPointer schemes. They're coming up next.

Using the Element Scheme

The element scheme (http://www.w3.org/TR/xptr-element) was broken out of the general XPointer scheme to make XPointer easier to implement. In the element scheme, you use element() to identify elements by ID, not by name. For example, to find the element with the ID "data", you could use this expression (technically, you can do this only if the element's ID is declared in an XML schema or a DTD):

<insurance xmlns:xlink = "http://www.w3.org/1999/xlink"
    xlink:type = "simple"
    xlink:show = "new"
    xlink:href = "http://www.XMLPowerCorp.com/insurance.xml#element(data)">
    Health Insurance
</insurance>

You can also specify child sequences by number; for example, to pick out the <data> element's third child element and then identify that element's first child element, you can use this XPath-like expression:

<insurance xmlns:xlink = "http://www.w3.org/1999/xlink"
    xlink:type = "simple"
    xlink:show = "new"
    xlink:href = "http://www.XMLPowerCorp.com/insurance.xml#element(data/3/1)">
    Health Insurance
</insurance>

As you can see, the element scheme lets you specify an element by ID, and you can also add location steps, by using numbers, to pick out child elements.

Using the Namespace Scheme

The namespace scheme (http://www.w3.org/TR/xptr-xmlns) indicates how to use namespaces when pointing to data. For example, if the <data> element you want to pick out is part of the xpc (for XML Power Corp.) namespace, you could specify that element this way:

<insurance xmlns:xlink = "http://www.w3.org/1999/xlink"
    xlink:type = "simple"
    xlink:show = "new"
    xlink:href = "http://www.XMLPowerCorp.com/insurance.xml#xmlns(xpc=

           "http:/XMLPowerCorp)xpc:data">
    Health Insurance
</insurance>

This XPointer picks out <xpc:data> in the document www.XMLPowerCorp.com/insurance.xml.

Using the XPointer Scheme

Because XPointer wasn't gaining much acceptance in its original very general and somewhat complex form, the W3C split the usage for barenames, the element scheme, and the namespace scheme away from the general XPointers to make XPointer easier to implement. However, the original form of XPointers is still part of the XPointer specification, although it's still in working draft form (http://www.w3.org/TR/xptr-xpointer). This is where the real meat of XPointer lies because you can use XPath expressions to point to exactly what you want; in fact, the XPointer scheme extends XPath. Here's what a full XPointer might look like—note that you use xpointer() here:

<insurance xmlns:xlink = "http://www.w3.org/1999/xlink"
    xlink:type = "simple"
    xlink:show = "new"
    xlink:href = "http://www.XMLPowerCorp.com/insurance.xml#xpointer(

           /child::*[position()=119]/child::*[position()=last()])">
    Health Insurance
</insurance>

This picks out the last child of the 119th element in www.XMLPowerCorp.com/insurance.xml. As you can see, you can use full XPath expressions with general XPointers.

You can also use the / n / m type of child identification, as in the element scheme. For example, this long expression:

http://www.XMLPowerCorp.com/ch10_01.xml#xpointer(
/child::*[position()=1]/child::*[position()=2]/child::*[position()=3])

can be abbreviated as this:

http://www.XMLPowerCorp.com/ch10_01.xml#1/2/3

In addition, the general XPointer scheme extends XPath by letting us select points and ranges besides normal XPath nodes. A point is a specific location in a document, and a range is made up of everything between two points. To support points and ranges, the general XPointer scheme extends the concept of nodes to locations. A location is an XPath node, a point, or a range. Node sets become location sets in the XPointer specification.

Although XPointers use the same axes as XPaths, there are some new node tests. These are the node tests you can use with XPointers:

• * — Matches any element.
• node() — Matches any node.
• text() — Matches a text node.
• comment() — Matches a comment node.
• processing-instruction() — Matches a processing instruction node.
• point() — Matches a point in a resource.
• range() — Matches a range in a resource.

Note in particular the last two—point() and range(). These correspond to the two new constructs added in XPointers, points and ranges, and you'll see more on them today.

General XPointers also make some additions to the functions that return location sets (that is, node sets in XPath). You can use the here() function to refer to the current element. This can be useful when you're working among the nodes of an element and want to refer to the current element or another node in the current element. For example, you might want to refer to the fifth previous <name> element of the current element, and you could do that this way:

here()/preceding-sibling::name[position() = 5]

In addition to here(), you can also use the origin() function, which is much like the here() function but is used with out-of-line links. This function refers to the original element from which the link was activated, even if that element is in another document.

Creating XPointer Points

To define an XPointer point, you use two items—a node and an index that can hold a positive integer or zero. The node specifies an origin for the point, and the index indicates how far the point you want is from that origin.

There are two different ways of measuring the index: in terms of characters in the document and in terms of a number of nodes, and you'll take a look at them here, as well as how to use the functions that work with points.

Measuring in Characters

If the starting node can contain only text, but not any child nodes, then the index is measured in characters. Points like these are called character-points. The index of a character-point must be a positive integer or zero and less than or equal to the length of the text string in the node. If the index is zero, the point is immediately before the first character; an index of 5 locates the point immediately after the fifth character. Character-points do not have preceding or following siblings or children.

Here's an example that treats <DOCUMENT> as a container node in the document:

<data>
Hello!
</data>

In this example, there are six character-points, one before each character. The character-point at Index 0 is right before the first character, H, the character-point at Index 1 is just before the e, and so forth. Note also that the general XPointer specification collapses all consecutive whitespace into a single space for counting purposes.

Measuring in Nodes

When the start node, also called the container node, has child nodes (in other words, it's an element node or the root node), the index of a point is measured in child nodes.

For an index of zero, the point is just before any child node. An index of 7 specifies a point immediately after the seventh child node.

Using Point Functions

When it comes to creating points, you can use the point() function with a predicate, like this:

point()[position()=5]

For example, say that you want to locate a point right before the l in California in the states example from Day 10, "Working with XSL Formatting Objects," ch10_01.xml. You could do that like this:

xpointer(/states/state[1]/name/text()/point()[position() = 2])

Creating XPointer Ranges

When it comes to creating ranges, all you need are two points: a start point and an end point. This is true as long as they are in the same document and the start point is before or the same as the end point; if the start point and the end point are the same point, the range you create is called a collapsed range.

The general XPointer specification adds to the functions in XPath a number of functions to handle ranges:

• range( location-set ) — Takes the locations you passed to it and returns a range that completely covers the locations.
• range-inside( location-set ) — Returns a range or ranges covering each location inside the location set; if you pass an element, the result is a range that encloses all that is inside the element.
• range-to( location-set ) — Returns a range for each location in the location set.

Besides these functions, the XPointer specification includes a function for string matching, string-range(). You can use this function to return a range for every match to a search string. Here's how to use string-range():

string-range(location-set, string, [index, [length]])

For example, the following expression returns a location set of ranges for all matches to the word Massachusetts:

string-range(/*, "Massachusetts")

You can use the [] operator to extract a specific match from the location set returned by this function. For example, the following expression returns a range covering the second match to Massachusetts:

string-range(/*, "Massachusetts")[2]

As you've seen so far today, there's a lot more power with XLinks and XPointers than you'll find with simple HTML hyperlinks. The software implementations of XLink and XPointer have been slow in arriving, but more and more are appearing now. XPointer in particular has been slow to be picked up because of the complexity of the general XPointer scheme, which you've just seen, but with the new division into element and namespace schemes, use of XPointer should accelerate.