variable

A variable in XSLT is really not what we would call a variable in VB, but more like a constant. The syntax for declaring a variable is like this:

<xsl:variable name="x" select="2"/>

Or you can declare it like this:

<xsl:variable name="x">2</xsl:variable>

These syntaxes are equivalent, but note that the first example uses an XPath expression and the second one uses an included fragment of XML. This causes the first variable to hold the numeric value 2 and the second one the string value '2'.

The value of a variable can be used in expressions and attribute value templates. The reference to a variable's value is done with $variablename, for example:

<xsl:variable name="x" value="2"/>
...
<xsl:value-of select="item[$x]"/>

<xsl:variable name="author">Teun Duynstee</xsl:variable>
...
<xsl:copy-of select="$author"/>

The copy-of element is a convenient way to insert the value of a variable into the output document.

A variable can be used both as a top-level element (child of the stylesheet element) and at template level (descendant of a template element). As a top-level element, the variable can be used from any place in the document. Within the template, the variable can be seen by all elements following the declaration (and their descendants).

In conclusion, the variable element doesn't really live up to its name, because it cannot change. There is no way to change the content. This is done by design. The XSLT specification does not want to specify any order for the evaluation of different nodes. By introducing changing values, it would become relevant for the result whether a certain action is performed before or after the change.

param

The param element works very much like the variable element. The param element has a name attribute and a select attribute, but the select attribute on the param element is only a default value. If a value is passed, this replaces the value in the select attribute.

Passing a Parameter to a Template

If a template has a parameter defined, a value can be passed when the template is executed (by apply-templates or call-template). Suppose you have this template:

<xsl:template name="numbered-item">
<xsl:param name="format" select="1. "/>
<xsl:number format="{$format}"/>
<xsl:apply-templates/>
</xsl:template>

If you call it using call-template, its index number would be formatted numerically (1. ). But we could also have the same template output the number in another format using the parameter format (which is used in the attribute value template in the number element):

<xsl:template match="OL/LI">
<xsl:call-template name="numbered-item">
<xsl:if test="@count = 'alpha'">
 <xsl:with-param name="format" select="'a. '"/>
</xsl:if>
</xsl:call-template>
</xsl:template>

This template will match on LI elements that have an OL parent. The transformation of these elements is implemented in the template 'numbered-item'. Only if the matched element has a count attribute with value 'alpha' does the template get called with a passed parameter value. This will cause the called template to output the number of the element in another format.

The with-param element can be used as a child of call-template and apply-templates. The name must be specified; the value can also be specified with the content of the element (just like the variable and param elements can).

Passing a Parameter to a Stylesheet

Although the XSLT specification defines a way to declare global parameters, nothing is mentioned about passing a parameter to the stylesheet. This depends on the implementation of the library you use. The SAXON and XT implementations both allow passing parameters on the command line. In the developer's preview of MSXML, you can set a parameter to a stylesheet only by using the special XMLDOMXSLProcessor object. This object is new in the MSXML library and is intended to cache compiled stylesheets to improve performance for repeated transforms with the same stylesheet. If your stylesheet contains a parameter called $x, the following code could be used to make the transformation:

Dim oDoc as new MSXML2.DOMDocument
Dim oXSLT as new MSXML2.DOMDocument
Dim oResult as new MSXML2.DOMDocument
Dim oTemplate as new MSXML2.XSLTemplate
Dim oXMLDOMXSLProcessor as new MSXML2.XMLDOMXSLProcessor

oDoc.async = false
oXSLT.async = false

oDoc.load "http://www.comp.com/sourceDocument.xml"
oXSLT.load "http://www.comp.com/stylesheet.xsl"

Set oTemplate.stylesheet = oXSLT.documentElement

Set oXMLDOMXSLProcessor = oTemplate.createProcessor
Set oXMLDOMXSLProcessor.input = oDoc
Set oXMLDOMXSLProcessor.output = oResult

oXMLDOMXSLProcessor.addParameter("x", "Value we want to pass in")
oXMLDOMXSLProcessor.transform

There are quite a lot of objects that we need here, three DOMDocument objects for starters. One of them may be empty. It is the target for the transform (oResult). The second one contains the source document (oDoc) and the third one contains the stylesheet (oXSLT). oXSLT is used to build the right template object. This template is used to create an XMLDOMXSLProcessor object. We inform the processor about the input and output documents, and then finally add our parameter value and let it transform. As this library is by no means stable at the time of writing - it is only a preview after all - it is very possible (so indicates the preliminary documentation) that the syntax will be different in the final release. In any case, the functionality of passing parameters will be included in that release.

Top Level Settings

The top-level settings are a set of elements that can only be used at the top level of an XSLT document, and hold settings that specify how the stylesheet should be used. They specify the behavior of the processor on a few points.

output

The output element is a bag of attributes that indicate settings about the style of output that is generated. The main setting is defined in the method attribute. The possible values are xml, html and text.

xml

If the method is set to xml, the output document will be an XML document. What this means depends largely on the other attributes of the output element:

• The version attribute specifies which version of XML should be used – we only have version 1.0 now, but that will probably change in the future. This number will also appear in the XML declaration if one is generated. The default version is 1.0.
• The encoding attribute sets the preferred encoding for the destination document. If it is not specified, XSLT processors will use UTF-8 or UTF-16. If an XML declaration is generated, this will contain the encoding string specified.
• The indent attribute can be set to yes to allow the processor to include additional white space in the destination document. This can improve readability. The default setting is no.
• The attribute cdata-section-elements tells the processor when to use CDATA sections in the destination and when to escape illegal characters by using entity references. The value can hold a white space separated list of element names. Text nodes that have a parent node in this list will be output as CDATA sections. All others will be escaped (characters like < will be replaced by entities like <).
• omit-xml-declaration can be set to yes to leave out the XML declaration. By default, XSLT will include one, reflecting the settings of encoding and version. Also, if the standalone attribute has any value, this value will show up in the XML declaration.
• With the doctype-system and doctype-public attributes, the validation rules for the destination document can be set. If you use only doctype-system, the processor will include a <!DOCTYPE fragment just before the first element. The doctype will be the name of the root element. The system identifier (URL of the DTD) is the value of the doctype-system attribute. If you also specify a doctype-public attribute, the output will contain a doctype declaration referring a public DOCTYPE, with the value of doctype-system as its URL. If only doctype-public is used, it will be ignored.
• Finally, the media-type attribute can be used to specify a MIME-type for the result. By default this is text/xml, but some XML-based document types may have their own MIME types installed.

Continued...