13.3 Using the document( ) Function

You have already been introduced to how the document( ) function works in examples from Chapters 5 and 9. This section will reintroduce some of the concepts discussed earlier, plus a few more. The following examples will focus on the text of the Book of Jonah, excerpted from the King James version of the Bible.

I'll start this discussion by showing you a stub of a document, bible.xml:

<?xml version="1.0" encoding="UTF-8"?>     <volume>  <book/> </volume>

There is not much to it. You can get bible.xml to do something interesting with Example 13-13, the stylesheet jonah.xsl.

Example 13-13. A stylesheet that copies in a separate document

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="xml" indent="yes"/>     <xsl:template match="volume">  <xsl:copy>   <xsl:attribute name="name">Old Testament</xsl:attribute>   <xsl:apply-templates select="book"/>  </xsl:copy> </xsl:template>     <xsl:template match="book">  <xsl:copy>   <xsl:attribute name="name">Jonah</xsl:attribute>   <xsl:copy-of select="document('jonah1.xml')"/>  </xsl:copy> </xsl:template>     </xsl:stylesheet>

Applying this stylesheet to bible.xml will produce the first chapter of Jonah in XML markup. It makes shallow copies of the volume and book nodes in bible.xml, adding name attributes to each. Then, using copy-of, it makes a deep copy of all the nodes in the document jonah1.xml, which contains the text of the first chapter of the Book of Jonah from the Old Testament, surrounded by XML elements. copy-of finds the nodes in jonah1.xml with the document( ) function.

The document( ) function must have at least one argument, but it can have two. The first argument must be an object, the second must be a node-set. The second argument of document( ) is rarely used. The first argument is usually a literal string that is the URI of the source document you are including, either as a relative filename or as a URI, or it is a node in the source document that contains a link to the required document.

In jonah.xsl, document( ) uses only one argument, the string jonah1.xml. The XSLT processor knows where to find the document jonah1.xml because it uses the location of the stylesheet as a base URI (the argument is a string). In other words, because it knows internally where the stylesheet is located on the filesystem, it looks for jonah1.xml relative to the location of the stylesheet, that is, in the same directory as the stylesheet. You could also use an absolute URI path for the file, as in document('file:///C:/learningxslt/examples/ch13/jonah1.xml').

Here are a few lines of jonah1.xml:

<chapter number="1"> <verse number="1">Now the word of the LORD came unto Jonah the son of Amittai, saying,</verse> <verse number="2">Arise, go to Nineveh, that great city, and cry against it;  for their wickedness is come up before me.</verse>

Apply jonah.xsl to bible.xml using this command:

xalan bible.xml jonah.xsl

You will get output that looks similar to the following (this is a clipped version of the output):

<?xml version="1.0" encoding="UTF-8"?> <volume name="Old Testament"> <book name="Jonah"> <chapter number="1"> <verse number="1">Now the word of the LORD came unto Jonah the son of Amittai,  saying,</verse> <verse number="2">Arise, go to Nineveh, that great city, and cry against it; for  their wickedness is come up before me.</verse>

The chapter and verse nodes are all pulled into the result tree using document( ).

Now look at the document jonahMap.xml:

<?xml version="1.0" encoding="UTF-8"?>     <volume name="Old Testament">  <book name="Jonah">   <chapter location="jonah1.xml"/>   <chapter location="jonah2.xml"/>   <chapter location="jonah3.xml"/>   <chapter location="jonah4.xml"/>  </book> </volume>

The location attributes in jonahMap.xml contain the relative path names to the four files containing the four chapters of the Book of Jonah, respectively. The document( ) function can use the location attributes in the current context to find these files, as shown in Example 13-14, jonahMap.xsl.

