Troubleshooting XSLT stylesheet parameters
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.
Incorrect use of stylesheet parameters may result in:
- failure to process the document (usually with a meaningful error message), or
- the parameter not being replaced, or
- the parameter being replaced with the wrong value (usually an empty string or empty node set).
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.
Assuming that an output document has been produced, there are three possibilities to consider if the content is not as intended:
- the parameter has not been declared using an
- the value of the parameter is being inappropriately interpreted as an XPath expression, or
- the XSLT processor is not supplying a value for the parameter.
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
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.)
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 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:
- If the value reverts to the empty string or empty node set when externally specified then that points strongly towards the parameter being interpreted as an XPath expression as described above.
- If there is no change to the value when externally specified then likely possibilities are that the parameter name is incorrect or there is some other problem with how the XSLT processor is being invoked.