xsl:message

The <xsl:message> instruction outputs a message, and optionally terminates execution of the stylesheet.

Changes in 2.0

The terminate attribute may now be specified as an attribute value template.

The select attribute is new in XSLT 2.0.

Format

 <xsl:message   select? = expression   terminate? = { "yes"  "no" }>   <!-- Content: sequence-constructor --> </xsl:message> 

Position

<xsl:message> is an instruction. It is always used as part of a sequence constructor.

Attributes

Name	Value	Meaning
select optional	Expression	The expression is evaluated to produce the content of the message
terminate optional	Attribute value template returning «yes » «no »	The value «yes » indicates that processing is terminated after the message is output. The default is «no »

Content

A sequence constructor. There is no requirement that this should only generate text nodes; it can produce any XML fragment. What happens to any markup, however, is not defined in the standard.

Unlike other elements that allow a select attribute and a sequence constructor, in this case they are not mutually exclusive. The results of evaluating the select expression and the results of evaluating the sequence constructor are concatenated to form a single sequence.

Effect

The <xsl:message> instruction behaves in a similar way to <xsl:result-document> described on page 414; it uses the contained sequence constructor (in this case, with the results of evaluating any select expression added at the front) to construct a new document node, sends the constructed document to an implementation-defined destination, and returns an empty sequence.

Unlike <xsl:result-document> , the <xsl:message> element provides no direct control over the destination or format of the result. The intention is that it should be used to produce progress messages, errors and warnings, which are secondary to the purpose of the transformation.

If the terminate attribute is omitted, the value «no » is assumed.

The contents of the constructed document (which will often be a simple text node) are output where the user can be expected to see them. The XSLT specification does not actually say where it goes; this is implementation-dependent, and it might be determined by configuration options. The specification suggests an alert box on the screen and a log file as two possible destinations.

If the terminate attribute has the value «yes » , execution of the stylesheet is abandoned immediately, and any output generated so far is discarded.

Usage

The <xsl:message> instruction is generally used to report error conditions detected by the stylesheet logic. An example might be where an element such as <sales> is expected to have a numeric value, but is found to have a nonnumeric value:

• With «terminate="no" » (the default), the stylesheet can report the error and continue processing.

• With «terminate="yes" » , the stylesheet can report the error and quit.

Before using <xsl:message> in a production environment, check what happens to the messages and whether they can be redirected. You need to be particularly clear about whether your messages are intended to be read by the source document author, the stylesheet author, or the end user: This will affect the way in which you write the text of the message.

The output produced by <xsl:message> can be unpredictable, because the sequence of execution of a stylesheet is not defined in the standard. For example, some products (including Saxon) defer evaluation of a variable until the variable is first used, which means that the order in which different variables are evaluated is difficult to predict. If evaluation of a variable triggers execution of <xsl:message> , the order of the messages may be surprising. Certainly, it can vary from one XSLT processor to another.

A common use of <xsl:message> is to generate diagnostic output so you can work out why your stylesheet isn't behaving as expected. This works well with products that have a fairly predictable sequence of execution, but it can be rather bewildering with a processor that does things in a different order from the one you would expect. Placing diagnostics as comments into the result tree (using <xsl:comment> ) is probably a more flexible solution. Some products, of course, have vendor-defined debugging aids built-in.

Imporant  

The Microsoft MSXML parser ignores <xsl:message terminate="no"> so the message is not reported anywhere . If «terminate="yes" » is specified, it generates an error, which can be handled through the script on the HTML page that invoked the transformation.

Examples

The following example issues a message and quits if the value of the <sales> element is non-numeric:

  <xsl:if test="string(number(sales))='NaN'">   <xsl:message terminate="yes">   <xsl:text>Sales value is not numeric</xsl:text>   </xsl:message>   </xsl:if>  

Unfortunately there is no mechanism defined in the XSLT standard that allows the location of the error in the source document to be included in the message.

The following example extends this by allowing several such errors to be reported in a single run, terminating the run only after all errors have been reported. It works by assigning a global variable to the set of nodes in error:

  <xsl:variable name="bad-sales"   select="//sales[string(number(current()))='NaN']"/>   <xsl:template match="/">   <xsl:for-each select="$bad-sales">   <xsl:message>Sales value <xsl:value-of select"."/>   is not numeric   </xsl:message>   </xsl:for-each>   ...   <xsl:if test="$bad-sales">   <xsl:message terminate="yes">   <xsl:text>Processing abandoned</xsl:text>   </xsl:message>   </xsl:if>   </xsl:template>  

Localized Messages

XSLT is designed very much with internationalization in mind, and no doubt the requirement to localize message text was discussed by the working group . They clearly decided that no special facilities were needed, and instead included a detailed example in the XSLT 1.0 specification showing how the message text can be localized (output in the user's native language). The example is worth repeating because it shows a general technique.

Messages for a particular language are stored in a file whose name identifies the language, for example German messages might be stored in messages/de.xml . The message file might have the structure:

  <messages>   <message name="started">Angefangen</message>   <message name="please-wait"/>Bitte warten!</message>   <message name="finished"/>Fertig</message>   </messages>  

A stylesheet that wishes to produce messages in the appropriate local language will need a parameter to identify this language (it might also be obtained via the system-property () function described in Chapter 7, on page 581, but not in a portable way). The stylesheet can then get access to the messages file for the appropriate language, and read the messages from there:

  <xsl:param name="language" select="'en '" as="xs:string"/>   <xsl:template name="output-message">   <xsl:param name="name"/>   <xsl:variable name="message-file"   select="concat('messages/', $language, '.xml')"/>   <xsl:variable name="message-text"   select="document($message-file)/messages"/>   <xsl:message>   <xsl:value-of select="$message-text/message[@name=$name]"/>   </xsl:message>   </xsl:template>  

The same technique can, of course, be used for producing localized text to include in the output file from the stylesheet.

See Also

<xsl:result-document> on page 414