10.3. Generating Error Messages and Logs

Error messages and log files are particularly important to programmers who need to debug or track changes in the processes of their code. XSLT provides a method, using <xsl:message>, to generate logs or messages, whether they are stored as files or sent to the screen as message windows, based on processor-specific implementations.

10.3.1. The <xsl:message> Instruction Element

The <xsl:message> instruction element is a way for the XSLT processor to communicate “outside” of itself and outside of the XSLT stylesheet being processed. It has one optional attribute, terminate, with a possible value of yes or no, as shown in the following element model definition. The content of the <xsl:message> element is a template, which means that other instruction elements can be used to build the structure of the final message.

<!-- Category: instruction -->
<xsl:message

terminate = "yes" | "no">
<!-- Content: template -->
</xsl:message>

If the terminate attribute is specified with a value of yes, the processor will send the message and terminate the processing of the stylesheet at that point. The default is no, meaning that the processor will continue to operate after the message has been output.

There is some discretion on the part of the XSLT processor as to the implementation of the output context and format for whatever message is to be given when <xsl:message> is triggered. It might appear in a message box on-screen, as a line at the command prompt, or it can be sent to a log file. The <xsl:message> element is triggered when the template rule containing it is instantiated; then the template contained within the <xsl:message> element determines the message displayed.

Using a modified fragment of our Markup City for Example 10-2, we can determine whether <block>s have names in text nodes or attribute nodes. The terminate attribute is set to yes to force the processor to terminate when the <xsl:message> element is activated by finding a <block> without a name attribute.

Example 10-2. Using <xsl:message> to test for content.

						INPUT:

<?xml version="1.0"?>
            <thoroughfare name="Whitesburg Drive">
                  <sidestreet>Bob Wallace Avenue</sidestreet>
                  <block name="1st Street"></block>
                  <block name="2nd Street"></block>
                  <block>3rd Street</block>
                  <sidestreet> Woodridge Street</sidestreet>
            </thoroughfare>

STYLESHEET:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">
<xsl:template match="//block">
      <xsl:choose>
            <xsl:when test="@name">
                  <xsl:value-of select="@name" />
            </xsl:when>
            <xsl:otherwise>
                  <xsl:message terminate="yes">
                        <xsl:text>Unfortunately, </xsl:text>
                        <xsl:value-of select="." />
                        <xsl:text> is a street name that is a text
node, not an attribute, so processing will terminate now.</xsl:text>
                  </xsl:message>
             </xsl:otherwise>
      </xsl:choose>
</xsl:template>
</xsl:stylesheet>

MESSAGE GENERATED:

Unfortunately, 3rd Street is a street name that is a text
node, not an attribute, so processing will terminate now.

Using the <xsl:choose> structure, the match attribute of <xsl:when> tests for the presence of a name attribute in each <block>. If there is a name attribute, then its value is selected with <xsl:value-of> and sent to the output result tree. The <xsl:otherwise> element matches any <block> found without a name attribute—3rd Street in this example—and the processor activates the <xsl:message>. The value of the text node is inserted into the text message using <xsl:value-of>. Because the terminate attribute on <xsl:message> is set to yes, the process terminates. Depending on the implementation of the processor, the valid content in the output result tree before the <xsl:message> element is activated may or may not be sent to the output.