9.1. The <xsl:copy-of> Instruction Element

The <xsl:copy-of> instruction element is used to create a copy of a node branch, or subtree, from the input tree. It is an empty element that has one required attribute, select, which contains an expression, as shown in the following element model definition:

<!-- Category: instruction -->

<xsl:copy-of

  select = expression />

When the expression in the select attribute is evaluated, the resulting object is copied to the output result tree. However, what is copied depends on the type of object produced by the expression.

If the expression produces either a node-set or an RTF, <xsl:copy-of> will copy each node in the node-set or RTF, including markup, children elements, and descendents of the node, and place the results in the output result tree. Attributes, namespaces, text, PIs, and comments in the node-set are also copied. The <xsl:copy-of> instruction element effectively “transplants” a node branch to the output result tree. If the select attribute matches a root, or document root node (/), then that root and its children and descendants are copied to the output result tree.

If the expression in the select attribute returns any object other than a node-set or RTF, then that object is converted to a string and copied to the output.

It is important to know that <xsl:copy-of> does not allow you to perform operations on the object returned by the expression before sending it to the output. It is, effectively, a “cut-and-paste” of the matched node. For example, it is not possible to selectively exclude some of the nodes, or to include new elements with LREs. For this reason the <xsl:copy-of> element is empty.

The stylesheet shown in Example 9-1 shows the use of <xsl:copy-of> with a pattern to select the <thoroughfare> elements and copy them into a new element-type name. Because the pattern returns a node-set, the entire <thoroughfare> node is copied for each match.

Example 9-1. Using <xsl:copy-of> to copy a node branch.

					INPUT:

<?xml version="1.0"?>
<main>
      <parkway>
            <thoroughfare>Governor Drive</thoroughfare>
            <thoroughfare name="Whitesburg Drive">
                  <sidestreet>Bob Wallace Avenue</sidestreet>
                  <block>1st Street</block>
                  <block>2nd Street</block>
                  <block>3rd Street</block>
                  <sidestreet>Woodridge Street</sidestreet>
            </thoroughfare>
            <thoroughfare name="Bankhead">
                  <sidestreet>Tollgate Road</sidestreet>
                  <block>First Street</block>
                  <block>Second Street</block>
                  <block>Third Street</block>
                  <sidestreet>Oak Drive</sidestreet>
            </thoroughfare>
      </parkway>
      <boulevard>
            <block>Panorama Street</block>
            <block>Highland Plaza</block>
            <block>Hutchens Avenue</block>
            <block>Wildwood Drive</block>
            <block>Old Chimney Road</block>
            <block>Carrol Circle</block>
      </boulevard>
</main>

STYLESHEET:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">
<xsl:template match="boulevard"/>
<xsl:template match="parkway">
      <new-parkway>
<xsl:copy-of select="thoroughfare"/>
      </new-parkway>
</xsl:template>
</xsl:stylesheet>
RESULT:

<?xml version="1.0" encoding="utf-8"?>
<new-parkway>
<thoroughfare>Governor Drive</thoroughfare>
<thoroughfare name="Whitesburg Drive">
<sidestreet>Bob Wallace Avenue</sidestreet>
<block>1st Street</block>
<block>2nd Street</block>
<block>3rd Street</block>
<sidestreet>Woodridge Street</sidestreet>
</thoroughfare>
<thoroughfare name="Bankhead">
<sidestreet>Tollgate Road</sidestreet>
<block>First Street</block>
<block>Second Street</block>
<block>Third Street</block>
<sidestreet>Oak Drive</sidestreet>
</thoroughfare>
</new-parkway>

This example shows two template rules: <xsl:template match="boulevard"/> to match the <boulevard> element and suppress its contents, and <xsl:template match="parkway"> to match the <parkway> element and replace it with the <new-parkway> element. The template rule that matches on <parkway> contains an LRE for the <new-parkway> and uses the <xsl:copy-of select="thoroughfare"/> to send each <thoroughfare> element to the output result tree.