XInclude and Document Assembly

XInclude merges documents: <xi:include href="..."> is replaced by the resource it names, parsed as XML (the default, optionally narrowed by xpointer) or inserted as text (parse="text"), and an <xi:fallback> child supplies content when the resource is missing. Use the namespace http://www.w3.org/2001/XInclude 189 : older examples show a 2003 draft namespace that libxml2 3,427 still accepts but Saxon 726,956 silently ignores. Here the catalog is assembled from parts, one of them missing:

Assembling a document with XInclude, a text include and a fallbackShell

mkdir -p parts
printf '<book id="b1"><title>The Quiet Harbor</title></book>\n' > parts/fiction.xml
printf 'Prices in USD; sample data.\n' > parts/notice.txt
cat > assembled.xml <<'EOF'
<catalog xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="parts/fiction.xml"/>
  <note><xi:include href="parts/notice.txt" parse="text"/></note>
  <xi:include href="parts/travel.xml">
    <xi:fallback><note>No travel feed today.</note></xi:fallback>
  </xi:include>
</catalog>
EOF
xmllint --xinclude assembled.xml 2>&1 | grep -v "I/O warning"

Output

<?xml version="1.0"?>
<catalog xmlns:xi="http://www.w3.org/2001/XInclude">
  <book id="b1" xml:base="parts/fiction.xml"><title>The Quiet Harbor</title></book>
  <note>Prices in USD; sample data.
</note>
  <note>No travel feed today.</note>
</catalog>

The included <book> gained xml:base="parts/fiction.xml", a base URI fixup that keeps its relative links working; the missing file fell back with only a warning. libxml2, Saxon (-xi:on) and lxml 3,063 (tree.xinclude()) include only when asked, the safe default: inclusion reads files the document names, so never enable it on untrusted input (XML Security). XInclude 1.1, a 2016 Working Group Note adding a fragid attribute, was never widely implemented.

XInclude

XInclude is a generic mechanism for merging XML documents. The valid values for the attribute 'parse' are 'text' and 'xml'. Like XLink, its special namespace should be declared before it is used. For a working PHP example, see PHP Integration.

Range Inclusion

The following demonstrates range inclusion: the document invoking XInclude, the source document referenced ('source.xml'), and the resulting XML obtained.

ch02-xinclude-range-doc.xml, ch02-xinclude-range-source.xml, ch02-xinclude-range-result.xmlXML

<?xml version='1.0'?>
<document>
  <p>The relevant excerpt is:</p>
  <quotation>
    <include xmlns="http://www.w3.org/2001/XInclude"
             href="source.xml"
             xpointer="xpointer(string-range(chapter/p[1],'Sentence 2')/range-to(string-range(/chapter/p[2]/i,'3.',1,2)))"/>
  </quotation>
</document>

<?xml version='1.0'?>
<chapter>
  <p>Sentence 1.  Sentence 2.</p>
  <p><i>Sentence 3.  Sentence 4.</i>  Sentence 5.</p>
</chapter>

<?xml version='1.0'?>
<document>
  <p>The relevant excerpt is:</p>
  <quotation>
    <p xml:base="http://www.example.com/source.xml"> Sentence 2.</p>
    <p xml:base="http://www.example.com/source.xml"><i>Sentence 3.</i></p>
  </quotation>
</document>

(Courtesy of http://www.w3.org/TR/xinclude/#examples 189 )

Fallback

The following demonstrates fallback. If neither example.txt nor fallback-example.txt is available, the XML obtained is shown below.

ch02-xinclude-fallback-doc.xml, ch02-xinclude-fallback-result.xmlXML

<?xml version='1.0'?>
<div>
  <xi:include href="example.txt" parse="text"
    xmlns:xi="http://www.w3.org/2001/XInclude">
     <xi:fallback>
        <xi:include href="fallback-example.txt" parse="text">
           <xi:fallback>
              <a href="mailto:bob@example.org">Report error</a>
           </xi:fallback>
        </xi:include>
     </xi:fallback>
  </xi:include>
</div>

<?xml version='1.0'?>
<div>
  <a href="mailto:bob@example.org">Report error</a>
</div>

(Courtesy of http://www.w3.org/TR/xinclude/#examples 189 )

Currently, browsers do not support XLink and XPointer in general. However, they support simple XLinks in SVG.

MENU

XInclude

Range Inclusion

Fallback