2.1. Boilerplates for XSLT Stylesheets

Building upon the information presented in Chapter 1, a boilerplate XSLT stylesheet, using <xsl:stylesheet> as the document element, would result in the basic structure required for any stylesheet, as shown in Example 2-1 .

The document element is used to contain the rest of the stylesheet, as well as providing a convenient place to declare the version and namespace for XSL. The XSLT version is shown here as version="1.0" and the XSL namespace, defined using the xmlns namespace declaration attribute, is shown here as:

Example 2-1. Basic XSLT stylesheet structure.

<?xml version="1.0"?>
      <xsl:stylesheet
            xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
            version="1.0" >
            <!--The various top-level elements
                   go here -->
      </xsl:stylesheet>

xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

The document element of an XSLT stylesheet can be either <xsl:stylesheet> or <xsl:transform>, or, as shown in Section2.1.2, can also be a literal result element.

2.1.1. Document Element: <xsl:stylesheet> or xsl:transform>

The document element, whether <xsl:stylesheet> or <xsl:transform>, contains the other elements in a stylesheet, and is used to declare the version of XSLT that the stylesheet conforms to. The document element is also used to tell the processor that the stylesheet is an XSLT stylesheet, using the xmlns attribute. Both elements have the same structure and content, as shown in the definitions below:

<xsl:stylesheet
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
						version = number>
  <!-- Content: (xsl:import*, top-level-elements) -->
</xsl:stylesheet>

Besides the required version attribute, both elements have an optional id attribute, which is used to provide an ID for the stylesheet when it is embedded directly in an XML document (see Section 2.2), and two attributes related to namespace prefixes (discussed in Chapter 12).

<xsl:transform
  id = id
 extension-element-prefixes = tokens
 exclude-result-prefixes = tokens
						version = number>
 <!-- Content: (xsl:import*, top-level-elements) -->
</xsl:transform>

Apart from its syntactic role as the document element of an XSLT stylesheet, the <xsl:stylesheet> or <xsl:transform> element serves to establish the fact that the document is an XSTL stylesheet by declaring it as one with the xmlns attribute. The xmlns attribute, while not listed in the element model definitions from the XSLT specification, is nevertheless allowed on this element. The xmlns attribute on the document element is used to declare the XSL namespace (see Section 12.3.4).

The following sections provide a review of the document element's other attributes, as well as the xml:space attribute.

2.1.1.1. The version Attribute

The version attribute is a required attribute for the document element. It provides information to the XSLT processor to determine which version of the XSLT specification the stylesheet requires for correct processing. The following attribute model definition shows its structure:

ATTRIBUTE: version NMTOKEN #REQUIRED
VALUE = number
						

An example of using the version attribute is as follows:

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

The value of the version attribute will be 1.0 until a new version of the XSLT specification becomes a recommendation.

2.1.1.2. The extension-element-prefixes Attribute

The extension-element-prefixes attribute is used to let the processor know if any extension elements are being used, and what their prefixes are. Prefixes for extension elements are established by adding namespaces (discussed in Chapter 12) to the document element. Any element in a template that uses a prefix other than xsl will be treated as a literal result element (LRE), sent to the output as is, unless the prefix is designated as an extension prefix using the extension-element-prefixes attribute. Once a prefix is designated as an extension prefix, elements in a template that have that prefix are treated as instruction elements and processed according to the rules of the namespace that governs that prefix. The following attribute model definition shows the proper structure of the extension-element-prefixes attribute:

ATTRIBUTE: extension-element-prefixes CDATA #IMPLIED
VALUE: = tokens
						

Declaring the XSL namespace using xmlns gives you access to the functions and top-level elements defined in the namespace, but it does not let you use its prefix in an element inside a template without also adding the prefix to the list of prefixes in the value of the attribute. (Note that some processors do not require this for their own extensions.)

The scope of any extension namespace is limited to the branch of the stylesheet starting with the element that contains either the extension-element-prefixes or xsl:extension-element-prefixes attribute. This does not include any stylesheets that are imported or included within the stylesheet. If the namespace is to be allowed within another stylesheet, it must be declared and designated in that stylesheet. In other words, namespaces are only available to elements that fall inside the branch of the element that declares the namespace.

When declaring XT and Saxon namespaces in our stylesheet, we add the extension-element-prefixes attribute as follows:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      version="1.0"
      xmlns:xt="http://www.jclark.com/xt"
							xmlns:saxon="http://icl.com/saxon"
							extension-element-prefixes="xt saxon" >

2.1.1.3. The exclude-result-prefixes Attribute

The attribute exclude-result-prefixes allows the removal of namespace prefixes from the result tree elements. This attribute is optional, and its value is a whitespace-separated list of namespace prefixes. The namespaces listed must have been declared in the stylesheet. The attribute model definition below shows the required structure of this attribute:

ATTRIBUTE: exclude-result-prefixes CDATA #IMPLIED
VALUE = = tokens
						

This attribute is primarily provided to clean up any namespace prefixes from the result tree that are inconsequential for the output. It is used to exclude any namespace prefixes from the LREs included in a stylesheet.

For the following example, we might declare the namespace "http://vedavid.org/x-nology" with a prefix of "veda," as shown below.

<xsl:stylesheet xmlns:xsl="http://www.w3org/1999/XSL/Transform"
      version="1.0"
      xmlns:xt="http://www.jclark.com/xt"
      xmlns:saxon="http://icl.com/saxon"
      xmlns:veda="http://vedavid.org/x-nology"
      extension-element-prefixes="xt saxon veda"
      exclude-result-prefixes="veda" >

