Debugging a Style Sheet

The interaction of a style sheet with a data file can be a complex process, and style sheet errors might not always be obvious. This section provides troubleshooting advice for the style sheet author. Also see the XSL Debugger, a Web page that offers single-stepping through a style sheet.

Problem:

No Output At All

Solution:

When browsing to an XML file with an XSL style sheet, well-formedness errors in the source file or the style sheet are reported, along with XSL syntax errors and run-time errors. These errors are not automatically reported when using XSL from script or upon data islands. For sample code to detect, format, and report these errors, see Detecting and Handling XSL Errors. Alternatively, use direct browsing as a development tool for reporting errors, as described in Using the Default Style Sheet as a Debugging Aid.

If no errors are being reported, the problem is most likely an error in the style sheet design, which can be diagnosed and corrected by the style sheet author. Begin by testing that the root template of the style sheet is being executed, using the method outlined in Expected Template Is Not Being Used.

Problem:

Expected Template Is Not Being Used

Solution:

If the contents of a template (including the root template) do not seem to be appearing in the output, first check that the template is really being called and not just producing output that doesn't cause display by adding an explicit trace message.

<xsl:template match="address">
  !! inside address template !!
  <xsl:apply-templates select="zipcode"/>
</xsl:template>

If the trace message appears in the output, the template is being executed, and the problem is likely that this <xsl:apply-templates> is not returning anything. For hints on diagnosing why the select pattern returns no results, see No Results from Select Pattern.

If the trace message does not appear, the problem could be that the match pattern is in error. Check the spelling and case of element and attribute names, and check that the full context for the match is actually present in the source data.

Also determine which <xsl:apply-templates> element should invoke the template and ensure that it is selecting the correct nodes—see No Results from Select Pattern.

If the template uses the root pattern (/) and is not being called, check that no template later in the style sheet uses the root pattern or omits the match attribute (matching all nodes including the document root). If the style sheet is being executed against a node other than the document root, a template matching that element is used instead of the root template.

Problem:

No Results from Select Pattern

Solution:

One of the most frequent errors preventing output is select patterns that don't match the input data. Fortunately these are also fairly easy to fix. The debug line added to the example below uses <xsl:eval> to call the xml method on the current node, outputting the node and its children as preformatted XML source.

<xsl:template match="address">
    <PRE><xsl:eval>xml</xsl:eval></PRE>
    <xsl:apply-templates select="zipcode"/>
  </xsl:template>

Comparing the actual XML data to the select pattern, spelling mistakes in element and attribute names can be found; for example, the data could show "zip-code" or "zipCode" as the correct element name. The context of the query can be checked—is "zipcode" a child of "address"? And the source data can also be checked for accuracy—does this "address" have a "zipcode"?

For complex patterns it is often helpful to progressively simplify the pattern to isolate the problem.

Problem:

Elements with the XSL Namespace Appear in Output

Solution:

Elements from the XSL namespace appearing in the output indicate that the XSL namespace declaration is using an incorrect URL. The XSL processor doesn't recognize these elements as XSL elements and treats them as output elements.

The correct namespace identifier for XSL is http://www.w3.org/TR/WD-xsl.

Problem:

Highlighting Elements Not Handled by a Template

Solution:

Often it is helpful to author a style sheet incrementally, adding templates for elements one at a time. Adding this handy template to your style sheet will show you visually which elements do not have templates associated with them yet.

<template match="*">
  <SPAN STYLE="background-color:yellow">
    <xsl:attribute name="title">&lt;<xsl:node-name/>&gt;</xsl:attribute>
    <xsl:apply-templates/>
  </SPAN>
</xsl:template>

Add this template near the top of your style sheet so that it doesn't override templates that handle specific elements. This template will display a yellow background behind the content of any element without a specific template in existence. Running the mouse over the yellow areas will display a ToolTip showing which elements still need to be handled by templates.

Style sheet writing in this fashion almost becomes a game—create a template and more yellow disappears. By the time the yellow is gone, your style sheet is finished!

Also see these related topics: