There are two ways to use XInclude explicitly in Orbeon Forms:

• At parsing time. The XML parser included with Orbeon Forms is able to process XInclude instructions when an XML file is being parsed (i.e. loaded) into Orbeon Forms. This is usually controlled with the URL generator. Example:

  <p:processor name="oxf:url-generator"><p:input name="config"><config><url>oxf:/some-document.xml</url><handle-xinclude>true</handle-xinclude></config></p:input><p:output name="data" id="processed-document"/></p:processor>

• With the XInclude processor. The processor documented here allows to explicitly control the use of XInclude instructions in any XML document, including documents that are not loaded with the URL generator, but dynamically generated. Example:

  <p:processor name="oxf:xinclude"><p:input name="config" href="oxf:/some-document.xml"/><p:output name="data" id="processed-document"/></p:processor>

  This example is equivalent to the example using the URL generator.

XInclude processing is implicit in the following cases:

• Page Flow Controller (PFC) Components. PFC page models, page views, and actions automatically go through XInclude processing. This in particular allows for using XInclude in static XHTML or dynamic XSLT page views. In this case, XInclude can make use of the special URIs input:data and input:instance to access data and instance documents fed to the page view.

  Note

  Because the PFC automatically processes XInclude statements in page components, the user should be careful when using XInclude statements in XPL pipelines for such components. It should be understood that XInclude processing in this case takes place upon loading the XPL pipeline.

• XPL Processor Definitions. Processor definitions (usually stored in a file called processors.xml) may use XInclude.

• Logging Configuration. Logging configuration (usually stored in a file called log4j.xml) may use XInclude.

It must be noted that, in particular, XInclude processing is not implicit in the following cases:

• XPL href attribute. In the following example:

  <p:input name="my-input-name" href="some-document.xml"/>

  In this case, the content of some-document.xml will not be processed by XInclude before being sent to the my-input-name input.

• XPL schema-href attribute. Similarly, XML schemas do not go through XInclude processing.

The config input receives an XML document which may contain XInclude elements. If it doesn't contain any XInclude elements, the content of the document will be produced without modifications on the XInclude processor's data output.

The main XInclude element is xi:include. The prefix, usually xi, must be bound to the namespace http://www.w3.org/2001/XInclude. xi:include takes a mandatory href attribute, which must contain an URL such as an oxf:, file: or http: URL. In addition, URIs of the form input:* are supported, to allow access to user-defined inputs connected to the XInclude processor.

This is a fragment of an XForms page using XInclude, in a resource named view.xhtml:

With the example above, the resource main-xforms-instance.xml can contain:

The processor is configured as follows:

The result of the inclusion on the data output is:

Notice how the xi:include element has been replaced with the entire content of the included file. In addition, a new xml:base attribute has been added, as per the XInclude specification. It specifies the base URI that must be used to resolve relative URIs in the included document.

An included document may in turn use further xi:include elements to perform nested inclusions.

It is possible to tell the XInclude processor not to produce xml:base on an inclusion by using the xxi:omit-xml-base extension attribute (the XInclude errata now allow such a feature to be provided by implementations). The attribute takes value false (the default) or true, and the namespace must be mapped for example using xmlns:xxi="http://orbeon.org/oxf/xml/xinclude". Example:

This produces:

Notice how there is no longer an xml:base attribute at the point of inclusion. This can be quite useful when performing schema validation on the result, or when xml:base resolution on the result must be performed relative to the URL base of the including document.

User-defined inputs allow the XInclude processor do include dynamically generated XML documents. For example, connecting the XInclude processor as follows:

It is possible to include the XML document available on the custom my-dynamic-content input by using input:* URIs, for example with the following document as the config input:

This makes the XInclude processor very versatile as a simple template processor.