Example 13-14. Applying the document( ) function to data from a source document

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="xml" indent="yes"/>     <xsl:template match="volume">  <xsl:copy>   <xsl:attribute name="name"><xsl:value-of select="@name"/></xsl:attribute>   <xsl:apply-templates select="book"/>  </xsl:copy> </xsl:template>     <xsl:template match="book">  <xsl:copy>   <xsl:attribute name="name"><xsl:value-of select="@name"/></xsl:attribute>   <xsl:apply-templates select="chapter"/>  </xsl:copy> </xsl:template>     <xsl:template match="chapter">  <xsl:copy-of select="document(@location)"/> </xsl:template>     </xsl:stylesheet>

In this instance of document( ), the object in the argument is an XPath location path for the location attributes on the chapter elements in the source tree. Also in this instance, the relative URI is interpreted as being relative to the base URI of chapter elements in the source document, not relative to the stylesheet.

When you apply jonahMap.xsl to jonahMap.xml with:

xalan jonahMap.xml jonahMap.xsl

all the chapters of Jonah will appear in the result. (The stylesheet, by the way, also takes the values of the name attributes from volume and book and places these values in the result.)

In the next example, Example 13-15, the document( ) function is used in conjunction with nodes found in the accessed document (as shown earlier in the book). The jonahVerse.xsl stylesheet prints verses from any of the files jonah1.xml, jonah2.xml, jonah3.xml, or jonah4.xml.

Example 13-15. Extracting information using document( ) function and parameters

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:include href="wspace.xsl"/> <xsl:output method="text"/> <xsl:strip-space elements="*"/> <xsl:param name="chap" select="1"/> <xsl:param name="ver" select="1"/>     <xsl:template match="volume/book">  <xsl:choose>   <xsl:when test="$chap = 1 and $ver &lt; 18">    <xsl:call-template name="cite"/>    <xsl:value-of select="document('jonah1.xml')/chapter/verse[@number=$ver]"/>   </xsl:when>   <xsl:when test="$chap = 2 and $ver &lt; 11">    <xsl:call-template name="cite"/>    <xsl:value-of select="document('jonah2.xml')/chapter/verse[@number=$ver]"/>   </xsl:when>   <xsl:when test="$chap = 3 and $ver &lt; 11">    <xsl:call-template name="cite"/>    <xsl:value-of select="document('jonah3.xml')/chapter/verse[@number=$ver]"/>   </xsl:when>   <xsl:when test="$chap = 4 and $ver &lt; 12">    <xsl:call-template name="cite"/>    <xsl:value-of select="document('jonah4.xml')/chapter/verse[@number=$ver]"/>   </xsl:when>   <xsl:otherwise>Not found!</xsl:otherwise>  </xsl:choose> </xsl:template>     <xsl:template name="cite">  <xsl:text>The Book of Jonah</xsl:text>  <xsl:call-template name="n1"/>  <xsl:text>Chapter </xsl:text>  <xsl:value-of select="$chap"/>  <xsl:text>, verse </xsl:text>  <xsl:value-of select="$ver"/>  <xsl:text>: </xsl:text>  <xsl:call-template name="n2"/> </xsl:template>     </xsl:stylesheet>

The stylesheet includes wspace.xsl so it can call templates from it (the ones named n1 and n2). The parameters chap and ver default to 1, that is, to Chapter 1, verse 1 of Jonah. The test attribute on the when elements checks to see what chapter you want to refer to and then uses that number to bring up a given file. It also makes sure that you don't request a verse that is out of range for a given chapter. If any of these tests return false, the otherwise element returns Not found! and the processor exits without doing anything else. If a verse is found, the cite template writes the citation and the verse to the result tree.

Try it. Enter the following command passing in values for the chap and ver parameters:

xalan -p chap '2' -p ver '8' bible.xml jonahVerse.xsl

which will return:

The Book of Jonah Chapter 2, verse 8:     They that observe lying vanities forsake their own mercy.

There are several other ways besides those shown to use document( ) with two arguments, but frankly, they are difficult to explain and are neither common nor very useful.