XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

document

Category:

Association and localisation of nodes and resources at runtime

Origin:

XSLT 1.0

Return value:

A sequence of document nodes of external XML documents.

Call/Arguments:

document($uri-sequence, $base-node)

$uri-sequence:

Obligatory. The first argument of the function must be directly a URI of an external document or an expression which can be interpreted as URI. This may be a relative URI, an absolute URI or a fragment identifier. Usually, it is a xs:string string which can be directly treated as URI reference.

Alternatively, a sequence from various items (in XSLT 1.0 a node set consisting of one or more nodes) can be passed on. The string values of all items contained in the sequence passed on have to correspond to URI strings and are individually evaluated by the document() function.

If a URI reference cannot be resolved, an error is reported or – each time per item concerned – an empty sequence is returned. If this applies to one or more nodes of a sequence passed on, no document node is generated for the nodes in question. As a consequence, these nodes are not contained in the altogether generated output sequence (of the set union of all referenced documents).

$base-node:

Optional. If a node is passed on as second argument, its base URI is used in order to resolve relative URIs of the external document. This is neccessary provided that the URI passed on $uri shall not be evaluated relatively to the stylesheet (or to the base URI of the context node).

If a $base-node argument is passed on, it refers to all documents refereced by the first argument. In case the argument is not a (single) node, a type error is reported. If a node sequence is passed on for $base-node, only its first item is taken into account provided that the XPath 1.0 compatibility mode is used. Otherwise a type error is reported, too.

Remark: The fn:doc() function being alternatively introduced in XPath 2.0 has no second argument corresponding to $base-node. As a compensation, the fn:resolve-uri() function can also be used.

Purpose of use:

The purpose of the document() function is to include one or more other external XML documents in the XSLT processing. The return value of the function is a sequence (in XPath 1.0 a node set) consisting of the document nodes of the appropriate document or documents. The argument is interpreted as collection of the URIs under which those can be found.

The simplest case is that a string or a node whose string values shall be used is passed on and from which the URI of exactly one external document results.

However, if a sequence is passed on as first argument, each individual of its items is resolved by means of the document() function. For those items for which the resolution to a URI is successful, a document node is added to the result sequence. The other items are not taken into account (depending on the implementation, also an error message may occur).

Remark: There is a risk that in documents referenced to the source document identical element names are used having different meanings. As a consequence, without intention, the same templates would be used for the processing of the documents as for those of the source document.

Alternative function fn:doc in XPath 2.0:
As an alternative to document(), XPath 2.0 introduces the simplified fn:doc() function which, as a XPath Core Function, can also be used outside the XSLT context, for example in XQuery. The fn:doc() function only takes one argument, a URI string. A base URI cannot be passed on to the function.

Example – dynamic embedding of external sources with document():

Source document:

Assuming that there are book reviews in the form of external XML files and these reviews shall be outputted in a result document in connection with other information on the book. This may happen on the basis of a document similar to the following:

The Stylesheet:

Now, the reviews can be integrated into the output document with the document()function by passing on their URIs contained in the text attribute; for example as follows:

The return value of document(@uri) is a sequence consisting of nodes: the document node of the external document. As a result, with the help of xsl:apply-templates, the entire external document is included in the processing and processed with the templates being also available for the main document.

If this is not intended, a mode attribute can be applied when calling xsl:apply-templates, for example in the following form:

Then, templates with appropriate modes can be provided which are exclusively used for the processing of external documents. Alternatively, one or more named templates could be used to which the external document is passed on.

Function definition:

XSLT 1.0:

document(object, node-set?) => node-set

XSLT 2.0:

document($uri-sequence as item()*) as node()*

document($uri-sequence as item()*,

$base-node as node())   as node()*

Possible compatibility problems XSLT 2.0 to XSLT 1.0:

In XSLT 1.0, the document() function is not very specific regarding the data type of the URI argument and allows strings as well as node sets. In XSLT 2.0, the items of the input sequence are transformed independently of their data type into the xs:anyURI type. For each URI determined in this way, a document node is generated which is contained in the output sequence.

As an alternative to document(), XPath 2.0 introduces the widely equivalent but simplified fn:doc() funtion:

fn:doc($uri as xs:string?) as document-node()?

The XPath 2.0 function fn:doc() only allows strings as its (sole) URI argument. (The original plan to demand the XML Schema type xs:anyURI as data type has been dropped. However, the string to be passed on has to lexically correspond to xs:anyURI.)