XSLTForms/include

Description
The  element includes external files in a form at compile time, during the evaluation of the   stylesheet. It is thus similar in functionality to general entities in XML, or to the XInclude  element.

It can be used to reduce duplication of code at multiple points in a form, to share code between forms, or just to move a complex part of a subform into a separate document to make the logic of the main form clearer and easier to follow.

Syntax
The  element is empty. It carries just one attribute:.

The value of the  attribute is a URI reference (absolute or relative) pointing to an XML document to be included in the form.

Repeated code within a form
Consider an XForm which accepts query data from a user, submits a query to a back end search engine, and displays the results to the user. To avoid overloading the user's browser and/or the network, we wish to send only a page's worth of results to the user at any one time, and allow the user to page through the results, so-and-so many results at a time.

The general outline of such a form might be something like this; we assume an instance named  to hold the query string and the starting position within the results, and an instance named   to hold the results.

To reduce the need for scrolling up and down in the results page, we wish to have buttons for moving forward and back in the results both at the top of the results list and at the bottom. The code will be the same for both: first a Back button, which displays only if the current starting position is greater than 1:

Then a message indicating location in the results (e.g. "11 to 20 of 34", or "No results"):

And finally a Forward button, which displays only if we are not currently displaying the last hit:

Note that the forward and back buttons, and the current-location message, have no IDs that need to be unique; there is no problem including their text twice in the form. To make that happen, we must


 * 1) Make an XML document containing the Back button, the location message, and the Forward button.  We wrap these three elements in an XHTML   element to give the XML a single root element, and call the result file "FBButtons.xhtml".
 * 2) In the appropriate locations in the main form, use the   element with the appropriate   value.  If "FBButtons.xhtml" was placed in the same directory as the main form, we'll use.

Known problems and issues

 * The  element works as specified in the main XForm, and recursively in documents loaded via  .  In subforms, which are loaded later, it works in some browsers but not in others (including Webkit-based browsers).  Cause of this discrepancy is the unwillingness of some browsers to evaluate the XSLT   function in XSLT stylesheets invoked from Javascript, which is motivated by security concerns of some description.
 * Browsers will enforce the same-origin policy, which means the absolute URI pointing to the XML document to be include will need to be on the same host as the form itself. [Tests and empirical confirmation of this claim would be desirable.]

For further information

 * Alain Couthures to xsltforms-support list, 3 Jul 2016 explaining problems with use of  in subforms.
 * Sample form showing use of  in main form and in dynamically loaded subform; the latter does not work.