To suppress the output of any prefix for the veda namespace used on an LRE, we add the exclude-result-prefixes attribute. Note that including the prefix with the extension-element-prefixes attribute is not a direct inverse action for excluding it with exclude-result-prefixes. The attributes extension-element-prefixes and exclude-result-prefixes are not direct opposites, because exclude-result-prefixes only affects the output, while extension-element-prefixes affects how the processor reads the elements in the stylesheet.

2.1.1.4. The id Attribute

The id attribute is defined as a type ID, as shown in the following attribute model definition. It is used to add functionality for cross-referencing a document element.

ATTRIBUTE: id ID #IMPLIED
VALUE = id
						

This optional attribute is very uncommon when using the <xsl:stylesheet> or <xsl:transform> document elements. It is more common when using an LRE as the document element, when the resulting document requires IDs on elements. It is also used when embedding a stylesheet directly in an XML document later (as shown in Example 2-4).

2.1.1.5. The xml:space Attribute

The xml:space attribute comes from the XML specification and provides functionality for preserving whitespace text nodes that are found in the stylesheet. It is allowed on the document element to provide a default action for preserving or removing whitespace nodes from all the descendant elements of the document element. The value for the xml:space attribute is a choice of either default or preserve, as shown in the following attribute model definition:

ATTRIBUTE:  xml:space (default|preserve) #IMPLIED
VALUE = (default|preserve)
						

If other elements in the stylesheet use the xml:space attribute, they will override the value declared in the document element. This introduces the concept of inheritance. The descendant elements of the document element will inherit the value of the attribute, unless they explicitly override the value with an xml:space attribute of their own.

It is important to note that the xml:space attribute applies only to the structure of the stylesheet, not to the structure of the input source document. Although they perform the same function, the preserving or stripping of nodes from the source tree is controlled with a set of top-level elements, <xsl:strip-space> and <xsl:preserve-space>.

The xml:space attribute is not specifically shown in the content model for this element in the XSLT specification, but it is referenced later in the appendixes.

2.1.2. Literal Result Element (LRE) Stylesheet

There is a unique kind of stylesheet with a document element that is itself a literal result element (LRE). A literal result element is any element in the stylesheet that does not have a prefix, like xsl, defining it to be part of a namespace. LREs are sent to the output as is, and are discussed in their capacity of generating new XML in Chapter 6. A literal result stylesheet is any stylesheet that has an LRE as the document element.

If an LRE is the first element, or the document element, in a stylesheet, then that LRE must use the same required attributes as either <xsl:stylesheet> or <xsl:transform>, discussed in the previous section. For instance, if the document element is <html>, then the <html> element, as the first element in the stylesheet, requires the XSL namespace declaration and the version attribute for XSLT, as shown in Example 2-2. However, since this is an LRE, the version attribute must be preceded by the xsl prefix. The xmlns attribute is already prefixed, so remains the same.

LREs that reference XSLT attributes use the prefix xsl in front of the attribute to let the processor know that the attribute comes from XSLT, and should be processed according to the rules for that XSLT attribute.

Stylesheets that take the form shown in Example 2-2 are handled by the processor as if the entire stylesheet was inside an <xsl:template> element (part of the template). The XSLT stylesheet in Example 2-3 is the equivalent of Example 2-2, using <xsl:stylesheet> as the document element.

Example 2-2. An LRE stylesheet showing the version and xsl namespace declaration.

<html xsl:version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
      <head>
            <title>My document title.</title>
      </head>
      <body>
            <p>My document content.</p>
      </body>
</html>

Example 2-3. An XSLT stylesheet that is equivalent to the LRE stylesheet in Example 2-2 .

<xsl:stylesheet
            version="1.0"
            xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
      <html>
						<head>
						<title>My document title.</title>
						</head>
						<body>
						<p>My document content.</p>
						</body>
						</html>
</xsl:template>
</xsl:stylesheet>

Because a literal result stylesheet is seen by the processor as a template inside an <xsl:template> element—where top-level elements are not allowed—LRE stylesheets will never contain top-level XSLT elements.

The document element of an LRE stylesheet also has the option to declare other namespaces that may be used in the stylesheet (see Chapter 12).

2.1.3. Children of the Document Element

There are twelve possible element children of the XSLT stylesheet's document element. These children are called top-level elements because they are allowed at the top level within a document element. There is little or no requisite syntactic or logical order to the elements in an XSLT stylesheet. They may occur within any order, though you will find that writing the various template rules in a manner that reflects either the order of the source tree or the intended result tree is often the most natural procedure.

There is one significant exception regarding the prescribed—or otherwise unprescribed—order for top-level elements in an XSLT stylesheet. If the <xsl:include> element is to be used, it must without exception come first within the document element. All other top-level elements must follow the <xsl:include> element, if present.

2.1.3.1. Top-Level Elements

Top-level elements are a specific set of XSLT elements that are children of the document element of an XSLT stylesheet. Top-level elements must be direct children of either the <xsl:stylesheet> element or the <xsl:transform> element. They are not allowed inside instruction elements or any other elements that are children of the document element. They are not allowed as children of an LRE element, even if that element is used as the document element. In other words, you cannot nest top-level elements inside instructions, other top-level elements, or LREs. Note that there are two exceptions to this rule, the <xsl:variable> and <xsl:param> elements are allowed at both the top level and at the same level as instruction elements.

Top-level elements are not instructions per se, as they do not instruct the processor to handle nodes from the source tree in a certain way to generate an output result tree fragment. They can be considered more like assistants to or wrappers for the instruction elements and stylesheet as a whole. The <xsl:template> element in particular only selects a set of nodes to be handed to a template. Each top-level element has a specific function, whether passing information to and from instructions or performing administrative roles.

Each of the top-level elements is discussed in more detail in the following chapters, but it is conceptually useful to provide a short list of them here. In addition, this list gives a sampling of the scope of richness in functionality available through XSLT.