Invoking the document() Function (XSLT)

7.3. Invoking the document() Function

In our previous stylesheet, we used the document() function to select some number of nodes from the original source document (our list of purchase orders), then open those files. There are a number of ways to invoke the document() function; we'll discuss them briefly here.

The most common way to use the document() function is as we just did. We use an XPath expression to describe a node-set; the document() function takes each node in the node-set, converts it to a string, then uses that string as a URI. So, when we passed a node-set containing the filename attributes in the list of purchase orders, each one is used as a URI. If those URIs are relative references (i.e., they don't begin with a protocol like http), the base URI of the stylesheet is used as the base URI for the reference.

If the document() function has two arguments, the second must be a node-set. The first argument is processed as just described, with the difference that the base URI of the first node in the node-set is used as the base URI for any relative URIs. That combination isn't used often, but it's there if you need it.

NOTE: Every node in the XPath source tree is associated with a base URI. When using the document() function, the base URI is important for resolving references to various resources (typically specified with relative links in a file opened with the document() function.

If a given node is an element or processing instruction node, and that node occurs in an external entity, then the base URI for that node is the base URI of the external entity. If an element or processing instruction node does not occur in an external entity, then its base URI is the base URI of the document in which it appears. The base URI of a document node is the base URI of the document itself, and the base URI of an attribute, comment, namespace, or text node is the base URI of that node's parent.

You can also pass a string or any other XPath datatype to the document() function. If we wanted to open a particular resource, we could simply pass the name of the resource:

document('http://www.ibm.com/pricelist.xml')

This action would open this particular resource and process it. Be aware that XSLT processors are required to return an empty node-set if a resource can't be found, but they aren't required to signal an error. XSLT processors also don't have to support any particular protocols (http, ftp, etc.); you have to check the documentation of your XSLT processor to see what protocols are and aren't supported.

A special case occurs when you pass an empty string to the document() function. As we've discussed the various combinations of arguments that can be passed to the function, we've gone over the rules for resolving URIs. When we call document(''), the XSLT processor parses the current stylesheet and returns a single node, the root node of the stylesheet itself. This technique is very useful for processing lookup tables in a stylesheet, something we'll discuss later in this chapter.