eXist-db comes with partial support for the XInclude standard. By default, eXist-db's XML serializer will scan all XML fragments for XInclude tags.
The XInclude processor is implemented as a filter in between the serializer's output event stream and the receiver. If it finds an XInclude element, it will try to expand it. XInclude processing is therefore applied whenever eXist-db serializes an XML fragment,whether it's a document, the result of an XQuery or an XSLT stylesheet.
eXist-db's does not support the full XInclude standard:
You cannot include raw text, only XML.
XPointers are restricted to XPath. Additional features defined in the XPointer spec (points and locations) are not supported. However, you can use XPath functions to partly work around this and substitute XPointer's important
eXist-db expands XIncludes at serialization, which means that the query engine will see the XInclude tags before they are expanded. You therefore cannot query across XIncludes, unless you create your own code (e.g. an XQuery function) for it.
DTD entity declarations can be used for some of the things that XInclude can be used for. In general, however, XInclude is more powerful (with the exception that entity declarations are able include raw text).
The XInclude namespace (in the examples below bound to the prefix
To include an entire document, simply specify its path in the
attribute of an
For example, one can include a standard disclaimer, stored in the file
short-disclaimer.xml, as follows:
If the URI in the
href attribute specifies a known scheme (like
file:), eXist-db will try to load it as an external
resource. For example:
If no scheme is specified, the XInclude processor will first try to load the referenced document from the database (relative to the current collection), and if that fails, from the file system.
If the document that contains the XInclude has been constructed in an XQuery (see Including XQuery results), relative file system paths will be resolved relative to the main XQuery module source file.
xpointer attribute of the
<xi:include> element can be used
to identify which part of the resource to include.
If the XPointer contains a simple value it is interpreted as an identifier. This will
select the element in the target document that has a matching attribute of type identifier
For example, assume an XInclude target document
disclaimer.xml looks like
the following XInclude selects the element from
identifier attribute with value
When there are multiple instances of the same identifier attribute, only the first instance will be used.
We can also use an XPath expression to select fragments. For this the
xpointer attribute must contain an XPointer, which consists of so called
"schemes". An XPath expression can be passed through the
The following expression includes the first stage direction in Shakespeare's Macbeth:
XIncludes can also perform searches, for instance using a full-text search:
The XPath expression will be applied to the entire collection if the path in
href points to a collection and not a single document:
In all cases, only the first hit is retrieved.
All namespace/prefix mappings declared in the source document are passed to the query
context. If necessary you can declare additional namespace mappings using
xmlns(), like this:
It is possible to include the result of an XQuery script by XInclude. If the target of an
XInclude reference points to an XQuery document stored in the database (binary resource with
application/xquery), the XInclude processor will attempt to compile and
execute this query and use its results.
The XInclude processor declares two variables in the XQuery's static context:
The name of the document which XInclude-s the query (without its collection path)
the collection in which the current document resides
You can also pass additional parameters to the XQuery script:
var2 will be available to
the XQuery as an external global variable. The XQuery needs to declare them:
An error is raised if you try to XInclude a resource which does not exist. You can specify
a fallback to avoid this. The result of the XInclude will be the content of the
A fallback element itself cannot contain XInclude elements.
One reason why the XPointer spec has hardly seen any implementation is that it operates
with "points" and "locations" which have no equivalent in the XPath Data Model. However, a
major use case for the XPointer specification is to allow pointing at a range of characters
inside an element. Luckily, we can work around the absence of this using the XPath functions
In the following example, a range of characters in the text node of a
element is extracted, 20 characters long, starting at the 22nd character:
Since only string contents is involved, these ranges can also work on text nodes belonging to different elements. In the following example, parts of succeeding lines are extracted from the SPEECH element: