Rate this page

Flattr this

Troubleshooting XSLT stylesheet parameters

Content

Background

The behaviour of an XSLT stylesheet can be made to depend on parameters that are chosen when documents are processed. Use of this feature is not particularly complicated but it presents several opportunities for error. Some of these can be challenging to troubleshoot because they provide few clues as to what has gone wrong.

Symptoms

Incorrect use of stylesheet parameters may result in:

It is primarily the second and third of these outcomes that are addressed here because it is the lack of an error message that makes troubleshooting difficult.

Investigation

Strategy

Assuming that an output document has been produced, there are three possibilities to consider if the content is not as intended:

  1. the parameter has not been declared using an xsl:param element,
  2. the value of the parameter is being inappropriately interpreted as an XPath expression, or
  3. the XSLT processor is not supplying a value for the parameter.

Check that the parameter has been declared using an xsl:param element

Instructing the XSLT processor to set the value of a stylesheet parameter is not generally enough to make it usable within the stylesheet: it must also be declared using an xsl:param element. This must be located at the top level of the stylesheet, outside of any template declarations. For example:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:param name="foo"/>

<!-- ... -->
</xsl:stylesheet>

Note that at least one XSLT processor (xsltproc, as of version 1.1.24) does not enforce this requirement. It is therefore possible for a missing xsl:param element to remain latent until triggered by switching to a different XSLT processor.

Check that the value of the parameter is not being inappropriately interpreted as an XPath expression

When a parameter is passed to an XSLT processor it is typically expected to be in the form of an XPath expression. This means that string values must be quoted, or doubly-quoted (single inside double) if the command is executed through a shell:

xsltproc --param foo "'bar'" style.xsl input.xml

If the quotation marks were omitted then the value in this example would be interpreted as an XPath search for elements of type bar at the top level of the input document. This is likely to yield an empty node set, giving the impression that the param option has been ignored by the XSLT processor.

xsltproc does have the ability to accept string arguments without quotation marks, but only if you use the --stringparam option in place of --param:

xsltproc --stringparam foo bar style.xsl input.xml

(Quotation marks would still be needed if, for example, the string contained spaces, but only for the benefit of the shell rather than the XSLT processor.)

Check that a value is being supplied by the XSLT processor

A third way in which a parameter can unintentionally become set to the empty string is if no value has been supplied by the XSLT processor (for example due to an error in the parameter name or the method of invocation) and no explicit default value has been specified. You can test for this condition by specifying a default within the xsl:param element:

<xsl:param name="foo" select="'bar'"/>

Beware that, for the reason discussed above, it is essential that you use two pairs of quotation marks here (single inside double) if you want the default value to be interpreted as a string. It would be useful to check that the default value works by invoking the stylesheet without an externally-specified value for the parameter. Assuming that is does:

Tags: xslt