Declarations

All elements that are immediate children of the <xsl:stylesheet> or <xsl:transform> element are called top-level elements. The top-level elements that are defined in the XSLT specification, and whose names are in the XSLT namespace, are called declarations. Those that are not defined in the XSLT specification are called user -defined data elements, and I will consider these in two categories: elements defined by the vendor of the XSLT processor, and elements defined by the stylesheet author.

It is not permitted to have text nodes as immediate children of the <xsl:stylesheet> or <xsl:transform> element, unless they consist entirely of whitespace characters . Processing instructions and comments may appear, and the XSLT processor will ignore them.

Top-level elements can appear in any order in the stylesheet, except that if there are any <xsl:import> declarations, these must come first. In most cases the order in which the elements appear is of no significance; however, if there are conflicting definitions, the XSLT processor sometimes has the option of either reporting an error or taking whichever definition comes last. If you want your stylesheet to be portable, you cannot rely on this behavior, and should ensure that conflicting declarations don't arise.

Let's now examine the three categories of elements that may appear as children of <xsl:stylesheet>.

• XSLT-defined declarations

• Implementer-defined declarations

• User-defined data elements

XSLT-Defined Declarations

An XSLT-defined declaration must be one of the following.

 <xsl:attribute-set> <xsl:character-map> <xsl:decimal-format> <xsl:function> <xsl:import> <xsl:import-schema> <xsl:include> <xsl:key> <xsl:namespace-alias> <xsl:output> <xsl:param> <xsl:preserve-space> <xsl:strip-space> <xsl:template> <xsl:variable> 

