EXSLT - exsl:document

Implementer Page: exsl.document.html
Element Package: exsl.document.zip

Element Syntax

<exsl:document
   href = { uri-reference }
   method = { "xml" | "html" | "text" | qname-but-not-ncname }
   version = { nmtoken }
   encoding = { string }
   omit-xml-declaration = { "yes" | "no" }
   standalone = { "yes" | "no" }
   doctype-public = { string }
   doctype-system = { string }
   cdata-section-elements = { qnames }
   indent = { "yes" | "no" }
   media-type = { string }>
   <-- Content: template -->
</exsl:document>

The exsl:document element is used to create multiple result documents. As well as the main result document, there can be subsidiary result documents. Each subsidiary result document is created using an exsl:document element. The content of the exsl:document element is a template; this is instantiated to create a sequence of nodes; a root node is created with this sequence of nodes as its children; the tree with this root node represents the subsidiary result document. The href attribute specifies where the subsidiary document should be stored; it must be an absolute or relative URI; it must not have a fragment identifier. For example, the following would create a main result document specifying an HTML frameset with two frames, together with two subsidiary documents, one for the contents of each frame:

<xsl:template match="/">
  <html>
    <head><title>Frame example</title></head>
    <frameset cols="20%, 80%">
      <frame src="toc.html"/>
      <exsl:document href="toc.html">
        <html>
          <head><title>Table of Contents</title></head>
          <body>
             <xsl:apply-templates mode="toc" select="*"/>
          </body>
        </html>
      </exsl:document>
      <frame src="body.html"/>
      <exsl:document href="body.html">
        <html>
          <head><title>Body</title></head>
          <body>
             <xsl:apply-templates select="*"/>
          </body>
        </html>
      </exsl:document>
    </frameset>
  </html>
</xsl:template>

The attributes on xsl:output elements affect only the main result document. The output of a subsidiary result document is controlled by the attributes on the exsl:document element that was used to create that subsidiary result document. With the exception of the href attribute which is allowed only on exsl:document, the attributes on exsl:document are applied to a subsidiary result document in the same way that the attributes on xsl:output are applied to the main result document. In particular, the method attribute on an exsl:document element is defaulted based on the content of the subsidiary document created by that exsl:document element, not based on the content of the main result document.

Normally, exsl:document can be understood as directly creating an additional result document. However, when exsl:document is used within xsl:variable or xsl:param elements, the following more sophisticated conceptual model is needed.

Documents involved in XSLT processing can be divided into two categories.

One category contains the documents that the XSLT processor constructs by instantiating templates; these are the main result document, subsidiary documents created by exsl:document, and documents created by a variable-binding element with content.

The other category contains the documents constructed by parsing or other processes external to the XSLT processor; these are the main source document and documents returned by the document function.

With each document in the former category, an XSLT processor associates a possibly empty set of subsidiary documents. The relationship between a document and its associated subsidiary documents thus organizes documents in this category into one or more unordered trees, where the associated subsidiary documents of a document are considered the children of that document. The main result document is the root of one such tree; the documents created by variable-binding elements with content are the roots of the other trees. Each subsidiary document created by an exsl:document element has a parent within this tree of documents.

During the processing of a stylesheet, there is a current result document; initially this is the main result document; the current result document is changed by the exsl:document element and by variable-binding elements with content. When an exsl:document element is instantiated, the content is instantiated with the subsidiary document being created by that exsl:document element as the current result document. When a variable-binding element with content is instantiated, the content is instantiated with the document being created (that is, the document whose root node is the sole member of the node-set that will be the value of the variable defined by that element) as the current result document. A document created by the instantiation of an exsl:document is not automatically output; instead, it is added to the set of subsidiary documents associated with the current result document.

NOTE: The exsl:document is allowed inside xsl:attribute, xsl:comment and xsl:processing-instruction and behaves in those contexts in the same way as elsewhere.

Issue (message-document): What should happen if exsl:document occurs inside xsl:message?

When a root node is copied with xsl:copy or xsl:copy-of, the subsidiary documents associated with the document of which it is the root node are copied and added to the set of subsidiary documents associated with the current result document. Copying a subsidiary document copies its subsidiary documents recursively.

Output conceptually follows the construction of the main result document and any subsidiary documents. The XSLT processor outputs the main result document and its associated subsidiary documents; when the XSLT processor outputs a subsidiary document it also recursively outputs its associated subsidiary documents. Apart from this, no other subsidiary documents are output. A subsidiary document associated with the document created by a variable-binding element with content is not output; only copies created by the copying of the root node of that document are ever output.

For each document that is output, there is an absolute URI that can, in the appropriate circumstances, be used to access that document. Call this the output URI of the document. The output URI of the main result document is system-dependent, typically specified when the XSLT processor is invoked. When the href attribute of a subsidiary document is an absolute URI, then that absolute URI serves as the output URI. When the href attribute of a subsidiary document is a relative URI, the relative URI is resolved into an absolute URI only if and when the subsidiary document is output. The output URI of the document with which the subsidiary document is associated (ie the output URI of its parent in the tree of documents) is used as the base URI. The resulting absolute URI is used as the output URI of the subsidiary document.

NOTE: The output URI of a document is not dependent on the base URI of the root node of the document.

It is an error if the set of documents to be output as the result of a single XSLT transformation (that is, the main result document and its subsidiary documents recursively) contain two documents with the same output URI.

Implementations

The following XSLT processors support exsl:document:

libxslt from Daniel Veillard; implementation by Thomas Broyer (version 1.0.19)

There are currently no third-party implementations of exsl:document.