XML Inclusions (XInclude)

User Guide / XML Input

XML Inclusions (XInclude) provides a method of including content from other files into an XML document. When Prince processes the XML document, the inclusions are resolved and the included content is treated as if it had been in the original document all along.

The core of XInclude is a single element, <include href="..."/>, which specifies the inclusion of the file referenced by the href attribute. The element is in the XInclude namespace, http://www.w3.org/2001/XInclude, which must be declared either on the element itself or one of its ancestor elements.

Including XML files

Here is an example of a book written in XHTML in which each chapter has been placed in a separate XML document for convenient editing and then included in the main document using XInclude:

<html xmlns:xi="http://www.w3.org/2001/XInclude">
<head>
<title>Book Title</title>
</head>
<body>
<xi:include href="chap1.xml"/>
<xi:include href="chap2.xml"/>
<xi:include href="chap3.xml"/>
</body>
</html>

(Note that the XInclude namespace was defined on the root element and bound to the xi prefix to save space by avoiding the need to declare the namespace on every inclusion).

Including text files

XInclude can also be used to include text files into XML documents:

<xi:include href="file.txt" parse="text"/>

This is a convenient way of including files containing arbitrary non-XML text, such as emails, database reports or program source code. It also allows the inclusion of external XML content as "unparsed text", as if all the markup had been explicitly escaped with character entities or placed in a CDATA section.

Fallback

It is possible to specify fallback content that should be used if an included file cannot be loaded. The fallback content can be arbitrary XML and may even contain additional inclusions.

<xi:include href="report.html">
    <xi:fallback>
	<p>No report is available</p>
    </xi:fallback>
</xi:include>

If the report.html file cannot be loaded then the paragraph saying "No report is available" will be included in the document instead.