No other XSLT element (that is, no other element with the namespace URI http://www.w3.org/1999/XSL/Transform ) may be used as a child of an <xsl:stylesheet> element.

The <xsl:param> and <xsl:variable> elements are exceptional in that they can be used both as declarations (of global variables and parameters) and as instructions within a sequence constructor.

The following table gives a quick introduction to the purpose of each of these declarations.

Declaration	Effect
<xsl:attribute-set>	Defines a named set of attribute nodes that can be added to any element in the result tree
<xsl:character-map>	Defines how individual characters in the result tree are to be output by the serializer
<xsl:decimal-format>	Defines a display format for numbers , used by the format-number() function described in Chapter 7
<xsl:function>	Defines a stylesheet function that can be invoked from any XPath expression
<xsl:import>	Incorporates declarations from another stylesheet module, with lower precedence than the declarations in the importing module
<xsl:import-schema>	Incorporates definitions from an XML Schema
<xsl:include>	Incorporates declarations from another stylesheet module, with the same precedence as the declarations in the including module
<xsl:key>	Defines a key that may be referenced using the key() function (described in Chapter 7) to give fast access to elements if their key values are known
<xsl:namespace-alias>	Defines a translation from namespaces used in the stylesheet to namespaces used in the result tree
<xsl:output>	Defines how a result tree should be serialized
<xsl:param>	Defines a stylesheet parameter, a value that can be set from outside the stylesheet and accessed from anywhere within it
<xsl:preserve-space>	Defines a list of elements that contain whitespace text nodes that need to be retained
<xsl:strip-space>	Defines a list of elements that contain whitespace text nodes that must be removed
<xsl:template>	Defines a template that can be invoked either when specific nodes are matched, or explicitly by name
<xsl:variable>	Defines a global variable whose value can be accessed from anywhere in the stylesheet

The meaning of each of these elements is explained in full detail in Chapter 5.

Implementor-Defined Declarations

An implementor-defined declaration must belong to a namespace with a non-null URI, different from the XSLT namespace. This will generally be a namespace defined by the vendor: for example with the Saxon product, the relevant namespace URI is http://saxon.sf.net/ . The meaning of elements in this category is entirely at the discretion of the vendor, though the specification states a rule that such elements must not be used to change the meaning of any standard XSLT constructs, except to the extent that the behavior is implementation defined. This is a very important caveat, because there are a great many things in XSLT that are implementation defined, and this clause allows vendors to use top-level elements to give the user control over the choices that are exercised. For example, they might be used to control the following:

• Binding of extension functions and extension instructions

• Collations used for sorting

• Details of result-tree serialization

• Localization of messages

• Options applied when building source trees, for example whether or not schema validation is performed

• Performance trade-offs, for example switches to control optimization or generation of diagnostics

• Error recovery policy

Note that these top-level elements are not technically extension instructions, and their namespace does not have to be declared in the extension-element-prefixes attribute for them to be effective.

Several vendors supply top-level elements that allow you to define extension functions that can be invoked from XPath expressions in the stylesheet (for example, Microsoft has an element called < msxsl :script> that can be used to define JavaScript functions to be called during the transformation). Others might use such elements to define debugging or tracing options. Saxon also uses top-level elements to describe details of collations used for sorting. Such extensions are described in the vendor's documentation for the particular product.

If the processor doesn't recognize the namespace used for an implementor-defined declaration, it simply ignores it. This means you can safely mix different vendors' extensions in the same stylesheet.

User-Defined Top-Level Elements

A user-defined top-level element must also belong to a namespace with a non-null URI, different from the XSLT namespace, and preferably different from the namespace URI used by any vendor. These elements are ignored by the XSLT processor.

With XSLT 1.0, user-defined top-level elements were useful as a place to put lookup data, error messages, and the like. It is possible to reference these elements from within the stylesheet, by treating the stylesheet as an additional psource document, and loading it using the document() function, which is described in Chapter 7, page 532. If the first argument to this function is an empty string, it is interpreted as a reference to the stylesheet module in which the document() function appears.

So, for example, if the stylesheet contains a user-defined top-level element as follows :

  <user:data xmlns:user="http://acme.com/">   <message nr="1">Source document is empty</message>   <message nr="2">Invalid date</message>   <message nr ="3">Sales value is not numeric</message>   </user:data>  

then the same stylesheet can contain a named template to display a numbered message as follows.

  <xsl:template name="display-message">   <xsl:param name="message-nr"/>   <xsl:message xmlns:user="http://acme.com/">   <xsl:value-of   select="document('')/*/user:data/message[@nr=$message-nr]"/>   </xsl:message>   </xsl:template>  

The <xsl:value-of> element evaluates the XPath expression in its select attribute as a string, and writes the value to the result tree. In this case the XPath expression is a path expression starting with «document ('') », which selects the root node of the stylesheet module, followed by «* », which selects its first child (the <xsl:stylesheet> element), followed by «user:data », which selects the <user:data> element, followed by «message [@nr=$message-nr] », which selects the <message> element whose nr attribute is equal to the value of the $message-nr parameter in the stylesheet.

This named template might be invoked from elsewhere in the stylesheet using a sequence such as:

  <xsl:if test="string(number(@sales))='NaN'">   <xsl:call-template name="display-message">   <xsl;with-param name="message-nr" select="3"/>   </xsl:call-template>   </xsl:if>  

The <xsl:if> element tests whether the sales attribute of the current source element is numeric: if not, the result of converting it to a number and then to a string will be the value NaN , meaning Not-A-Number. In this case, the code will call the template we defined earlier to display the message "Sales value is not numeric." (The destination of messages output using <xsl:message> is not defined in the standard. It might produce an alert box, or simply a message in the Web server log file.)

The advantage of this technique is that it gathers all the messages together in one place, for ease of maintenance. The technique can also be readily extended to use different sets of messages, depending on the user's preferred language.

With XSLT 2.0 this technique is no longer necessary, since it becomes more convenient to define fixed data as part of a global variable definition. Instead of writing:

  <user:data xmlns:user="http://acme.com/">   <message nr="1">Source document is empty</message>   <message nr="2">Invalid date</message>   <message nr="3">Sales value is not numeric</message>   </user:data>  

you can write:

  <xsl:variable name="data">   <message nr="1">Source document is empty</message>   <message nr="2">Invalid date</message>   <message nr="3">Sales value is not numeric</message>   </xsl:variable>  

and instead of:

  <xsl:value-of select="document('')/*/user:data/message[@nr=$message-nr]"/>  

you can write:

  <xsl:value-of select="$data/message[@nr=$message-nr]"/>  

The XSLT 1.0 technique still works, and you may want to continue using it when you write stylesheets that are to be portable between 1.0 and 2.0 processors.