6.5. The <xsl:text> Instruction Element

Another way to supplement the output result tree is to add text directly using the <xsl:text> element. While this can also be accomplished by typing text directly in the template, the <xsl:text> element serves to distinguish the actual text from other parts of the stylesheet. Sequences of <xsl:text> elements are sent to the output without any line breaks, making it possible to concatenate several strings. The <xsl:text> element, which has one optional attribute, disable-output-escaping, as shown in the following element model definition, can be used to output literal whitespace as well.

<!-- Category: instruction -->

<xsl:text

disable-output-escaping = "yes" | "no">

<!-- Content: #PCDATA -->

</xsl:text>

In effect, <xsl:text> instructs the XSLT processor to output the exact sequence of keystrokes that are found between the <xsl:text> and </xsl:text> tags. This includes line breaks and tabs. However, there are two special characters, < and &, that are not allowed in the content of <xsl:text> unless they are included as the special character entities, &lt; and &amp;. This is because these two characters are special XML characters and are processed as such when the document is parsed. It is the XML parser, not the XSLT processor, that will generate an error if these characters are used. The processing of these characters can be affected using the disable-output-escaping attribute.

6.5.1. The disable-output-escaping Attribute

When the output method of the document is xml or html, whether declared as such in the <xsl:output> element (see Chapter 10), or defaulted by the lack of an <xsl:output> element, certain special character entities are escaped. In other words, they will appear in the output as the same character entity reference that appeared in the input document. Note that this behavior is only valid for a few character entities, based on the XSLT processor used. The XSLT specification states that:

Normally, the xml output method escapes & and < (and possibly other characters) when outputting text nodes. This ensures that the output is well-formed XML. (XSLT specification, section 16.4)

This means that only & and < are guaranteed to appear in the output as &amp; and &lt;, but that the processor is free to add other characters to this list. In order to by-pass this functionality, you can use the disable-output-escaping to output the characters they represent, which are the text strings the entities resolve to. This is achieved by setting the attribute disable-output-escaping to a value of yes.

ATTRIBUTE:  disable-output-escaping (yes|no) "no"
VALUE = (yes|no) "no"

The default value of the disable-output-escaping attribute is no, as shown in the following sample DTD element declaration for <xsl:text>.

<!ELEMENT xsl:text (#PCDATA)>
<!ATTLIST xsl:text
  disable-output-escaping (yes|no) "no" >

When the value of the method attribute of the <xsl:output> element is set to text, the processor ignores any use of the disable-output-escaping attribute altogether, and defaults to generating the actual character in the output. Table 6-1 shows the possible combinations of the disable-output-escaping attribute and the xsl:output method (either “text” or “xml/html”) and the results using James Clark's XT.

6.5.2. Using <xsl:text> to Generate Text

New text that is added to the output can be placed inside the <xsl:text> element to distinguish it from other text.Several <xsl:text> elements can be used to output sequential text elements without any additional whitespace because generating text with <xsl:text>, or any other XSLT element, does not generate any additional line-breaks outside the tag in the output. For example, the following lines generate the single line "line1line2line3line4" in the output:

<xsl:text>line1</xsl:text>
<xsl:text>line2</xsl:text>
<xsl:text>line3</xsl:text>
<xsl:text>line4</xsl:text>

Line breaks inside the <xsl:text> element, however, do appear in the output:

<xsl:text>line1

</xsl:text>
<xsl:text>line2</xsl:text>
<xsl:text>line3</xsl:text>
<xsl:text>line4</xsl:text>

Adding the two line breaks inside the <xsl:text> element for line 1 generates the literal line breaks in the output:

line1

line2line3line4

The <xsl:text> element is very useful for placing extra whitespace like linebreaks and tabs between text generated by other elements. For example, most of the output examples in this book have line breaks added to make them readable, but in reality, the output is bunched up, as shown in Example 6-10.

Example 6-10. Generated elements without line breaks.

						STYLESHEET:

<?xml version="1.0"?>
<xsl:stylesheet
             xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      version="1.0">

<xsl:template match="/">
<block>
      <xsl:element name="house">1</xsl:element>
      <xsl:element name="house">2</xsl:element>
      <xsl:element name="house">3</xsl:element>
      <xsl:element name="house">4</xsl:element>
<xsl:element name="house">5</xsl:element>
</block>
</xsl:template>
</xsl:stylesheet>

RESULT:
<?xml version="1.0" encoding="utf-8"?>
<block><house>1</house><house>2</house><house>3/house><house>4</
house>
<house>5</house></block>

In order to have readable output, with line breaks between the <house> elements, we can add <xsl:text> elements with line breaks inside them, as shown in Example 6-11.

Note that simply putting line breaks between elements in the stylesheet will not generate line breaks in the output, as shown in Example 6-12.

Example 6-11. Generating line breaks with <xsl:text>

						STYLESHEET:

<?xml version="1.0"?>
<xsl:stylesheet
           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      version="1.0">

<xsl:template match="/">
<block>
<xsl:text>
</xsl:text>
      <xsl:element name="house">1</xsl:element>
<xsl:text>
</xsl:text>
      <xsl:element name="house">2</xsl:element>
<xsl:text>
</xsl:text>
      <xsl:element name="house">3</xsl:element>
<xsl:text>
</xsl:text>
      <xsl:element name="house">4</xsl:element>
<xsl:text>
</xsl:text>
      <xsl:element name="house">5</xsl:element>
<xsl:text>
</xsl:text>
</block>
</xsl:template>
</xsl:stylesheet>
RESULT:

<?xml version="1.0" encoding="utf-8"?>
<block>
<house>1</house>
<house>2</house>
<house>3</house>
<house>4</house>
<house>5</house>
</block>

6.5.3. Generating Text without <xsl:text>

It is possible to generate text in the output result tree without using <xsl:text> by simply typing the text in the stylesheet. The issues with using text in this way are subtle in the fact that they deal mostly with whitespace. When the processor sees a text string, it normalizes the string before sending it to the output. This means that any extra whitespace is removed according to the XSLT rules for normalizing whitespace. In most cases this means that, if the text between elements is simply line breaks, the line breaks will not appear in the output. If, on the other hand, the text includes line breaks between other text, the line breaks will be preserved. This is demonstrated in Example 6-13.

Example 6-12. No line breaks generated without <xsl:text>.

						STYLESHEET:

<?xml version="1.0"?>
<xsl:stylesheet
           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      version="1.0">

<xsl:template match="/">
<block>

      <xsl:element name="house">1</xsl:element>

      <xsl:element name="house">2</xsl:element>

      <xsl:element name="house">3</xsl:element>

      <xsl:element name="house">4</xsl:element>

      <xsl:element name="house">5</xsl:element>

</block>
</xsl:template>

</xsl:stylesheet>
RESULT:

<?xml version="1.0" encoding="utf-8"?>

<block><house>1</house><house>2</house><house>3</house><house>4</house>
<house>5</house></block>

Example 6-13. Using text in a stylesheet with line breaks.

						STYLESHEET:


<?xml version="1.0"?>
<xsl:stylesheet
             xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      version="1.0">
<xsl:template match="/">
<block>
text line1

text line2
<xsl:element name="house">1</xsl:element>
<xsl:element name="house">2</xsl:element>
<xsl:element name="house">3</xsl:element>
<xsl:element name="house">4</xsl:element>
<xsl:element name="house">5</xsl:element>
</block>
</xsl:template>
</xsl:stylesheet>
RESULT:


<?xml version="1.0" encoding="utf-8"?>
<block>
text line1

text line2
<house>1</house><house>2</house><house>3</house><house>4</house><house>
5</house></block>