The xsl:document Element: Generating Multiple Result Documents

The <xsl:document> Element: Generating Multiple Result Documents

A common thing to want to do is create multiple result documents during a transformation. For example, you might want to create a report indicating how the transformation went, or split an input document up into multiple result documents (such as splitting a novel into chapters). Or, you might want to create a result document set that is meant to be used together (such as when you create an HTML frameset document) along with two documents to be displayed in the frames .

Creating multiple result documents is such a common thing to do that nearly all XSLT processors enable you to do it, even in XSLT 1.0, where theres no special support for this task. XSLT processors add new extension elements to do this. For example, Xalan includes a <write> element that enables you to write to a new result document. To use this element, you create a new namespace prefixIll use xalan herefor the namespace Xalan uses for this element, com.lotus.xsl.extensions.Redirect, and indicate that this new prefix is an extension element prefix:

 <?xml version="1.0"?>  <xsl:stylesheet version="1.1"      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"      xmlns:xalan="com.lotus.xsl.extensions.Redirect"      extension-element-prefixes="xalan">          .          .          . 

Now I can use the <xalan:write> elements file attribute to write to a new file:

 <?xml version="1.0"?>  <xsl:stylesheet version="1.1"      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"      xmlns:xalan="com.lotus.xsl.extensions.Redirect"      extension-element-prefixes="xalan">          .          .          .  <xalan:write file="newdoc.txt">      <xsl:text>Here's some text.</xsl:text>  </xalan:write> 

In Saxon, you use the <output> element; I use the prefix saxon for this element, which corresponds to the URI http://icl.com/saxon:

 <?xml version="1.0"?>  <xsl:stylesheet version="1.1"      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"      xmlns:saxon="http://icl.com/saxon"      extension-element-prefixes="saxon">          .          .          .  <saxon:output file="newdoc.txt">      <xsl:text>Here's some text.</xsl:text>  </saxon:output> 

You can also do the same thing in XT; in this case, you use the namespace http://www.jclark.com/xt with the <document> element and use the href attribute to specify the name of the new file:

 <?xml version="1.0"?>  <xsl:stylesheet version="1.1"      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"      xmlns:xt="http://www.jclark.com/xt"      extension-element-prefixes="xt">          .          .          .  <xt:document href="newdoc.txt">      <xsl:text>Here's some text.</xsl:text>  </xt:document> 

All this makes for quite a jungle of standards, because everyone has created their own implementations . For this reason, XSLT 1.1 introduced a new element, <xsl:document> , to support multiple result documents. This element has the following attributes:

• href (mandatory). Indicates where the new document should be placed. You set this to an absolute or relative URI, without a fragment identifier.

• method (optional). Sets the output method used to create the result document. Set to xml, html, text, or a QName that is not an NCName.

• version (optional). Sets the version of the output document. Set to an NMTOKEN.

• encoding (optional) Sets the encoding of the output document. Set to a string.

• omit-xml-declaration (optional). Set to yes or no to omit the XML declaration or not.

• cdata-section-elements (optional). Sets the names of those elements whose content you want output as CDATA sections. Set to a whitespace-separated list of QNames.

• doctype-public (optional). Specifies the public identifier to be used in the <!DOCTYPE> declaration in the output. Set to a string value.

• doctype-system (optional). Specifies the system identifier to be used in the <!DOCTYPE> declaration in the output. Set to a string value.

• encoding (optional). Sets the character encoding. Set to a string value.

• indent (optional). Specifies whether the output should be indented to show its nesting structure. Set to yes or no.

• media-type (optional). Sets the MIME type of the output. Set to a string value.

• standalone (optional). Specifies whether a standalone declaration should be included in the output and sets its value if so. Set to yes or no.

This element contains a template body.

The following example is based on a simplified stylesheet. In this case, I create two frames in an HTML document, as well as the two HTML documents that are to be displayed in those frames (frame1.html and frame2.html). I create the first frame and the document that will appear in it as follows :

 <HTML>      <HEAD>          <TITLE>              Two Frames          </TITLE>      </HEAD>      <FRAMESET cols="50%, 50%">          <FRAME src="frame1.html"/>          <xsl:document href="frame1.html">              <HTML>                  <HEAD>                      <TITLE>                          Frame 1                      </TITLE>                  </HEAD>                  <BODY>                      <H1>This is frame 1.</H1>                  </BODY>              </HTML>          </xsl:document>          .          .          . 

Then I can create the second frame and the document that will appear in that frame in this way:

 <HTML>      <HEAD>          <TITLE>              Two Frames          </TITLE>      </HEAD>      <FRAMESET cols="50%, 50%">          <FRAME src="frame1.html"/>          <xsl:document href="frame1.html">              <HTML>                  <HEAD>                      <TITLE>                          Frame 1                      </TITLE>                  </HEAD>                  <BODY>                      <H1>This is frame 1.</H1>                  </BODY>              </HTML>          </xsl:document>        <FRAME src="frame2.html"/>         <xsl:document href="frame2.html">              <HTML>                  <HEAD>                      <TITLE>                          Frame 2                      </TITLE>                  </HEAD>                  <BODY>                      <H1>This is frame 2.</H1>                  </BODY>              </HTML>          </xsl:document>      </FRAMESET>    </HTML> 

Note, however, that this is an XSLT 1.1-only example.

As Im writing this, one XSLT processor seems to have implemented <xsl:document> : Saxon version 6.2.1 and later, which has changed its <saxon:output> element to <xsl:document> . Thats the only XSLT processor I know of, however, that handles this element so far.