10.3 Using Templates with Parameters

For the purposes of XSLT, a parameter is a name that can be bound to a value and then later referenced by name. You learned about this in Chapter 7. You can use the with-param element as a child element of either apply-templates or call-template to pass a parameter into a template. For example, a template could be invoked several times, each time with a different parameter value, thus changing what happens when the template is invoked. Watch what happens when a stylesheet calls a template with four different parameter values.

Example 10-10, yukon.xml, lists cities in Canada's Yukon Territory.

Example 10-10. A list of cities in the Yukon

<?xml version="1.0" encoding="UTF-8"?>     <province name="Yukon Territory">  <city>Beaver Creek</city>  <city>Carcross</city>  <city>Carmacks</city>  <city>Dawson</city>  <city>Faro</city>  <city>Haines Junction</city>  <city>Mayo</city>  <city>Ross River</city>  <city>Teslin</city>  <city>Watson Lake</city>  <city>Whitehorse</city> </province>

The stylesheet in Example 10-11, yukon.xsl, processes yukon.xml with each instance of call-template passing a different value for the parameter nl.

Example 10-11. Processing cities with call-template

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="text"/>     <xsl:template match="province">  <xsl:text>Yukon Territory Cities</xsl:text>  <xsl:call-template name="nl">   <xsl:with-param name="nl" select="'&#10;&#10;'"/>  </xsl:call-template>  <xsl:apply-templates select="city"/> </xsl:template>     <xsl:template match="city">  <xsl:text> -> </xsl:text>  <xsl:value-of select="."/>  <xsl:call-template name="nl">   <xsl:with-param name="nl" select="'&#10;'"/>  </xsl:call-template> </xsl:template>     <xsl:template match="city[.='Dawson']">  <xsl:text> -> </xsl:text>  <xsl:value-of select="."/>  <xsl:call-template name="nl">   <xsl:with-param name="nl" select="' (second largest city in the Yukon)&#10;'"/>  </xsl:call-template> </xsl:template>     <xsl:template match="city[.='Whitehorse']">  <xsl:text> -> </xsl:text>  <xsl:value-of select="."/>  <xsl:call-template name="nl">   <xsl:with-param name="nl" select="' (largest city in the Yukon)&#10;'"/>  </xsl:call-template> </xsl:template>     <xsl:template name="nl">  <xsl:param name="nl"/>  <xsl:value-of select="$nl"/> </xsl:template>     </xsl:stylesheet>

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

xalan yukon.xml yukon.xsl

you produce this result:

Yukon Territory Cities      -> Beaver Creek  -> Carcross  -> Carmacks  -> Dawson (second largest city in the Yukon)  -> Faro  -> Haines Junction  -> Mayo  -> Ross River  -> Teslin  -> Watson Lake  -> Whitehorse (largest city in the Yukon)

When the first template is invoked, it inserts the heading text Yukon Territory Cities and then calls the template named nl with the parameter nl containing a value of two linefeed character references. (In XSLT, there are no name conflicts between the names of templates and the names of parameters or variables.)

As each instance of city is encountered in the source, the stylesheet invokes the template that matches city, each time with the parameter nl containing only one linefeed. However, when the stylesheet finds city nodes that contain the text nodes Dawson or Whitehorse, it calls the template with distinct parameter values for nl a line of text followed by a linefeed.

You could produce the same results as yukon.xsl without using with-param; however, yukon.xsl illustrates how to use with-param. You can read more about with-param in Section 11.6 of the XSLT specification.

You can also use with-param as a child of apply-templates, as demonstrated in the stylesheet with-param.xsl, explained in Chapter 7. Nevertheless, with-param is more commonly used with call-template.