XSLT extensions

XSLT adds some functions to those defined in the XPath standard. These functions are used to access other documents, find indexed elements, generate unique element identifiers, format numbers, refer to the current node, retrieve URLs from unparsed entities, and discover information about the XSLT processor and the vendor of the software.

Document function

This function is discussed in Chapter 11.

Key function

This function is fully described in Chapter 13.

Generate id function

This function is described in Chapter 13.

Format number function

Numeric values copied from source attributes can be reformatted using the format-number() function. For example, the number '12345.6' may be formatted as '12,345.600'.

This function takes at least two parameters, and it returns a string representation of the number that contains appropriate symbols and padding. First, the number to be formatted is given, and then a formatting template, which uses conventions copied from a Java class (the DecimalFormat class, which is part of the 'java.text' package). For example, to reformat a number to ensure that the decimal point appears, and that there are at least two digits after the point, the pattern '0.00' can be used:

						format-number(123.4, '0.00')

   123.40
					

To pass an attribute value as the first parameter, it is only necessary to enter the attribute name, as it is automatically converted to a number before it is passed to the function:

   <price val="123.4"/>
<xsl:template match="price">
  <P>Price:
    <xsl:value-of select="format-number(@val, '0.00')"/>
  </P>
</xsl:template>


   <P>Price: 123.40</P>

The second parameter is a template for the formatting operation. The characters '0', '#', '-', '%', ',' and '.' have special meanings in this template

The character '0' indicates a placeholder for a digit that must be present. If the number to format has no digit at this position, '0' is output. This is demonstrated in the example above. The mimimum template pattern is a single '0' character, indicating that the formatted number must be at least a single digit value (anything less is not a number).

But most templates are divided into two major parts: the required integer part and the optional fractional part. The '.' symbol is a placeholder for the decimal point, which indicates the division between these two parts. The number to format is aligned on this point. For example, '123.4' becomes '123.40' when using the template '0.00', as shown above, but remains '123.4' when using the template '00.0'. It is an error for a pattern to include two '.' symbols.

The '#' symbol is also a placeholder for a digit, but in this case is not replaced by '0' if the digit is absent. It can be used before zeros in the integer part of the number (there must be at leat one '0' here), and after any zeros in the fraction part of the number, as in the following example:

						###00.0###
					

The '#' symbols in this example appear to be superfluous, as they have no effect on the output, but are useful when mixed with grouping separators, which are indicated using a comma, ','.

Also, the '0' and '#' characters in the fraction part of the number indicate how many digits are allowed. So '.0#' indicates two digits only, and a longer fraction is reduced to this length by rounding the last valid digit up or down. Using the example pattern, the value '1.123' becomes '1.12', while '1.12999' becomes '1.13'. This rule does not apply to the integer part of the number, so '##0.' does not truncate the number '123456' to three digits:

            12
           123.4
           123.45678
           876.54321
						1234.56
     123456789.12


###,###,000.00#


           012.00
           123.40
           123.457
           876.543
         1,234.56
   123,456,789.12

A separate pattern can be specified for negative values and is separated from the first pattern using a semi-colon, ';'. In the following example, negative numbers are padded to six digits, preceded by a minus sign:

###,##0.00;-000000

The percent symbol, '%', is used to indicate a percentage. The value is automatically multiplied by 100. A fraction is thereby converted to a percentage:

   0.1
   0.99


%0


   10%
   99%

Similarly, the '?' symbol represents 'per mille' (per thousand). The value is multiplied by 1000. Also, the '¤' symbol (currency symbol) stands in for the current currency symbol, such as '$' or '£'.

It is important to recognize that the '0', ',', '%', '¤' and '-' symbols are only the default characters used in patterns in English. An optional third parameter to the function identifies a Decimal Format element that is used to control the formatting and override the default settings. This element is identified by the value of its Name attribute:

<decimal-format name="England" ... />

... format-number(123.4, '###,##0.00', England) ...

A number of other attributes on this element specify characters for each role. The Decimal Separator attribute and Grouping Separator attributes indicate which characters take these roles (defaulting to '.' and ',' respectively). For example, in France the full-point character is the grouping character, and the comma is the decimal point:

<decimal-format name="France"
                decimal-separator=","
                grouping-separator="." />


   '###.##0,00'

When a number if formatted, it may be an infinite number, an illegal number or a negative number. The symbol for infinity is given in the Infinity attribute, and this attribute may contain a string of characters. Likewise, the NaN attribute holds the string that should be presented when the supplied number if not valid. Remaining attributes must have a single character value. The minus symbol for negative numbers is specified using the Minus Sign attribute (default '-'):

