Copyright © 1999 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This specification defines the syntax and semantics of XSLT, which is a language for transforming XML documents into other XML documents.
XSLT is designed for use as part of XSL, which is a stylesheet language for XML. In addition to XSLT, XSL includes an XML vocabulary for specifying formatting. XSL specifies the styling of an XML document by using XSLT to describe how the document is transformed into another XML document that uses the formatting vocabulary.
XSLT is also designed to be used independently of XSL. However, XSLT is not intended as a completely general-purpose XML transformation language. Rather it is designed primarily for the kinds of transformations that are needed when XSLT is used as part of XSL.
This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from other documents. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
The list of known errors in this specification is available at http://www.w3.org/1999/11/REC-xslt-19991116-errata.
Comments on this specification may be sent to xsl-editors@w3.org; archives of the comments are available. Public discussion of XSL, including XSL Transformations, takes place on the XSL-List mailing list.
The English version of this specification is the only normative version. However, for translations of this document, see http://www.w3.org/Style/XSL/translations.html.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.
This specification has been produced as part of the W3C Style activity.
This specification defines the syntax and semantics of the XSLT language. A transformation in the XSLT language is expressed as a well-formed XML document [XML] conforming to the Namespaces in XML Recommendation [XML Names], which may include both elements that are defined by XSLT and elements that are not defined by XSLT. XSLT-defined elements are distinguished by belonging to a specific XML namespace (see [2.1 XSLT Namespace]), which is referred to in this specification as the XSLT namespace. Thus this specification is a definition of the syntax and semantics of the XSLT namespace.
A transformation expressed in XSLT describes rules for transforming a source tree into a result tree. The transformation is achieved by associating patterns with templates. A pattern is matched against elements in the source tree. A template is instantiated to create part of the result tree. The result tree is separate from the source tree. The structure of the result tree can be completely different from the structure of the source tree. In constructing the result tree, elements from the source tree can be filtered and reordered, and arbitrary structure can be added.
A transformation expressed in XSLT is called a stylesheet. This is because, in the case when XSLT is transforming into the XSL formatting vocabulary, the transformation functions as a stylesheet.
This document does not specify how an XSLT stylesheet is associated with an XML document. It is recommended that XSL processors support the mechanism described in [XML Stylesheet]. When this or any other mechanism yields a sequence of more than one XSLT stylesheet to be applied simultaneously to a XML document, then the effect should be the same as applying a single stylesheet that imports each member of the sequence in order (see [2.6.2 Stylesheet Import]).
A stylesheet contains a set of template rules. A template rule has two parts: a pattern which is matched against nodes in the source tree and a template which can be instantiated to form part of the result tree. This allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.
A template is instantiated for a particular source element to create part of the result tree. A template can contain elements that specify literal result element structure. A template can also contain elements from the XSLT namespace that are instructions for creating result tree fragments. When a template is instantiated, each instruction is executed and replaced by the result tree fragment that it creates. Instructions can select and process descendant source elements. Processing a descendant element creates a result tree fragment by finding the applicable template rule and instantiating its template. Note that elements are only processed when they have been selected by the execution of an instruction. The result tree is constructed by finding the template rule for the root node and instantiating its template.
In the process of finding the applicable template rule, more than one template rule may have a pattern that matches a given element. However, only one template rule will be applied. The method for deciding which template rule to apply is described in [5.5 Conflict Resolution for Template Rules].
A single template by itself has considerable power: it can create structures of arbitrary complexity; it can pull string values out of arbitrary locations in the source tree; it can generate structures that are repeated according to the occurrence of elements in the source tree. For simple transformations where the structure of the result tree is independent of the structure of the source tree, a stylesheet can often consist of only a single template, which functions as a template for the complete result tree. Transformations on XML documents that represent data are often of this kind (see [D.2 Data Example]). XSLT allows a simplified syntax for such stylesheets (see [2.3 Literal Result Element as Stylesheet]).
When a template is instantiated, it is always instantiated with respect to a current node and a current node list. The current node is always a member of the current node list. Many operations in XSLT are relative to the current node. Only a few instructions change the current node list or the current node (see [5 Template Rules] and [8 Repetition]); during the instantiation of one of these instructions, the current node list changes to a new list of nodes and each member of this new list becomes the current node in turn; after the instantiation of the instruction is complete, the current node and current node list revert to what they were before the instruction was instantiated.
XSLT makes use of the expression language defined by [XPath] for selecting elements for processing, for conditional processing and for generating text.
XSLT provides two "hooks" for extending the language, one hook for extending the set of instruction elements used in templates and one hook for extending the set of functions used in XPath expressions. These hooks are both based on XML namespaces. This version of XSLT does not define a mechanism for implementing the hooks. See [14 Extensions].
NOTE:The XSL WG intends to define such a mechanism in a future version of this specification or in a separate specification.
The element syntax summary notation used to describe the syntax of XSLT-defined elements is described in [18 Notation].
The MIME media types text/xml
and
application/xml
[RFC2376] should be used
for XSLT stylesheets. It is possible that a media type will be registered
specifically for XSLT stylesheets; if and when it is, that media type may
also be used.
The XSLT namespace has the URI
http://www.w3.org/1999/XSL/Transform
.
NOTE:The 1999
in the URI indicates the year in which
the URI was allocated by the W3C. It does not indicate the version of XSLT
being used, which is specified by attributes (see [2.2 Stylesheet Element] and [2.3 Literal Result Element as
Stylesheet]).
XSLT processors must use the XML namespaces mechanism [XML Names] to recognize elements and attributes from this namespace. Elements from the XSLT namespace are recognized only in the stylesheet not in the source document. The complete list of XSLT-defined elements is specified in [B Element Syntax Summary]. Vendors must not extend the XSLT namespace with additional elements or attributes. Instead, any extension must be in a separate namespace. Any namespace that is used for additional instruction elements must be identified by means of the extension element mechanism specified in [14.1 Extension Elements].
This specification uses a prefix of xsl:
for referring to
elements in the XSLT namespace. However, XSLT stylesheets are free to use any
prefix, provided that there is a namespace declaration that binds the prefix
to the URI of the XSLT namespace.
An element from the XSLT namespace may have any attribute not from the XSLT namespace, provided that the expanded-name of the attribute has a non-null namespace URI. The presence of such attributes must not change the behavior of XSLT elements and functions defined in this document. Thus, an XSLT processor is always free to ignore such attributes, and must ignore such attributes without giving an error if it does not recognize the namespace URI. Such attributes can provide, for example, unique identifiers, optimization hints, or documentation.
It is an error for an element from the XSLT namespace to have attributes with expanded-names that have null namespace URIs (i.e. attributes with unprefixed names) other than attributes defined for the element in this document.
NOTE:The conventions used for the names of XSLT elements, attributes and functions are that names are all lower-case, use hyphens to separate words, and use abbreviations only if they already appear in the syntax of a related language such as XML or HTML.
<xsl:stylesheet
id = id
extension-element-prefixes = tokens
exclude-result-prefixes = tokens
version = number>
<!-- Content: (xsl:import*,
top-level-elements) -->
</xsl:stylesheet>
<xsl:transform
id = id
extension-element-prefixes = tokens
exclude-result-prefixes = tokens
version = number>
<!-- Content: (xsl:import*,
top-level-elements) -->
</xsl:transform>
A stylesheet is represented by an xsl:stylesheet
element in
an XML document. xsl:transform
is allowed as a synonym for
xsl:stylesheet
.
An xsl:stylesheet
element must have a version
attribute, indicating the version of XSLT that the stylesheet requires. For
this version of XSLT, the value should be 1.0
. When the value
is not equal to 1.0
, forwards-compatible processing mode is
enabled (see [2.5 Forwards-Compatible
Processing]).
The xsl:stylesheet
element may contain the following types of
elements:
xsl:import
xsl:include
xsl:strip-space
xsl:preserve-space
xsl:output
xsl:key
xsl:decimal-format
xsl:namespace-alias
xsl:attribute-set
xsl:variable
xsl:param
xsl:template
An element occurring as a child of an
xsl:stylesheet
element is called a top-level element.
This example shows the structure of a stylesheet. Ellipses
(...
) indicate where attribute values or content have been
omitted. Although this example shows one of each type of allowed element,
stylesheets may contain zero or more of each of these elements.
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="..."/> <xsl:include href="..."/> <xsl:strip-space elements="..."/> <xsl:preserve-space elements="..."/> <xsl:output method="..."/> <xsl:key name="..." match="..." use="..."/> <xsl:decimal-format name="..."/> <xsl:namespace-alias stylesheet-prefix="..." result-prefix="..."/> <xsl:attribute-set name="..."> ... </xsl:attribute-set> <xsl:variable name="...">...</xsl:variable> <xsl:param name="...">...</xsl:param> <xsl:template match="..."> ... </xsl:template> <xsl:template name="..."> ... </xsl:template> </xsl:stylesheet>
The order in which the children of the xsl:stylesheet
element
occur is not significant except for xsl:import
elements and for
error recovery. Users are free to order the elements as they prefer, and
stylesheet creation tools need not provide control over the order in which
the elements occur.
In addition, the xsl:stylesheet
element may contain any
element not from the XSLT namespace, provided that the expanded-name of the
element has a non-null namespace URI. The presence of such top-level
elements must not change the behavior of XSLT elements and functions defined
in this document; for example, it would not be permitted for such a top-level
element to specify that xsl:apply-templates
was to use different
rules to resolve conflicts. Thus, an XSLT processor is always free to ignore
such top-level elements, and must ignore a top-level element without giving
an error if it does not recognize the namespace URI. Such elements can
provide, for example,
information used by extension elements or extension functions (see [14 Extensions]),
information about what to do with the result tree,
information about how to obtain the source tree,
metadata about the stylesheet,
structured documentation for the stylesheet.
A simplified syntax is allowed for stylesheets that consist of only a
single template for the root node. The stylesheet may consist of just a
literal result element (see [7.1.1
Literal Result Elements]). Such a stylesheet is equivalent to a
stylesheet with an xsl:stylesheet
element containing a template
rule containing the literal result element; the template rule has a match
pattern of /
. For example
<html xsl:version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/TR/xhtml1/strict"> <head> <title>Expense Report Summary</title> </head> <body> <p>Total Amount: <xsl:value-of select="expense-report/total"/></p> </body> </html>
has the same meaning as
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/TR/xhtml1/strict"> <xsl:template match="/"> <html> <head> <title>Expense Report Summary</title> </head> <body> <p>Total Amount: <xsl:value-of select="expense-report/total"/></p> </body> </html> </xsl:template> </xsl:stylesheet>
A literal result element that is the document element of a stylesheet must
have an xsl:version
attribute, which indicates the version of
XSLT that the stylesheet requires. For this version of XSLT, the value
should be 1.0
; the value must be a Number. Other literal result
elements may also have an xsl:version
attribute. When the
xsl:version
attribute is not equal to 1.0
,
forwards-compatible processing mode is enabled (see [2.5 Forwards-Compatible Processing]).
The allowed content of a literal result element when used as a stylesheet is no different from when it occurs within a stylesheet. Thus, a literal result element used as a stylesheet cannot contain top-level elements.
In some situations, the only way that a system can recognize that an XML document needs to be processed by an XSLT processor as an XSLT stylesheet is by examining the XML document itself. Using the simplified syntax makes this harder.
NOTE:For example, another XML language (AXL) might also use anaxl:version
on the document element to indicate that an XML document was an AXL document that required processing by an AXL processor; if a document had both anaxl:version
attribute and anxsl:version
attribute, it would be unclear whether the document should be processed by an XSLT processor or an AXL processor.
Therefore, the simplified syntax should not be used for XSLT stylesheets
that may be used in such a situation. This situation can, for example, arise
when an XSLT stylesheet is transmitted as a message with a MIME media type of
text/xml
or application/xml
to a recipient that
will use the MIME media type to determine how the message is processed.
The name of an internal XSLT object, specifically a named template (see [6 Named Templates]), a mode (see [5.7 Modes]), an attribute set (see [7.1.4 Named Attribute Sets]), a key (see [12.2 Keys]), a decimal-format (see [12.3 Number Formatting]), a variable or a parameter (see [11 Variables and Parameters]) is specified as a QName. If it has a prefix, then the prefix is expanded into a URI reference using the namespace declarations in effect on the attribute in which the name occurs. The expanded-name consisting of the local part of the name and the possibly null URI reference is used as the name of the object. The default namespace is not used for unprefixed names.
An element enables forwards-compatible mode for itself, its attributes,
its descendants and their attributes if either it is an
xsl:stylesheet
element whose version
attribute is
not equal to 1.0
, or it is a literal result element that has an
xsl:version
attribute whose value is not equal to
1.0
, or it is a literal result element that does not have an
xsl:version
attribute and that is the document element of a
stylesheet using the simplified syntax (see [2.3 Literal Result Element as
Stylesheet]). A literal result element that has an
xsl:version
attribute whose value is equal to 1.0
disables forwards-compatible mode for itself, its attributes, its descendants
and their attributes.
If an element is processed in forwards-compatible mode, then:
if it is a top-level element and XSLT 1.0 does not allow such elements as top-level elements, then the element must be ignored along with its content;
if it is an element in a template and XSLT 1.0 does not allow such elements to occur in templates, then if the element is not instantiated, an error must not be signaled, and if the element is instantiated, the XSLT must perform fallback for the element as specified in [15 Fallback];
if the element has an attribute that XSLT 1.0 does not allow the element to have or if the element has an optional attribute with a value that the XSLT 1.0 does not allow the attribute to have, then the attribute must be ignored.
Thus, any XSLT 1.0 processor must be able to process the following stylesheet without error, although the stylesheet includes elements from the XSLT namespace that are not defined in this specification:
<xsl:stylesheet version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="/"> <xsl:choose> <xsl:when test="system-property('xsl:version') >= 1.1"> <xsl:exciting-new-1.1-feature/> </xsl:when> <xsl:otherwise> <html> <head> <title>XSLT 1.1 required</title> </head> <body> <p>Sorry, this stylesheet requires XSLT 1.1.</p> </body> </html> </xsl:otherwise> </xsl:choose> </xsl:template> </xsl:stylesheet>
NOTE:If a stylesheet depends crucially on a top-level element introduced by a version of XSL after 1.0, then the stylesheet can use anxsl:message
element withterminate="yes"
(see [13 Messages]) to ensure that XSLT processors implementing earlier versions of XSL will not silently ignore the top-level element. For example,<xsl:stylesheet version="1.5" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:important-new-1.1-declaration/> <xsl:template match="/"> <xsl:choose> <xsl:when test="system-property('xsl:version') < 1.1"> <xsl:message terminate="yes"> <xsl:text>Sorry, this stylesheet requires XSLT 1.1.</xsl:text> </xsl:message> </xsl:when> <xsl:otherwise> ... </xsl:otherwise> </xsl:choose> </xsl:template> ... </xsl:stylesheet>
If an expression occurs in an attribute that is processed in forwards-compatible mode, then an XSLT processor must recover from errors in the expression as follows:
if the expression does not match the syntax allowed by the XPath grammar, then an error must not be signaled unless the expression is actually evaluated;
if the expression calls a function with an unprefixed name that is not part of the XSLT library, then an error must not be signaled unless the function is actually called;
if the expression calls a function with a number of arguments that XSLT does not allow or with arguments of types that XSLT does not allow, then an error must not be signaled unless the function is actually called.
XSLT provides two mechanisms to combine stylesheets:
<!--
Category: top-level-element -->
<xsl:include
href = uri-reference />
An XSLT stylesheet may include another XSLT stylesheet using an
xsl:include
element. The xsl:include
element has an
href
attribute whose value is a URI reference identifying the
stylesheet to be included. A relative URI is resolved relative to the base
URI of the xsl:include
element (see [3.2
Base URI]).
The xsl:include
element is only allowed as a top-level element.
The inclusion works at the XML tree level. The resource located by the
href
attribute value is parsed as an XML document, and the
children of the xsl:stylesheet
element in this document replace
the xsl:include
element in the including document. The fact
that template rules or definitions are included does not affect the way they
are processed.
The included stylesheet may use the simplified syntax described in [2.3 Literal Result Element as
Stylesheet]. The included stylesheet is treated the same as the
equivalent xsl:stylesheet
element.
It is an error if a stylesheet directly or indirectly includes itself.
NOTE:Including a stylesheet multiple times can cause errors because of duplicate definitions. Such multiple inclusions are less obvious when they are indirect. For example, if stylesheet B includes stylesheet A, stylesheet C includes stylesheet A, and stylesheet D includes both stylesheet B and stylesheet C, then A will be included indirectly by D twice. If all of B, C and D are used as independent stylesheets, then the error can be avoided by separating everything in B other than the inclusion of A into a separate stylesheet B' and changing B to contain just inclusions of B' and A, similarly for C, and then changing D to include A, B', C'.
<xsl:import
href = uri-reference />
An XSLT stylesheet may import another XSLT stylesheet using an
xsl:import
element. Importing a stylesheet is the same as
including it (see [2.6.1 Stylesheet Inclusion])
except that definitions and template rules in the importing stylesheet take
precedence over template rules and definitions in the imported stylesheet;
this is described in more detail below. The xsl:import
element
has an href
attribute whose value is a URI reference identifying
the stylesheet to be imported. A relative URI is resolved relative to the
base URI of the xsl:import
element (see [3.2 Base URI]).
The xsl:import
element is only allowed as a top-level element. The xsl:import
element children must precede all other element children of an
xsl:stylesheet
element, including any xsl:include
element children. When xsl:include
is used to include a
stylesheet, any xsl:import
elements in the included document are
moved up in the including document to after any existing
xsl:import
elements in the including document.
For example,
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="article.xsl"/> <xsl:import href="bigfont.xsl"/> <xsl:attribute-set name="note-style"> <xsl:attribute name="font-style">italic</xsl:attribute> </xsl:attribute-set> </xsl:stylesheet>
The xsl:stylesheet
elements
encountered during processing of a stylesheet that contains
xsl:import
elements are treated as forming an import
tree. In the import tree, each xsl:stylesheet
element has
one import child for each xsl:import
element that it contains.
Any xsl:include
elements are resolved before constructing the
import tree. An
xsl:stylesheet
element in the import tree is defined to have
lower import precedence than another xsl:stylesheet
element in the import tree if it would be visited before that
xsl:stylesheet
element in a post-order traversal of the import
tree (i.e. a traversal of the import tree in which an
xsl:stylesheet
element is visited after its import children).
Each definition and template rule has import precedence determined by the
xsl:stylesheet
element that contains it.
For example, suppose
stylesheet A imports stylesheets B and C in that order;
stylesheet B imports stylesheet D;
stylesheet C imports stylesheet E.
Then the order of import precedence (lowest first) is D, B, E, C, A.
NOTE:Sincexsl:import
elements are required to occur before any definitions or template rules, an implementation that processes imported stylesheets at the point at which it encounters thexsl:import
element will encounter definitions and template rules in increasing order of import precedence.
In general, a definition or template rule with higher import precedence takes precedence over a definition or template rule with lower import precedence. This is defined in detail for each kind of definition and for template rules.
It is an error if a stylesheet directly or indirectly imports itself.
Apart from this, the case where a stylesheet with a particular URI is
imported in multiple places is not treated specially. The import tree will have a separate
xsl:stylesheet
for each place that it is imported.
NOTE:If xsl:apply-imports
is used (see [5.6 Overriding Template Rules]), the
behavior may be different from the behavior if the stylesheet had been
imported only at the place with the highest import precedence.
Normally an XSLT stylesheet is a complete XML document with the
xsl:stylesheet
element as the document element. However, an XSLT
stylesheet may also be embedded in another resource. Two forms of embedding
are possible:
xsl:stylesheet
element may occur in an XML document
other than as the document element.To facilitate the second form of embedding, the
xsl:stylesheet
element is allowed to have an ID attribute that
specifies a unique identifier.
NOTE:In order for such an attribute to be used with the XPath id function, it must actually be declared in the DTD as being an ID.
The following example shows how the xml-stylesheet
processing
instruction [XML Stylesheet] can be used to allow a
document to contain its own stylesheet. The URI reference uses a relative
URI with a fragment identifier to locate the xsl:stylesheet
element:
<?xml-stylesheet type="text/xml" href="#style1"?> <!DOCTYPE doc SYSTEM "doc.dtd"> <doc> <head> <xsl:stylesheet id="style1" version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format"> <xsl:import href="doc.xsl"/> <xsl:template match="id('foo')"> <fo:block font-weight="bold"><xsl:apply-templates/></fo:block> </xsl:template> <xsl:template match="xsl:stylesheet"> <!-- ignore --> </xsl:template> </xsl:stylesheet> </head> <body> <para id="foo"> ... </para> </body> </doc>
NOTE:A stylesheet that is embedded in the document to which it is to
be applied or that may be included or imported into an stylesheet that is
so embedded typically needs to contain a template rule that specifies that
xsl:stylesheet
elements are to be ignored.
The data model used by XSLT is the same as that used by XPath with the additions described in this section. XSLT operates on source, result and stylesheet documents using the same data model. Any two XML documents that have the same tree will be treated the same by XSLT.
Processing instructions and comments in the stylesheet are ignored: the stylesheet is treated as if neither processing instruction nodes nor comment nodes were included in the tree that represents the stylesheet.
The normal restrictions on the children of the root node are relaxed for the result tree. The result tree may have any sequence of nodes as children that would be possible for an element node. In particular, it may have text node children, and any number of element node children. When written out using the XML output method (see [16 Output]), it is possible that a result tree will not be a well-formed XML document; however, it will always be a well-formed external general parsed entity.
When the source tree is created by parsing a well-formed XML document, the root node of the source tree will automatically satisfy the normal restrictions of having no text node children and exactly one element child. When the source tree is created in some other way, for example by using the DOM, the usual restrictions are relaxed for the source tree as for the result tree.
Every node also has an associated URI called its base URI, which is used for resolving attribute values that represent relative URIs into absolute URIs. If an element or processing instruction occurs in an external entity, the base URI of that element or processing instruction is the URI of the external entity; otherwise, the base URI is the base URI of the document. The base URI of the document node is the URI of the document entity. The base URI for a text node, a comment node, an attribute node or a namespace node is the base URI of the parent of the node.
The root node has a mapping that gives the URI for each unparsed entity declared in the document's DTD. The URI is generated from the system identifier and public identifier specified in the entity declaration. The XSLT processor may use the public identifier to generate a URI for the entity instead of the URI specified in the system identifier. If the XSLT processor does not use the public identifier to generate the URI, it must use the system identifier; if the system identifier is a relative URI, it must be resolved into an absolute URI using the URI of the resource containing the entity declaration as the base URI [RFC2396].
After the tree for a source document or stylesheet document has been constructed, but before it is otherwise processed by XSLT, some text nodes are stripped. A text node is never stripped unless it contains only whitespace characters. Stripping the text node removes the text node from the tree. The stripping process takes as input a set of element names for which whitespace must be preserved. The stripping process is applied to both stylesheets and source documents, but the set of whitespace-preserving element names is determined differently for stylesheets and for source documents.
A text node is preserved if any of the following apply:
The element name of the parent of the text node is in the set of whitespace-preserving element names.
The text node contains at least one non-whitespace character. As in XML, a whitespace character is #x20, #x9, #xD or #xA.
An ancestor element of the text node has an xml:space
attribute with a value of preserve
, and no closer ancestor
element has xml:space
with a value of
default
.
Otherwise, the text node is stripped.
The xml:space
attributes are not stripped from the tree.
NOTE:This implies that if an xml:space
attribute is
specified on a literal result element, it will be included in the
result.
For stylesheets, the set of whitespace-preserving element names consists
of just xsl:text
.
<!--
Category: top-level-element -->
<xsl:strip-space
elements = tokens />
<!--
Category: top-level-element -->
<xsl:preserve-space
elements = tokens />
For source documents, the set of whitespace-preserving element names is
specified by xsl:strip-space
and xsl:preserve-space
top-level elements. These elements each have an
elements
attribute whose value is a whitespace-separated list of
NameTests. Initially,
the set of whitespace-preserving element names contains all element names. If
an element name matches a NameTest in an
xsl:strip-space
element, then it is removed from the set of
whitespace-preserving element names. If an element name matches a NameTest in an
xsl:preserve-space
element, then it is added to the set of
whitespace-preserving element names. An element matches a NameTest if and only if the
NameTest would be true
for the element as an XPath
node test. Conflicts between matches to xsl:strip-space
and
xsl:preserve-space
elements are resolved the same way as
conflicts between template rules (see [5.5 Conflict
Resolution for Template Rules]). Thus, the applicable match for a
particular element name is determined as follows:
First, any match with lower import precedence than another match is ignored.
Next, any match with a NameTest that has a lower default priority than the default priority of the NameTest of another match is ignored.
It is an error if this leaves more than one match. An XSLT processor may signal the error; if it does not signal the error, it must recover by choosing, from amongst the matches that are left, the one that occurs last in the stylesheet.
XSLT uses the expression language defined by XPath [XPath]. Expressions are used in XSLT for a variety of purposes including:
An expression must match the XPath production Expr.
Expressions occur as the value of certain attributes on XSLT-defined elements and within curly braces in attribute value templates.
In XSLT, an outermost expression (i.e. an expression that is not part of another expression) gets its context as follows:
the context node comes from the current node
the context position comes from the position of the current node in the current node list; the first position is 1
the context size comes from the size of the current node list
the variable bindings are the bindings in scope on the element which has the attribute in which the expression occurs (see [11 Variables and Parameters])
the set of namespace declarations are those in scope on the element
which has the attribute in which the expression occurs; this includes the
implicit declaration of the prefix xml
required by the the
XML Namespaces Recommendation [XML Names]; the
default namespace (as declared by xmlns
) is not part of this
set
the function library consists of the core function library together with the additional functions defined in [12 Additional Functions] and extension functions as described in [14 Extensions]; it is an error for an expression to include a call to any other function
A list of source nodes is processed to create a result tree fragment. The result tree is constructed by processing a list containing just the root node. A list of source nodes is processed by appending the result tree structure created by processing each of the members of the list in order. A node is processed by finding all the template rules with patterns that match the node, and choosing the best amongst them; the chosen rule's template is then instantiated with the node as the current node and with the list of source nodes as the current node list. A template typically contains instructions that select an additional list of source nodes for processing. The process of matching, instantiation and selection is continued recursively until no new source nodes are selected for processing.
Implementations are free to process the source document in any way that produces the same result as if it were processed using this processing model.
Template rules identify the nodes to which they apply by using a pattern. As well as being used in template rules, patterns are used for numbering (see [7.7 Numbering]) and for declaring keys (see [12.2 Keys]). A pattern specifies a set of conditions on a node. A node that satisfies the conditions matches the pattern; a node that does not satisfy the conditions does not match the pattern. The syntax for patterns is a subset of the syntax for expressions. In particular, location paths that meet certain restrictions can be used as patterns. An expression that is also a pattern always evaluates to an object of type node-set. A node matches a pattern if the node is a member of the result of evaluating the pattern as an expression with respect to some possible context; the possible contexts are those whose context node is the node being matched or one of its ancestors.
Here are some examples of patterns:
para
matches any para
element
*
matches any element
chapter|appendix
matches any chapter
element and any appendix
element
olist/item
matches any item
element with
an olist
parent
appendix//para
matches any para
element
with an appendix
ancestor element
/
matches the root node
text()
matches any text node
processing-instruction()
matches any processing
instruction
node()
matches any node other than an attribute node
and the root node
id("W11")
matches the element with unique ID
W11
para[1]
matches any para
element that is
the first para
child element of its parent
*[position()=1 and self::para]
matches any
para
element that is the first child element of its
parent
para[last()=1]
matches any para
element
that is the only para
child element of its parent
items/item[position()>1]
matches any
item
element that has a items
parent and that
is not the first item
child of its parent
item[position() mod 2 = 1]
would be true for any
item
element that is an odd-numbered item
child
of its parent.
div[@class="appendix"]//p
matches any p
element with a div
ancestor element that has a
class
attribute with value appendix
@class
matches any class
attribute
(not any element that has a class
attribute)
@*
matches any attribute
A pattern must match the grammar for Pattern. A
Pattern is a set of location path patterns
separated by |
. A location path pattern is a location path
whose steps all use only the child
or attribute
axes. Although patterns must not use the descendant-or-self
axis, patterns may use the //
operator as well as the
/
operator. Location path patterns can also start with an id or key function call with a literal argument.
Predicates in a pattern can use arbitrary expressions just like predicates in
a location path.
[1] | Pattern | ::= | LocationPathPattern | |
| Pattern '|' LocationPathPattern | ||||
[2] | LocationPathPattern | ::= | '/' RelativePathPattern? | |
| IdKeyPattern (('/' | '//') RelativePathPattern)? | ||||
| '//'? RelativePathPattern | ||||
[3] | IdKeyPattern | ::= | 'id' '(' Literal ')' | |
| 'key' '(' Literal ',' Literal ')' | ||||
[4] | RelativePathPattern | ::= | StepPattern | |
| RelativePathPattern '/' StepPattern | ||||
| RelativePathPattern '//' StepPattern | ||||
[5] | StepPattern | ::= | ChildOrAttributeAxisSpecifier NodeTest Predicate* | |
[6] | ChildOrAttributeAxisSpecifier | ::= | AbbreviatedAxisSpecifier | |
| ('child' | 'attribute') '::' |
A pattern is defined to match a node if and only if there is possible context such that when the pattern is evaluated as an expression with that context, the node is a member of the resulting node-set. When a node is being matched, the possible contexts have a context node that is the node being matched or any ancestor of that node, and a context node list containing just the context node.
For example, p
matches any p
element, because
for any p
if the expression p
is evaluated with the
parent of the p
element as context the resulting node-set will
contain that p
element as one of its members.
NOTE:This matches even a p
element that is the document
element, since the document root is the parent of the document
element.
Although the semantics of patterns are specified indirectly in terms of
expression evaluation, it is easy to understand the meaning of a pattern
directly without thinking in terms of expression evaluation. In a pattern,
|
indicates alternatives; a pattern with one or more
|
separated alternatives matches if any one of the alternative
matches. A pattern that consists of a sequence of StepPatterns separated by /
or
//
is matched from right to left. The pattern only matches if
the rightmost StepPattern matches and a
suitable element matches the rest of the pattern; if the separator is
/
then only the parent is a suitable element; if the separator
is //
, then any ancestor is a suitable element. A StepPattern that uses the child axis matches if
the NodeTest is true for
the node and the node is not an attribute node. A StepPattern that uses the attribute axis matches
if the NodeTest is true
for the node and the node is an attribute node. When []
is
present, then the first PredicateExpr in a StepPattern is evaluated with the node being
matched as the context node and the siblings of the context node that match
the NodeTest as the
context node list, unless the node being matched is an attribute node, in
which case the context node list is all the attributes that have the same
parent as the attribute being matched and that match the NameTest.
For example
appendix//ulist/item[position()=1]
matches a node if and only if all of the following are true:
the NodeTest
item
is true for the node and the node is not an attribute;
in other words the node is an item
element
evaluating the PredicateExpr
position()=1
with the node as context node and the siblings
of the node that are item
elements as the context node list
yields true
the node has a parent that matches appendix//ulist
;
this will be true if the parent is a ulist
element that has
an appendix
ancestor element.
<!--
Category: top-level-element -->
<xsl:template
match = pattern
name = qname
priority = number
mode = qname>
<!-- Content: (xsl:param*,
template) -->
</xsl:template>
A template rule is specified with the xsl:template
element.
The match
attribute is a Pattern that
identifies the source node or nodes to which the rule applies. The
match
attribute is required unless the xsl:template
element has a name
attribute (see [6 Named Templates]). It is an error for
the value of the match
attribute to contain a VariableReference.
The content of the xsl:template
element is the template that is
instantiated when the template rule is applied.
For example, an XML document might contain:
This is an <emph>important</emph> point.
The following template rule matches emph
elements and
produces a fo:inline-sequence
formatting object with a
font-weight
property of bold
.
<xsl:template match="emph"> <fo:inline-sequence font-weight="bold"> <xsl:apply-templates/> </fo:inline-sequence> </xsl:template>
NOTE:Examples in this document use thefo:
prefix for the namespacehttp://www.w3.org/1999/XSL/Format
, which is the namespace of the formatting objects defined in [XSL].
As described next, the xsl:apply-templates
element
recursively processes the children of the source element.
<!--
Category: instruction -->
<xsl:apply-templates
select = node-set-expression
mode = qname>
<!-- Content: (xsl:sort | xsl:with-param)* -->
</xsl:apply-templates>
This example creates a block for a chapter
element and then
processes its immediate children.
<xsl:template match="chapter"> <fo:block> <xsl:apply-templates/> </fo:block> </xsl:template>
In the absence of a select
attribute, the
xsl:apply-templates
instruction processes all of the children of
the current node, including text nodes. However, text nodes that have been
stripped as specified in [3.4 Whitespace
Stripping] will not be processed. If stripping of whitespace nodes
has not been enabled for an element, then all whitespace in the content of
the element will be processed as text, and thus whitespace between child
elements will count in determining the position of a child element as
returned by the position
function.
A select
attribute can be used to process nodes selected by
an expression instead of processing all children. The value of the
select
attribute is an expression.
The expression must evaluate to a node-set. The selected set of nodes is
processed in document order, unless a sorting specification is present (see
[10 Sorting]). The following example processes
all of the author
children of the author-group
:
<xsl:template match="author-group"> <fo:inline-sequence> <xsl:apply-templates select="author"/> </fo:inline-sequence> </xsl:template>
The following example processes all of the given-name
s of the
author
s that are children of author-group
:
<xsl:template match="author-group"> <fo:inline-sequence> <xsl:apply-templates select="author/given-name"/> </fo:inline-sequence> </xsl:template>
This example processes all of the heading
descendant elements
of the book
element.
<xsl:template match="book"> <fo:block> <xsl:apply-templates select=".//heading"/> </fo:block> </xsl:template>
It is also possible to process elements that are not descendants of the
current node. This example assumes that a department
element
has group
children and employee
descendants. It
finds an employee's department and then processes the group
children of the department
.
<xsl:template match="employee"> <fo:block> Employee <xsl:apply-templates select="name"/> belongs to group <xsl:apply-templates select="ancestor::department/group"/> </fo:block> </xsl:template>
Multiple xsl:apply-templates
elements can be used within a
single template to do simple reordering. The following example creates two
HTML tables. The first table is filled with domestic sales while the second
table is filled with foreign sales.
<xsl:template match="product"> <table> <xsl:apply-templates select="sales/domestic"/> </table> <table> <xsl:apply-templates select="sales/foreign"/> </table> </xsl:template>
NOTE: It is possible for there to be two matching descendants where one is a descendant of the other. This case is not treated specially: both descendants will be processed as usual. For example, given a source document<doc><div><div></div></div></doc>the rule<xsl:template match="doc"> <xsl:apply-templates select=".//div"/> </xsl:template>will process both the outerdiv
and innerdiv
elements.
NOTE:Typically,xsl:apply-templates
is used to process only nodes that are descendants of the current node. Such use ofxsl:apply-templates
cannot result in non-terminating processing loops. However, whenxsl:apply-templates
is used to process elements that are not descendants of the current node, the possibility arises of non-terminating loops. For example,<xsl:template match="foo"> <xsl:apply-templates select="."/> </xsl:template>Implementations may be able to detect such loops in some cases, but the possibility exists that a stylesheet may enter a non-terminating loop that an implementation is unable to detect. This may present a denial of service security risk.
It is possible for a source node to match more than one template rule. The template rule to be used is determined as follows:
First, all matching template rules that have lower import precedence than the matching template rule or rules with the highest import precedence are eliminated from consideration.
Next, all matching template rules that have lower priority than the
matching template rule or rules with the highest priority are eliminated
from consideration. The priority of a template rule is specified by the
priority
attribute on the template rule. The value of this
must be a real number (positive or negative), matching the production Number with an optional
leading minus sign (-
). The default priority is computed as
follows:
If the pattern contains multiple alternatives separated by
|
, then it is treated equivalently to a set of template
rules, one for each alternative.
If the pattern has the form of a QName preceded
by a ChildOrAttributeAxisSpecifier
or has the form processing-instruction(
Literal)
preceded by a ChildOrAttributeAxisSpecifier,
then the priority is 0.
If the pattern has the form NCName:*
preceded by a ChildOrAttributeAxisSpecifier,
then the priority is -0.25.
Otherwise, if the pattern consists of just a NodeTest preceded by a ChildOrAttributeAxisSpecifier, then the priority is -0.5.
Otherwise, the priority is 0.5.
Thus, the most common kind of pattern (a pattern that tests for a node with a particular type and a particular expanded-name) has priority 0. The next less specific kind of pattern (a pattern that tests for a node with a particular type and an expanded-name with a particular namespace URI) has priority -0.25. Patterns less specific than this (patterns that just tests for nodes with particular types) have priority -0.5. Patterns more specific than the most common kind of pattern have priority 0.5.
It is an error if this leaves more than one matching template rule. An XSLT processor may signal the error; if it does not signal the error, it must recover by choosing, from amongst the matching template rules that are left, the one that occurs last in the stylesheet.
<!--
Category: instruction -->
<xsl:apply-imports />
A template rule that is being used to override a template rule in an
imported stylesheet (see [5.5 Conflict Resolution for
Template Rules]) can use the xsl:apply-imports
element
to invoke the overridden template rule.
At any point in the processing of a
stylesheet, there is a current template rule. Whenever a template
rule is chosen by matching a pattern, the template rule becomes the current
template rule for the instantiation of the rule's template. When an
xsl:for-each
element is instantiated, the current template rule
becomes null for the instantiation of the content of the
xsl:for-each
element.
xsl:apply-imports
processes the current node using only
template rules that were imported into the stylesheet element containing the
current template rule; the node is processed in the current template rule's
mode. It is an error if xsl:apply-imports
is instantiated when
the current template rule is null.
For example, suppose the stylesheet doc.xsl
contains a
template rule for example
elements:
<xsl:template match="example"> <pre><xsl:apply-templates/></pre> </xsl:template>
Another stylesheet could import doc.xsl
and modify the
treatment of example
elements as follows:
<xsl:import href="doc.xsl"/> <xsl:template match="example"> <div style="border: solid red"> <xsl:apply-imports/> </div> </xsl:template>
The combined effect would be to transform an example
into an
element of the form:
<div style="border: solid red"><pre>...</pre></div>
Modes allow an element to be processed multiple times, each time producing a different result.
Both xsl:template
and xsl:apply-templates
have
an optional mode
attribute. The value of the mode
attribute is a QName, which is
expanded as described in [2.4 Qualified Names].
If xsl:template
does not have a match
attribute, it
must not have a mode
attribute. If an
xsl:apply-templates
element has a mode
attribute,
then it applies only to those template rules from xsl:template
elements that have a mode
attribute with the same value; if an
xsl:apply-templates
element does not have a mode
attribute, then it applies only to those template rules from
xsl:template
elements that do not have a mode
attribute.
There is a built-in template rule to allow recursive processing to continue in the absence of a successful pattern match by an explicit template rule in the stylesheet. This template rule applies to both element nodes and the root node. The following shows the equivalent of the built-in template rule:
<xsl:template match="*|/"> <xsl:apply-templates/> </xsl:template>
There is also a built-in template rule for each mode, which allows
recursive processing to continue in the same mode in the absence of a
successful pattern match by an explicit template rule in the stylesheet.
This template rule applies to both element nodes and the root node. The
following shows the equivalent of the built-in template rule for mode
m
.
<xsl:template match="*|/" mode="m"> <xsl:apply-templates mode="m"/> </xsl:template>
There is also a built-in template rule for text and attribute nodes that copies text through:
<xsl:template match="text()|@*"> <xsl:value-of select="."/> </xsl:template>
The built-in template rule for processing instructions and comments is to do nothing.
<xsl:template match="processing-instruction()|comment()"/>
The built-in template rule for namespace nodes is also to do nothing. There is no pattern that can match a namespace node; so, the built-in template rule is the only template rule that is applied for namespace nodes.
The built-in template rules are treated as if they were imported implicitly before the stylesheet and so have lower import precedence than all other template rules. Thus, the author can override a built-in template rule by including an explicit template rule.
<!--
Category: instruction -->
<xsl:call-template
name = qname>
<!-- Content: xsl:with-param* -->
</xsl:call-template>
Templates can be invoked by name. An xsl:template
element
with a name
attribute specifies a named template. The value of
the name
attribute is a QName, which is
expanded as described in [2.4 Qualified Names].
If an xsl:template
element has a name
attribute, it
may, but need not, also have a match
attribute. An
xsl:call-template
element invokes a template by name; it has a
required name
attribute that identifies the template to be
invoked. Unlike xsl:apply-templates
,
xsl:call-template
does not change the current node or the
current node list.
The match
, mode
and priority
attributes on an xsl:template
element do not affect whether the
template is invoked by an xsl:call-template
element. Similarly,
the name
attribute on an xsl:template
element does
not affect whether the template is invoked by an
xsl:apply-templates
element.
It is an error if a stylesheet contains more than one template with the same name and same import precedence.
This section describes instructions that directly create nodes in the result tree.
In a template, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension element (see [14.1 Extension Elements]) is instantiated to create an element node with the same expanded-name. The content of the element is a template, which is instantiated to give the content of the created element node. The created element node will have the attribute nodes that were present on the element node in the stylesheet tree, other than attributes with names in the XSLT namespace.
The created element node will also have a copy of the namespace nodes that
were present on the element node in the stylesheet tree with the exception of
any namespace node whose string-value is the XSLT namespace URI
(http://www.w3.org/1999/XSL/Transform
), a namespace URI declared
as an extension namespace (see [14.1
Extension Elements]), or a namespace URI designated as an excluded
namespace. A namespace URI is designated as an excluded namespace by using
an exclude-result-prefixes
attribute on an
xsl:stylesheet
element or an
xsl:exclude-result-prefixes
attribute on a literal result
element. The value of both these attributes is a whitespace-separated list
of namespace prefixes. The namespace bound to each of the prefixes is
designated as an excluded namespace. It is an error if there is no namespace
bound to the prefix on the element bearing the
exclude-result-prefixes
or
xsl:exclude-result-prefixes
attribute. The default namespace
(as declared by xmlns
) may be designated as an excluded
namespace by including #default
in the list of namespace
prefixes. The designation of a namespace as an excluded namespace is
effective within the subtree of the stylesheet rooted at the element bearing
the exclude-result-prefixes
or
xsl:exclude-result-prefixes
attribute; a subtree rooted at an
xsl:stylesheet
element does not include any stylesheets imported
or included by children of that xsl:stylesheet
element.
NOTE:When a stylesheet uses a namespace declaration only for the
purposes of addressing the source tree, specifying the prefix in the
exclude-result-prefixes
attribute will avoid superfluous
namespace declarations in the result tree.
The value of an attribute of a literal result element is interpreted as an
attribute value template: it can
contain expressions contained in curly braces ({}
).
A namespace URI in the stylesheet tree that is being used to specify a namespace URI in the result tree is called a literal namespace URI. This applies to:
the namespace URI in the expanded-name of a literal result element in the stylesheet
the namespace URI in the expanded-name of an attribute specified on a literal result element in the stylesheet
the string-value of a namespace node on a literal result element in the stylesheet
<!--
Category: top-level-element -->
<xsl:namespace-alias
stylesheet-prefix = prefix | "#default"
result-prefix = prefix |
"#default" />
A stylesheet can use the
xsl:namespace-alias
element to declare that one namespace URI is
an alias for another namespace URI. When a literal namespace URI has been declared
to be an alias for another namespace URI, then the namespace URI in the
result tree will be the namespace URI that the literal namespace URI is an
alias for, instead of the literal namespace URI itself. The
xsl:namespace-alias
element declares that the namespace URI
bound to the prefix specified by the stylesheet-prefix
attribute
is an alias for the namespace URI bound to the prefix specified by the
result-prefix
attribute. Thus, the
stylesheet-prefix
attribute specifies the namespace URI that
will appear in the stylesheet, and the result-prefix
attribute
specifies the corresponding namespace URI that will appear in the result
tree. The default namespace (as declared by xmlns
) may be
specified by using #default
instead of a prefix. If a namespace
URI is declared to be an alias for multiple different namespace URIs, then
the declaration with the highest import
precedence is used. It is an error if there is more than one such
declaration. An XSLT processor may signal the error; if it does not signal
the error, it must recover by choosing, from amongst the declarations with
the highest import precedence, the one that occurs last in the stylesheet.
When literal result elements are being used to create element, attribute, or namespace nodes that use the XSLT namespace URI, the stylesheet must use an alias. For example, the stylesheet
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:axsl="http://www.w3.org/1999/XSL/TransformAlias"> <xsl:namespace-alias stylesheet-prefix="axsl" result-prefix="xsl"/> <xsl:template match="/"> <axsl:stylesheet> <xsl:apply-templates/> </axsl:stylesheet> </xsl:template> <xsl:template match="block"> <axsl:template match="{.}"> <fo:block><axsl:apply-templates/></fo:block> </axsl:template> </xsl:template> </xsl:stylesheet>
will generate an XSLT stylesheet from a document of the form:
<elements> <block>p</block> <block>h1</block> <block>h2</block> <block>h3</block> <block>h4</block> </elements>
NOTE:It may be necessary also to use aliases for namespaces other than the XSLT namespace URI. For example, literal result elements belonging to a namespace dealing with digital signatures might cause XSLT stylesheets to be mishandled by general-purpose security software; using an alias for the namespace would avoid the possibility of such mishandling.
xsl:element
<!--
Category: instruction -->
<xsl:element
name = { qname }
namespace = { uri-reference }
use-attribute-sets = qnames>
<!-- Content: template -->
</xsl:element>
The xsl:element
element allows an element to be created with
a computed name. The expanded-name of the
element to be created is specified by a required name
attribute
and an optional namespace
attribute. The content of the
xsl:element
element is a template for the attributes and
children of the created element.
The name
attribute is interpreted as an attribute value template. It is an
error if the string that results from instantiating the attribute value
template is not a QName. An XSLT
processor may signal the error; if it does not signal the error, then it must
recover by making the the result of instantiating the
xsl:element
element be the sequence of nodes created by
instantiating the content of the xsl:element
element, excluding
any initial attribute nodes. If the namespace
attribute is not
present then the QName is expanded into
an expanded-name using the namespace declarations in effect for the
xsl:element
element, including any default namespace
declaration.
If the namespace
attribute is present, then it also is
interpreted as an attribute value
template. The string that results from instantiating the attribute value
template should be a URI reference. It is not an error if the string is not
a syntactically legal URI reference. If the string is empty, then the
expanded-name of the element has a null namespace URI. Otherwise, the string
is used as the namespace URI of the expanded-name of the element to be
created. The local part of the QName specified by the
name
attribute is used as the local part of the expanded-name of
the element to be created.
XSLT processors may make use of the prefix of the QName specified in the
name
attribute when selecting the prefix used for outputting the
created element as XML; however, they are not required to do so.
xsl:attribute
<!--
Category: instruction -->
<xsl:attribute
name = { qname }
namespace = { uri-reference }>
<!-- Content: template -->
</xsl:attribute>
The xsl:attribute
element can be used to add attributes to
result elements whether created by literal result elements in the stylesheet
or by instructions such as xsl:element
. The expanded-name of the
attribute to be created is specified by a required name
attribute and an optional namespace
attribute. Instantiating an
xsl:attribute
element adds an attribute node to the containing
result element node. The content of the xsl:attribute
element is
a template for the value of the created attribute.
The name
attribute is interpreted as an attribute value template. It is an
error if the string that results from instantiating the attribute value
template is not a QName or is the string
xmlns
. An XSLT processor may signal the error; if it does not
signal the error, it must recover by not adding the attribute to the result
tree. If the namespace
attribute is not present, then the QName is expanded into
an expanded-name using the namespace declarations in effect for the
xsl:attribute
element, not including any default
namespace declaration.
If the namespace
attribute is present, then it also is
interpreted as an attribute value
template. The string that results from instantiating it should be a URI
reference. It is not an error if the string is not a syntactically legal URI
reference. If the string is empty, then the expanded-name of the attribute
has a null namespace URI. Otherwise, the string is used as the namespace URI
of the expanded-name of the attribute to be created. The local part of the QName specified by the
name
attribute is used as the local part of the expanded-name of
the attribute to be created.
XSLT processors may make use of the prefix of the QName specified in the
name
attribute when selecting the prefix used for outputting the
created attribute as XML; however, they are not required to do so and, if the
prefix is xmlns
, they must not do so. Thus, although it is not
an error to do:
<xsl:attribute name="xmlns:xsl" namespace="whatever">http://www.w3.org/1999/XSL/Transform</xsl:attribute>
it will not result in a namespace declaration being output.
Adding an attribute to an element replaces any existing attribute of that element with the same expanded-name.
The following are all errors:
Adding an attribute to an element after children have been added to it; implementations may either signal the error or ignore the attribute.
Adding an attribute to a node that is not an element; implementations may either signal the error or ignore the attribute.
Creating nodes other than text nodes during the instantiation of the
content of the xsl:attribute
element; implementations may
either signal the error or ignore the offending nodes.
NOTE:When anxsl:attribute
contains a text node with a newline, then the XML output must contain a character reference. For example,<xsl:attribute name="a">x y</xsl:attribute>will result in the outputa="x
y"(or with any equivalent character reference). The XML output cannot bea="x y"This is because XML 1.0 requires newline characters in attribute values to be normalized into spaces but requires character references to newline characters not to be normalized. The attribute values in the data model represent the attribute value after normalization. If a newline occurring in an attribute value in the tree were output as a newline character rather than as character reference, then the attribute value in the tree created by reparsing the XML would contain a space not a newline, which would mean that the tree had not been output correctly.
<!--
Category: top-level-element -->
<xsl:attribute-set
name = qname
use-attribute-sets = qnames>
<!-- Content: xsl:attribute*
-->
</xsl:attribute-set>
The xsl:attribute-set
element defines a named set of
attributes. The name
attribute specifies the name of the
attribute set. The value of the name
attribute is a QName, which is
expanded as described in [2.4 Qualified Names].
The content of the xsl:attribute-set
element consists of zero or
more xsl:attribute
elements that specify the attributes in the
set.
Attribute sets are used by specifying a use-attribute-sets
attribute on xsl:element
, xsl:copy
(see [7.5 Copying]) or xsl:attribute-set
elements. The value of the use-attribute-sets
attribute is a
whitespace-separated list of names of attribute sets. Each name is specified
as a QName, which
is expanded as described in [2.4 Qualified
Names]. Specifying a use-attribute-sets
attribute is
equivalent to adding xsl:attribute
elements for each of the
attributes in each of the named attribute sets to the beginning of the
content of the element with the use-attribute-sets
attribute, in
the same order in which the names of the attribute sets are specified in the
use-attribute-sets
attribute. It is an error if use of
use-attribute-sets
attributes on xsl:attribute-set
elements causes an attribute set to directly or indirectly use itself.
Attribute sets can also be used by specifying an
xsl:use-attribute-sets
attribute on a literal result element.
The value of the xsl:use-attribute-sets
attribute is a
whitespace-separated list of names of attribute sets. The
xsl:use-attribute-sets
attribute has the same effect as the
use-attribute-sets
attribute on xsl:element
with
the additional rule that attributes specified on the literal result element
itself are treated as if they were specified by xsl:attribute
elements before any actual xsl:attribute
elements but after any
xsl:attribute
elements implied by the
xsl:use-attribute-sets
attribute. Thus, for a literal result
element, attributes from attribute sets named in an
xsl:use-attribute-sets
attribute will be added first, in the
order listed in the attribute; next, attributes specified on the literal
result element will be added; finally, any attributes specified by
xsl:attribute
elements will be added. Since adding an attribute
to an element replaces any existing attribute of that element with the same
name, this means that attributes specified in attribute sets can be
overridden by attributes specified on the literal result element itself.
The template within each xsl:attribute
element in an
xsl:attribute-set
element is instantiated each time the
attribute set is used; it is instantiated using the same current node and
current node list as is used for instantiating the element bearing the
use-attribute-sets
or xsl:use-attribute-sets
attribute. However, it is the position in the stylesheet of the
xsl:attribute
element rather than of the element bearing the
use-attribute-sets
or xsl:use-attribute-sets
attribute that determines which variable bindings are visible (see [11 Variables and Parameters]); thus, only
variables and parameters declared by top-level
xsl:variable
and xsl:param
elements are visible.
The following example creates a named attribute set
title-style
and uses it in a template rule.
<xsl:template match="chapter/heading"> <fo:block quadding="start" xsl:use-attribute-sets="title-style"> <xsl:apply-templates/> </fo:block> </xsl:template> <xsl:attribute-set name="title-style"> <xsl:attribute name="font-size">12pt</xsl:attribute> <xsl:attribute name="font-weight">bold</xsl:attribute> </xsl:attribute-set>
Multiple definitions of an attribute set with the same expanded-name are merged. An attribute from a definition that has higher import precedence takes precedence over an attribute from a definition that has lower import precedence. It is an error if there are two attribute sets that have the same expanded-name and equal import precedence and that both contain the same attribute, unless there is a definition of the attribute set with higher import precedence that also contains the attribute. An XSLT processor may signal the error; if it does not signal the error, it must recover by choosing from amongst the definitions that specify the attribute that have the highest import precedence the one that was specified last in the stylesheet. Where the attributes in an attribute set were specified is relevant only in merging the attributes into the attribute set; it makes no difference when the attribute set is used.
A template can also contain text nodes. Each text node in a template remaining after whitespace has been stripped as specified in [3.4 Whitespace Stripping] will create a text node with the same string-value in the result tree. Adjacent text nodes in the result tree are automatically merged.
Note that text is processed at the tree level. Thus, markup of
<
in a template will be represented in the stylesheet
tree by a text node that includes the character <
. This will
create a text node in the result tree that contains a <
character, which will be represented by the markup <
(or
an equivalent character reference) when the result tree is externalized as an
XML document (unless output escaping is disabled as described in [16.4 Disabling Output
Escaping]).
<!-- Category:
instruction -->
<xsl:text
disable-output-escaping = "yes" | "no">
<!-- Content: #PCDATA -->
</xsl:text>
Literal data characters may also be wrapped in an xsl:text
element. This wrapping may change what whitespace characters are stripped
(see [3.4 Whitespace Stripping]) but does not
affect how the characters are handled by the XSLT processor thereafter.
NOTE:Thexml:lang
andxml:space
attributes are not treated specially by XSLT. In particular,
it is the responsibility of the stylesheet author explicitly to generate any
xml:lang
orxml:space
attributes that are needed in the result;specifying an
xml:lang
orxml:space
attribute on an element in the XSLT namespace will not cause anyxml:lang
orxml:space
attributes to appear in the result.
<!-- Category: instruction
-->
<xsl:processing-instruction
name = { ncname }>
<!-- Content: template -->
</xsl:processing-instruction>
The xsl:processing-instruction
element is instantiated to
create a processing instruction node. The content of the
xsl:processing-instruction
element is a template for the
string-value of the processing instruction node. The
xsl:processing-instruction
element has a required
name
attribute that specifies the name of the processing
instruction node. The value of the name
attribute is
interpreted as an attribute value
template.
For example, this
<xsl:processing-instruction name="xml-stylesheet">href="book.css" type="text/css"</xsl:processing-instruction>
would create the processing instruction
<?xml-stylesheet href="book.css" type="text/css"?>
It is an error if the string that results from instantiating the
name
attribute is not both an NCName and a PITarget. An XSLT
processor may signal the error; if it does not signal the error, it must
recover by not adding the processing instruction to the result tree.
NOTE:This means thatxsl:processing-instruction
cannot be used to output an XML declaration. Thexsl:output
element should be used instead (see [16 Output]).
It is an error if instantiating the content of
xsl:processing-instruction
creates nodes other than text nodes.
An XSLT processor may signal the error; if it does not signal the error, it
must recover by ignoring the offending nodes together with their content.
It is an error if the result of instantiating the content of the
xsl:processing-instruction
contains the string
?>
. An XSLT processor may signal the error; if it does not
signal the error, it must recover by inserting a space after any occurrence
of ?
that is followed by a >
.
<!--
Category: instruction -->
<xsl:comment>
<!-- Content: template -->
</xsl:comment>
The xsl:comment
element is instantiated to create a comment
node in the result tree. The content of the xsl:comment
element
is a template for the string-value of the comment node.
For example, this
<xsl:comment>This file is automatically generated. Do not edit!</xsl:comment>
would create the comment
<!--This file is automatically generated. Do not edit!-->
It is an error if instantiating the content of xsl:comment
creates nodes other than text nodes. An XSLT processor may signal the error;
if it does not signal the error, it must recover by ignoring the offending
nodes together with their content.
It is an error if the result of instantiating the content of the
xsl:comment
contains the string --
or ends with
-
. An XSLT processor may signal the error; if it does not
signal the error, it must recover by inserting a space after any occurrence
of -
that is followed by another -
or that ends the
comment.
<!-- Category:
instruction -->
<xsl:copy
use-attribute-sets = qnames>
<!-- Content: template -->
</xsl:copy>
The xsl:copy
element provides an easy way of copying the
current node. Instantiating the xsl:copy
element creates a copy
of the current node. The namespace nodes of the current node are
automatically copied as well, but the attributes and children of the node are
not automatically copied. The content of the xsl:copy
element
is a template for the attributes and children of the created node; the
content is instantiated only for nodes of types that can have attributes or
children (i.e. root nodes and element nodes).
The xsl:copy
element may have a
use-attribute-sets
attribute (see [7.1.4 Named Attribute Sets]). This is used
only when copying element nodes.
The root node is treated specially because the root node of the result
tree is created implicitly. When the current node is the root node,
xsl:copy
will not create a root node, but will just use the
content template.
For example, the identity transformation can be written using
xsl:copy
as follows:
<xsl:template match="@*|node()"> <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy> </xsl:template>
When the current node is an attribute, then if it would be an error to use
xsl:attribute
to create an attribute with the same name as the
current node, then it is also an error to use xsl:copy
(see [7.1.3 Creating Attributes with
xsl:attribute
]).
The following example shows how xml:lang
attributes can be
easily copied through from source to result. If a stylesheet defines the
following named template:
<xsl:template name="apply-templates-copy-lang"> <xsl:for-each select="@xml:lang"> <xsl:copy/> </xsl:for-each> <xsl:apply-templates/> </xsl:template>
then it can simply do
<xsl:call-template name="apply-templates-copy-lang"/>
instead of
<xsl:apply-templates/>
when it wants to copy the xml:lang
attribute.
Within a template, the xsl:value-of
element can be used to
compute generated text, for example by extracting text from the source tree
or by inserting the value of a variable. The xsl:value-of
element does this with an expression that is
specified as the value of the select
attribute. Expressions can
also be used inside attribute values of literal result elements by enclosing
the expression in curly braces ({}
).
xsl:value-of
<!--
Category: instruction -->
<xsl:value-of
select = string-expression
disable-output-escaping = "yes" | "no" />
The xsl:value-of
element is instantiated to create a text
node in the result tree. The required select
attribute is an expression; this expression is evaluated and the
resulting object is converted to a string as if by a call to the string function.
The string specifies the string-value of the created text node. If the
string is empty, no text node will be created. The created text node will be
merged with any adjacent text nodes.
The xsl:copy-of
element can be used to copy a node-set over
to the result tree without converting it to a string. See [11.3 Using Values of Variables and Parameters with
xsl:copy-of
].
For example, the following creates an HTML paragraph from a
person
element with given-name
and
family-name
attributes. The paragraph will contain the value of
the given-name
attribute of the current node followed by a space
and the value of the family-name
attribute of the current
node.
<xsl:template match="person"> <p> <xsl:value-of select="@given-name"/> <xsl:text> </xsl:text> <xsl:value-of select="@family-name"/> </p> </xsl:template>
For another example, the following creates an HTML paragraph from a
person
element with given-name
and
family-name
children elements. The paragraph will contain the
string-value of the first given-name
child element of the
current node followed by a space and the string-value of the first
family-name
child element of the current node.
<xsl:template match="person"> <p> <xsl:value-of select="given-name"/> <xsl:text> </xsl:text> <xsl:value-of select="family-name"/> </p> </xsl:template>
The following precedes each procedure
element with a
paragraph containing the security level of the procedure. It assumes that
the security level that applies to a procedure is determined by a
security
attribute on the procedure element or on an ancestor
element of the procedure. It also assumes that if more than one such element
has a security
attribute then the security level is determined
by the element that is closest to the procedure.
<xsl:template match="procedure"> <fo:block> <xsl:value-of select="ancestor-or-self::*[@security][1]/@security"/> </fo:block> <xsl:apply-templates/> </xsl:template>
In an attribute value that is
interpreted as an attribute value template, such as an attribute of a
literal result element, an expression can be
used by surrounding the expression with curly braces ({}
). The
attribute value template is instantiated by replacing the expression together
with surrounding curly braces by the result of evaluating the expression and
converting the resulting object to a string as if by a call to the string function.
Curly braces are not recognized in an attribute value in an XSLT stylesheet
unless the attribute is specifically stated to be one that is interpreted as
an attribute value template; in an element syntax summary, the value of such
attributes is surrounded by curly braces.
NOTE:Not all attributes are interpreted as attribute value
templates. Attributes whose value is an expression or pattern, attributes
of top-level elements and attributes that refer
to named XSLT objects are not interpreted as attribute value templates. In
addition, xmlns
attributes are not interpreted as attribute
value templates; it would not be conformant with the XML Namespaces
Recommendation to do this.
The following example creates an img
result element from a
photograph
element in the source; the value of the
src
attribute of the img
element is computed from
the value of the image-dir
variable and the string-value of the
href
child of the photograph
element; the value of
the width
attribute of the img
element is computed
from the value of the width
attribute of the size
child of the photograph
element:
<xsl:variable name="image-dir">/images</xsl:variable> <xsl:template match="photograph"> <img src="{$image-dir}/{href}" width="{size/@width}"/> </xsl:template>
With this source
<photograph> <href>headquarters.jpg</href> <size width="300"/> </photograph>
the result would be
<img src="/images/headquarters.jpg" width="300"/>
When an attribute value template is instantiated, a double left or right curly brace outside an expression will be replaced by a single curly brace. It is an error if a right curly brace occurs in an attribute value template outside an expression without being followed by a second right curly brace. A right curly brace inside a Literal in an expression is not recognized as terminating the expression.
Curly braces are not recognized recursively inside expressions. For example:
<a href="#{id({@ref})/title}">
is not allowed. Instead, use simply:
<a href="#{id(@ref)/title}">
<!--
Category: instruction -->
<xsl:number
level = "single" | "multiple" | "any"
count = pattern
from = pattern
value = number-expression
format = { string }
lang = { nmtoken }
letter-value = { "alphabetic" | "traditional" }
grouping-separator = { char }
grouping-size = { number } />
The xsl:number
element is used to insert a formatted number
into the result tree. The number to be inserted may be specified by an
expression. The value
attribute contains an expression. The expression is evaluated and the
resulting object is converted to a number as if by a call to the number function.
The number is rounded to an integer and then converted to a string using the
attributes specified in [7.7.1 Number to String
Conversion Attributes]; in this context, the value of each of these
attributes is interpreted as an attribute value template. After
conversion, the resulting string is inserted in the result tree. For example,
the following example numbers a sorted list:
<xsl:template match="items"> <xsl:for-each select="item"> <xsl:sort select="."/> <p> <xsl:number value="position()" format="1. "/> <xsl:value-of select="."/> </p> </xsl:for-each> </xsl:template>
If no value
attribute is specified, then the
xsl:number
element inserts a number based on the position of the
current node in the source tree. The following attributes control how the
current node is to be numbered:
The level
attribute specifies what levels of the source
tree should be considered; it has the values single
,
multiple
or any
. The default is
single
.
The count
attribute is a pattern that specifies what
nodes should be counted at those levels. If count
attribute
is not specified, then it defaults to the pattern that matches any node
with the same node type as the current node and, if the current node has
an expanded-name, with the same expanded-name as the current node.
The from
attribute is a pattern that specifies where
counting starts.
In addition, the attributes specified in [7.7.1
Number to String Conversion Attributes] are used for number to string
conversion, as in the case when the value
attribute is
specified.
The xsl:number
element first constructs a list of positive
integers using the level
, count
and
from
attributes:
When level="single"
, it goes up to the first node in
the ancestor-or-self axis that matches the count
pattern,
and constructs a list of length one containing one plus the number of
preceding siblings of that ancestor that match the count
pattern. If there is no such ancestor, it constructs an empty list. If
the from
attribute is specified, then the only ancestors
that are searched are those that are descendants of the nearest ancestor
that matches the from
pattern. Preceding siblings has the
same meaning here as with the preceding-sibling
axis.
When level="multiple"
, it constructs a list of all
ancestors of the current node in document order followed by the element
itself; it then selects from the list those nodes that match the
count
pattern; it then maps each node in the list to one
plus the number of preceding siblings of that node that match the
count
pattern. If the from
attribute is
specified, then the only ancestors that are searched are those that are
descendants of the nearest ancestor that matches the from
pattern. Preceding siblings has the same meaning here as with the
preceding-sibling
axis.
When level="any"
, it constructs a list of length one
containing the number of nodes that match the count
pattern
and belong to the set containing the current node and all nodes at any
level of the document that are before the current node in document order,
excluding any namespace and attribute nodes (in other words the union of
the members of the preceding
and
ancestor-or-self
axes). If the from
attribute
is specified, then only nodes after the first node before the current
node that match the from
pattern are considered.
The list of numbers is then converted into a string using the attributes specified in [7.7.1 Number to String Conversion Attributes]; in this context, the value of each of these attributes is interpreted as an attribute value template. After conversion, the resulting string is inserted in the result tree.
The following would number the items in an ordered list:
<xsl:template match="ol/item"> <fo:block> <xsl:number/><xsl:text>. </xsl:text><xsl:apply-templates/> </fo:block> <xsl:template>
The following two rules would number title
elements. This is
intended for a document that contains a sequence of chapters followed by a
sequence of appendices, where both chapters and appendices contain sections,
which in turn contain subsections. Chapters are numbered 1, 2, 3; appendices
are numbered A, B, C; sections in chapters are numbered 1.1, 1.2, 1.3;
sections in appendices are numbered A.1, A.2, A.3.
<xsl:template match="title"> <fo:block> <xsl:number level="multiple" count="chapter|section|subsection" format="1.1 "/> <xsl:apply-templates/> </fo:block> </xsl:template> <xsl:template match="appendix//title" priority="1"> <fo:block> <xsl:number level="multiple" count="appendix|section|subsection" format="A.1 "/> <xsl:apply-templates/> </fo:block> </xsl:template>
The following example numbers notes sequentially within a chapter:
<xsl:template match="note"> <fo:block> <xsl:number level="any" from="chapter" format="(1) "/> <xsl:apply-templates/> </fo:block> </xsl:template>
The following example would number H4
elements in HTML with a
three-part label:
<xsl:template match="H4"> <fo:block> <xsl:number level="any" from="H1" count="H2"/> <xsl:text>.</xsl:text> <xsl:number level="any" from="H2" count="H3"/> <xsl:text>.</xsl:text> <xsl:number level="any" from="H3" count="H4"/> <xsl:text> </xsl:text> <xsl:apply-templates/> </fo:block> </xsl:template>
The following attributes are used to control conversion of a list of numbers into a string. The numbers are integers greater than 0. The attributes are all optional.
The main attribute is format
. The default value for the
format
attribute is 1
. The format
attribute is split into a sequence of tokens where each token is a maximal
sequence of alphanumeric characters or a maximal sequence of non-alphanumeric
characters. Alphanumeric means any character that has a Unicode category of
Nd, Nl, No, Lu, Ll, Lt, Lm or Lo. The alphanumeric tokens (format tokens)
specify the format to be used for each number in the list. If the first
token is a non-alphanumeric token, then the constructed string will start
with that token; if the last token is non-alphanumeric token, then the
constructed string will end with that token. Non-alphanumeric tokens that
occur between two format tokens are separator tokens that are used to join
numbers in the list. The nth format token will be used to format
the nth number in the list. If there are more numbers than format
tokens, then the last format token will be used to format remaining numbers.
If there are no format tokens, then a format token of 1
is used
to format all numbers. The format token specifies the string to be used to
represent the number 1. Each number after the first will be separated from
the preceding number by the separator token preceding the format token used
to format that number, or, if there are no separator tokens, then by
.
(a period character).
Format tokens are a superset of the allowed values for the
type
attribute for the OL
element in HTML 4.0 and
are interpreted as follows:
Any token where the last character has a decimal digit value of 1 (as specified in the Unicode character property database), and the Unicode value of preceding characters is one less than the Unicode value of the last character generates a decimal representation of t