XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (45 page)

All of these XSLT instructions are explained in full detail in Chapter 6.

If an unknown element in the XSLT namespace is encountered in a sequence constructor, the action taken depends on whether
forward-compatible mode
is enabled. This is discussed later on page 130.

Extension Instructions

An
extension instruction
is an instruction defined by the vendor or the user, as distinct from one defined in the XSLT standard. In both cases, they are recognized as extension elements because they belong to a namespace that is listed in the
[xsl:]extension-element-prefixes
attribute of this element or of a containing element. (The prefix
xsl:
is used on this attribute only when it appears on an element that is
not
in the XSLT namespace. Most commonly, this attribute—without the
xsl:
prefix—appears on the

element itself.)

In practice, extension instructions are more likely to be defined by vendors than by users. With XSLT 1.0, several vendors provided extension instructions to direct the stylesheet output to multiple output files (with XSLT 2.0, this is superseded by a standard facility, the

instruction). The Saxon product also provided the

extension element, which has been superseded by the

instruction in XSLT 2.0. An example of an extension that has not been superseded by any XSLT 2.0 feature is Saxon's

element, which returns the result of performing a query on a relational database.

The following example shows an

element that would be treated as a literal result element were it not for the
xsl:extension-element-prefixes
attribute, which turns it into an extension instruction.

The way in which new extension instructions are implemented is not defined in the XSLT specification and is likely to vary for each vendor. Not all products allow users to implement their own extension instructions, and with those that do, it may well involve some rather complex system-level programming. In practice, it is usually simpler to escape to user-written code by using extension functions, which are much easier to write. Extension functions are discussed later in this chapter, on page 134.

However, all XSLT processors are required to recognize an extension instruction when they see one, and distinguish it from a literal result element.

What happens if a stylesheet that uses an extension instruction defined in the Xalan product (say) is processed using a different product (say Microsoft's)? If the processor encounters an extension instruction that it cannot evaluate (typically because it was invented by a different vendor), the action it must take is clearly defined in the XSLT standard: if the stylesheet author has defined an

action, it must evaluate that; otherwise, it must report an error. The one thing it must not do is to treat the extension instruction as a literal result element and copy it to the result tree.

Any element found in a sequence constructor that is not an XSLT instruction or an extension instruction is interpreted as a
literal result element
(for example, the

So in effect there are two kinds of nodes in a sequence constructor: instructions and data. Instructions are obeyed according to the rules of the particular instruction, and data nodes (text nodes and literal result elements) are copied to the result sequence.

Literal result elements play an important role in the structure of a stylesheet, so the next section examines them in more detail.

Literal Result Elements

A literal result element is an element within a sequence constructor in the stylesheet that cannot be interpreted as an instruction, and which is therefore treated as data to be copied to the current output destination.

The notation I'm using here to describe literal result elements will be used extensively in Chapter 6, so it's worth explaining it.

• The
  Format
  section explains where the element can appear in the stylesheet; it lists the permitted attributes and their meanings and defines what child elements can appear in this element, if any. For each attribute it gives the name of the attribute, states whether the attribute is mandatory or optional, gives the permitted values for the attribute, and explains how the attribute is used. It also indicates whether the attribute may be an attribute value template.
  
• The
  Effect
  section defines what the element does
  
• The
  Usage
  section explains how the element is used in practice.
  
• The
  Examples
  section gives examples of how the element is used. In some cases, especially where an element has several distinct usages, the examples are merged into the
  Usage
  section.
  

Format

A literal result element can have any name, provided it is not in the XSLT namespace and is not in a namespace declared to contain extension instructions.

Position

A literal result element always appears directly within a sequence constructor.

Attributes

Name	Value	Meaning
xsl:use-when (optional)	An XPath expression that can be evaluated at compile time	Allows the element to be conditionally excluded from the stylesheet.
xsl:default-collation (optional)	A URI identifying a collation supplied by the vendor	Defines the default collation to be used within this part of the stylesheet.
xsl:exclude-result-prefixes (optional)	Whitespace-separated list of namespace prefixes (see the following note)	Each prefix in the list must identify a namespace that is in scope at this point in the stylesheet module. The namespace identified is not to be copied to the result tree.
xsl:extension-element-prefixes (optional)	Whitespace-separated list of namespace prefixes (see the following note)	Each prefix in the list must identify a namespace that is in scope at this point in the stylesheet module. Elements that are descendants of this literal result element, and whose names are in one of these identified namespaces, are treated as extension instructions rather than literal result elements.
xsl:inherit-namespaces (optional)	yes or no (Default is yes )	Indicates whether the constructed element will inherit the namespaces of its parent.
xsl:version (optional)	Number	The value 1.0 invokes backward-compatible processing for this element and its descendants (see page 129). A value greater than 2.0 enables forward-compatible processing (see page 130).
xsl:use-attribute-sets (optional)	Whitespace-separated list of QNames identifying named elements (see the following note)	The attributes defined in the named attribute sets are instantiated and copied as attributes of this literal result element in the constructed sequence.
xsl:type (optional)	The name of a global type (simple type or complex type), which is either a built-in type such as xs:date , or a type defined in an imported schema	The constructed element in the result tree will be validated against this type definition. If it is valid, the element will be annotated with this type; if not, the transformation will fail.
xsl:validation (optional)	One of the values strict , lax , strip , or preserve	Describes the validation action to be performed. This attribute cannot be combined with the xsl:type attribute. The value strict or lax causes the processor to look in the available schemas for an element declaration that matches the name of the literal result element, and to validate the constructed element against this declaration. Validation is described in more detail in Chapter 4.