<decimal-format name="England" ...
                infinity="INFINITY AND BEYOND!"
                NaN="NOT A NUMBER"
                minus-sign="M" />

Within the pattern template, reserved symbols are used to indicate digits ('#') and the separator when there are two templates (';'). The Digit attribute specifies the symbol to use to represent a digit, and the Pattern Separator attribute provides the separator character:

<decimal-format name="England" ...
                digit="D"
                pattern-separator="+" />

Finally, a number of attributes are used both to define special characters in the template and, at the same time, to define the output characters for the percent symbol, the per-mille symbol and the zero digit. The Percent, Per Mille amd Zero Digit attributes are used:

<decimal-format name="England" ...
                percent="P"
                per-mille="?"
                zero-digit="Z" />

Current function

While the current node is normally represented by the full-point symbol, '.', it can also be represented by the current() function. The following tests are directly equivalent (as they both test for the occurrence of at least one paragraph somewhere within the current element):

<if test=".//para">...</if>


<if test="current()//para">...</if>

However, their meanings can differ in a subtle way in some circumstances. When location paths are used in an expression, the concept of the 'current' element can be ambiguous.

In one sense, the current element is still the element selected by the template, regardless of where it is referenced from within an expression in the template. In another sense, the current element is the one selected by a previous step in an expression, as each step identifies a new current element from which the remaining steps take their context. It is sometimes useful to be able to distinguish between these two meanings.

The current() function always refers to the element selected by the template, so that the node it represents does not change in an expression. The '.' symbols, however, refers to different nodes, depending on where it is used in the expression. In the following example, the first test matches any directly embedded paragraphs that include (directly or indirectly) a Secret element. The second test selects the paragraph if there is a Secret element anywhere in the book:

<template match="book">
  <if test="para[.//secret]">PARA WITH SECRET</if>
  <if test="para[current()//secret]">PARA IN BOOK WITH
  SECRET</if>
</template>

A perhaps more realistic example of the need for this function is to compare attribute values. The following example compares the revision number of all embedded paragraphs with the revision number of the book itself; and only the latest paragraphs are processed:

   <book rev="3">
     <para rev="1">Old paragraph.</para>
     <para rev="2">Still an old paragraph.</para>
     <para rev="3">New paragraph.</para>
   </book>


<template match="book">
  <DIV>
    <apply-templates
        select="para[./@rev = current()/@rev]" />
  </DIV>
</template>


   <DIV>
     <P>New paragraph.</P>
   </DIV>

Note that this function cannot be used in a pattern, and so it must not be used in the Match attribute of the Template or Key element, or the attributes on the Number element.

Unparsed entity uri function

XML DTDs may contain entities that refer to external non-XML data, such as image files. The unparsed-entity-uri() function is used to obtain the system identifier (or public identifier) when an attribute value contains a reference to an entity name. Consider the following example, where the DTD defines an Image element that uses a Name attribute to hold the entity name. The example instance refers to an entity called 'Boat':

<!DOCTYPE book [
  <!NOTATION GIF SYSTEM "GIFviewer.EXE">
  <!ENTITY Boat SYSTEM "/images/boat.GIF" NDATA GIF>
  ...
  <!ELEMENT image EMPTY>
  <!ATTLIST image name ENTITY #REQUIRED>
]>
<book>
  ...
  <image name="Boat"/>
  ...
</book>

When converting such an example to HTML, which does not use entities, the output attribute must hold the path to the image instead of the entity name (so '/images/boat.GIF' must replace 'Boat'). When the name of an unparsed entity is passed to the function, it returns the URL for that entity:

   <image name="Boat"/>


<xsl:template match="image">
  <IMG HREF="{unparsed-entity-uri(@name)}" />
</xsl:template>


   <IMG HREF="/images/boat.GIF">

System property function

Information about the version of XSLT in use, and the vendor of the XSLT processor currently processing the stylesheet, can be obtained using the system-property() function. A specific processor may provide access to a large number of additional items. A string parameter passed to the function determines what item is wanted. For the core items, the parameters needed are 'xsl:version', 'xsl:vendor' and 'xsl:vendor-uri'. For example, a comment could be constructed, to be placed in the output document, recording the technology and tool used to create the document:

<template match="book">
  <comment>
    <text>XSLT version: </text>
    <value-of select="system-property(xsl:version)" />
    <text>XSLT Processor vendor: </text>
    <value-of select="system-property(xsl:vendor)" />
    <text>XSLT Processor vendor Web site: </text>
    <value-of select="system-property(xsl:vendor-uri)" />
  </comment>
  ...
</template>


   <!-- XSLT version: 1
   XSLT Vendor: Apache Software Foundation
   XSLT Vendor Web site: http://xml.apache.org/xalan
   -->