Beginning with version 0.9, eXist comes with partial support for the XInclude standard. If configured, the server will scan a document stored in the database for XInclude tags and expand those tags if possible. The expansion is applied during the serialization of the document, i.e. whenever you retrieve a document containing XInclude tags.
eXist's support for XInclude is not complete. You cannot include raw text, just XML. The fallback element is ignored. Also just basic XPath is allowed for XPointers.
Why do we need XInclude? One reason is that eXist does not preserve entity declarations. Entities are resolved by the XML parser, so eXist just sees the expanded text, not the entity itself. However, external entities are handy if you want to include a given fragment at several locations in different files. For example, the navigation sidebar at the left will probably be used by several documents throughout a site, so it would be wise to keep it in an external file.
XInclude provides a powerful alternative. The following sections present some examples.
If you came here from the examples page, you are already looking at a page that has been passed through XInclude, and you can see the live effect of all the examples below. If not, try to browse to
and continue to read there.
By the way, this page also demonstrates some of the possibilities of eXist's REST interface. All the files required to render this page reside in the database and are read from there, including the two XSLT stylesheets used for the formatting.
To include an entire document, just specify its path in the href attribute of an <xi:include> tag. For example, the sidebar shown at the left of this documents has been included as follows:
Please note that, as usual, you have to provide the correct namespace for XInclude, e.g. in the root element of the document. The official namespace is:
The fragment part of the URI reference in the href attribute is interpreted as an XPointer. If the fragment is just a barename - now called shorthand pointer - it will select the first element of the target document that has an attribute of type ID matching the name. For example, the following xinclude selects the p element from file disclaimer.xml, which has an ID attribute with value "statement".
The result of the XInclude will be displayed below:
We may also use an XPath expression to select fragments. The XPath expression is passed to the xpointer() scheme. The results of the expression will be included in place of the <xi:include> element. The following expression includes a section taken from Shakespeare's Macbeth:
As before, the results are included below:
An XPath expression will be applied to the entire collection if the path in href points to a collection and not a single document:
Test namespaces: all namespace/prefix mappings declared in the source document are passed to the query context. Alternatively, you may declare mappings with xmlns().
