Copyright © 1999 W3C (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
XSLT 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 transformation that are needed when XSLT is used as part of XSL.
This is a W3C Working Draft for review by W3C members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. The XSL Working Group will not allow early implementation to constrain its ability to make changes to this specification prior to final release. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of current W3C working drafts can be found at http://www.w3.org/TR.
This draft is nearly stable. The XSL Working Group does not anticipate making technical changes except as necessary to resolve the issues explicitly mentioned in this document.
Some material that was previously part of this draft has been separated out into XPath [XPath]; the XPath draft describes the status of everything that is part of XPath.
This is part of the Style activity.
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.
Comments 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.
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].
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 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 [6.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 [C.2 Data Example]). XSLT allows a simplified syntax for such stylesheets (see [2.3 Literal Result Element as Stylesheet]).
XSLT uses XML namespaces [XML Names] to distinguish
elements that are instructions to the XSLT processor from elements that
specify literal result tree structure. Instruction elements all
belong to the XSLT namespace. The examples in this document use a
prefix of xsl:
for elements in the XSLT namespace.
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 [15 Extensions].
NOTE: The XSL WG intends to define such a mechanism in a future version of this specification or in a separate specification.
XSLT processors must use the XML namespaces mechanism [XML Names] to recognize XSLT-defined elements. All XSLT-defined
elements, that is those elements specified in this document with a
prefix of xsl:
, will only be recognized by the XSLT
processor if they belong to a namespace with the URI
http://www.w3.org/XSL/Transform/1.0
(but see [2.5 Forwards-Compatible Processing]); XSLT-defined elements are recognized only in the
stylesheet not in the source document.
Issue (id-attributes-on-xsl-elements): Should it be legal for any element in the XSLT namespace to have an ID attribute?
Issue (non-xsl-attributes-on-xsl-elements): Should it be legal for elements in the XSLT namespace to have global attributes from non-XSLT namespaces?
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.
A stylesheet is represented by an xsl:stylesheet
element in an XML document. xsl:transform
is allowed as
a synonym for xsl:stylesheet
.
The xsl:stylesheet
element may contain the following types
of elements:
xsl:import
xsl:include
xsl:strip-space
xsl:preserve-space
xsl:key
xsl:locale
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 xmlns:xsl="http://www.w3.org/XSL/Transform/1.0"> <xsl:import href="..."/> <xsl:include href="..."/> <xsl:strip-space elements="..."/> <xsl:preserve-space elements="..."/> <xsl:key name="..." match="..." use="..."/> <xsl:locale name="..."> ... </xsl:locale> <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 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 us 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 [15 Extensions]),
information about what to do with the result tree,
information about how to obtain the source tree,
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 [8.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 xmlns:xsl="http://www.w3.org/XSL/Transform/1.0" xmlns="http://www.w3.org/TR/xhtml1"> <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 xmlns:xsl="http://www.w3.org/XSL/Transform/1.0" xmlns="http://www.w3.org/TR/xhtml1"> <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>
The allowed content of a literal result element when used as a stylesheet is no different than when it occurs within a stylesheet.
The name of an internal XSLT object, specifically a named template (see [7 Named Templates]), a mode (see [6.7 Modes]), an attribute set (see [8.1.4 Named Attribute Sets]), a key (see [14.2 Keys]), a locale (see [14.3 Number Formatting]), a variable or a parameter (see [12 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 XSLT processor must treat any namespace whose URI starts with
the http://www.w3.org/XSL/Transform/
in the same way as
the XSLT 1.0 namespace
(http://www.w3.org/XSL/Transform/1.0
) except that it must
recover from errors as follows:
If an element from the XSLT namespace has an attribute that XSLT 1.0 does not allow the element to have, then the attribute must be ignored.
If a literal result element has an attribute from the XSLT namespace that XSLT 1.0 does not allow the literal result element to have, then the attribute must be ignored.
If the xsl:stylesheet
element has a child
element from the XSLT namespace that XSLT 1.0 does not allow an
xsl:stylesheet
element to contain, then the child element
must be ignored along with its content.
If a template contains an element from the XSLT namespace that XSLT 1.0 does not permit templates to contain, then an error must not be signaled unless the element is actually instantiated.
If an 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 an 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.
Issue (mix-namespace-versions): What does forwards-compatible processing require for stylesheets that mix XSLT namespaces with different versions?
Thus, any XSLT 1.0 processor must be able to process the following stylesheet without error, although the stylesheet is not a correct XSLT 1.0 stylesheet:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.1"> <xsl:template match="/"> <xsl:choose> <xsl:when test="system-property('xsl:version') >= 1.1"> <xsl:exciting-new-1.1-feature/> </xsl:when> <xsl:otherwise> <p>Sorry this stylesheet requires XSLT 1.1.</p> </xsl:otherwise> </xsl:choose> </xsl:template> </xsl:stylesheet>
Issue (conformance-error): What error handling should be required for conformant XSLT processors? Should they be required to detect and report invalid stylesheets?
Issue (error-recovery): When should XSLT specify an error recovery behavior? There needs to be a consistent policy.
XSLT provides two mechanisms to combine stylesheets:
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.
It is an error if a stylesheet directly or indirectly includes itself.
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 xmlns:xsl="http://www.w3.org/XSL/Transform/1.0"> <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. The behavior will be the same as if it 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/xsl" href="#style1"?> <!DOCTYPE doc SYSTEM "doc.dtd"> <doc> <head> <xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0" id="style1"> <xsl:import href="doc.xsl"/> <xsl:template match="id('foo')"> <fo:block font-weight="bold"><xsl:apply-templates/></fo:block> </xsl:template> </xsl:stylesheet> </head> <body> <para id="foo"> ... </para> </body> </doc>
NOTE: Thetype
pseudo-attribute in thexml-stylesheet
processing instruction identifies the stylesheet language, not the content type of the resource of which the stylesheet is a part.
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 a result tree may not be a well-formed XML document, but will 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.
An element 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 occurs in an external entity, the base URI of that element is the URI of the external entity. Otherwise, the base URI is the base URI of the document.
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 may be stripped. The stripping process takes as input a set of element types for which whitespace must be preserved. The stripping process is applied to both stylesheets and source documents, but the set of whitespace-preserving element types is determined differently for stylesheets and for source documents.
A text node is preserved if any of the following apply:
The element type of the parent of the text node is in the set of whitespace-preserving element types.
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. When a text node is stripped, it is removed from tree.
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 types
consists of just xsl:text
.
For source documents, the set of whitespace-preserving element types is determined using the stylesheet as follows:
If the xsl:stylesheet
element specifies a
default-space
attribute with a value of
strip
, then the set is initially empty. Otherwise, the
set initially contains all element types that occur in the
document.
The xsl:strip-space
element causes element types
to be removed from the set of whitespace-preserving element types.
The elements
attribute gives a white-space separated list
of the names of the element types.
The xsl:preserve-space
element causes element
types to be added to the set of whitespace-preserving element
types. The elements
attribute gives a white-space
separated list of the names of the element types.
Issue (strip-preserve-space-conflict): How should conflicts between
xsl:strip-space
andxsl:preserve-space
be handled? Need to consider interaction withxsl:import
as well.
When an XSLT processor outputs the result tree as an entity (a sequence of bytes) that represents the result tree in XML, it must do so in such a way that the entity is a well-formed XML external general parsed entity. If the root node has a single element node child and no text node children, then the entity must also be a well-formed XML document entity. When the entity is referenced within a trivial XML document wrapper like this
<!DOCTYPE doc [ <!ENTITY e SYSTEM "..."> ]> <doc>&e;</doc>
where ...
is a URI for the entity, then the wrapper
document as a whole must be a well-formed XML document conforming to
the XML Namespaces Recommendation [XML Names]. In
addition, if a new tree was constructed by parsing the wrapper as an
XML document as specified in [3 Data Model], and then
removing the document element, making its children instead be children
of the root node, then the new tree would be the same as the result
tree, with the following possible exceptions:
The order of attributes in the two trees may be different.
The new tree may contain namespace nodes that were not present in the result tree.
NOTE: An XSLT processor may need to add namespace declarations in the course of outputting the result tree as XML.
NOTE: If the XSLT processor outputs an XML declaration, the XML declaration must include both version information and an encoding declaration, but not a standalone document declaration; this ensures that it is both a XML declaration (allowed at the beginning of a document entity) and a text declaration (allowed at the beginning of an external general parsed entity).
The xsl:stylesheet
element can have an
indent-result
attribute with values yes
or
no
. If the stylesheet specifies
indent-result="yes"
, then the XSLT processor may add
whitespace to the result tree (possibly based on whitespace stripped
from either the source document or the stylesheet) in order to indent
the result nicely; if indent-result="no"
, it must not add
any whitespace to the result. When adding whitespace with
indent-result="yes"
, the XSLT processor can use any
algorithm provided that the result is the same as the result with
indent-result="no"
after whitespace is stripped from both
using the process described with the set of whitespace-preserving
element types consisting of just xsl:text
.
Issue (conformance-result): What if anything should conformant XSLT processors be required to be able to do with the result tree? Should they be required to be able to serialize it as XML?
The xsl:stylesheet
element can have a
result-version
attribute, which specifies the preferred
version of XML to be used for outputting the result tree. If the XSLT
processor does not support this version of XML, it must use a version
of XML that it does support. The version output in the XML
declaration (if the XSLT processor chooses to output an XML
declaration) must correspond to the version of XML that the processor
used for outputting the result tree. The value of the
result-version
attribute must match the VersionNum production of the XML
Recommendation [XML].
The xsl:stylesheet
element can have a
result-encoding
attribute, which specifies the preferred
encoding to use for outputting the result tree. The value of the
result-encoding
attribute must match the EncName production of the XML
Recommendation [XML]. The value of the attribute should
be treated case-insensitively. XSLT processors are required to
respect values of UTF-8
and UTF-16
. For
other values, if the XSLT processor does not support the specified
encoding it may signal an error; if it does not signal an error it
must use UTF-8
or UTF-16
instead. It is
possible that the result tree may contain a character that cannot be
represented in the encoding that the XSLT processor is using for
output. In this case, if the character occurs in a context where XML
recognizes character references (i.e. in the value of an attribute node
or text node), then the character must be output as a character
reference; otherwise (for example if the character occurs in the name
of an element) the XSLT processor must signal an error.
The xsl:stylesheet
element has an optional
result-ns
attribute; the value must be a namespace
prefix. If there is a namespace declared as the default namespace,
then an empty string may be used as the value to specify that the
default namespace is the result namespace.
The result-ns
attribute is a hint to the XSLT
processor that it should do something with the result tree other than
simply output it as XML. XSLT processors are not required to pay
attention to the hint and may simply output the result tree as XML.
If the result-ns
attribute is specified, all elements in
the result tree must belong to the namespace identified by this prefix
(the result namespace).
A result namespace of http://www.w3.org/XSL/Format/1.0
indicates that the result tree should be interpreted according to the
semantics defined in [XSL]. XSL requires that XSL
processors respect this hint. The examples in this document use the
fo:
prefix for this namespace.
A result namespace of http://www.w3.org/TR/REC-html40
indicates that the result tree should be output as HTML that conforms
to the HTML 4.0 Recommendation rather than as XML; for example,
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0" xmlns="http://www.w3.org/TR/REC-html40" result-ns=""> <xsl:template match="/"> <html> <xsl:apply-templates/> </html> </xsl:template> ... </xsl:stylesheet>
Issue (result-ns): The
result-ns
attribute is an inadequate mechanism for controlling the output of the result tree. In particular, restricting the result tree to a single namespace is too limiting. What should replaceresult-ns
? A solution may also encompass the existing output-related attributes (result-encoding
,result-version
andindent-result
).
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 node list comes from 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 [12 Variables and Parameters])
the set of namespace declarations are those in scope on the
element which has the attribute in which the expression occurs; 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 [14 Additional Functions] and extension functions as described in [15 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 for the node. During the instantiation of a template, the node for which the template is being instantiated is called the current node; the list of source nodes that is being processed is called the current node list. The current node is always a member of 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. In addition, patterns are used for numbering (see [8.7 Numbering]) and for declaring keys (see [14.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 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
set of location path patterns separated by |
. A location
path pattern is a location path none of the steps of which uses either
AxisNames or .
or
..
. 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 | ::= | AbbreviatedBasis Predicate* |
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's a NodeTest matches if the NodeTest is true for the node and the
node is not an attribute node. A StepPattern that starts with @
matches if the node is an attribute node and the WildcardName matches the name of
the attribute. 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 nodes
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 WildcardName.
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.
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 [7 Named Templates]).
The content of the xsl:template
element is the
template.
For example, an XML document might contain:
This is an <emph>important</emph> point.
The following template rule matches emph
elements and
has a template, which 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>
As described later, the xsl:apply-templates
element
recursively processes the children of the source element.
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, in particular, 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 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
[11 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 first-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/first-name"/> </fo:inline-sequence> </xsl:template>
This example processes all of the heading
elements
contained in 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 contains group
and employee
elements
(at some level). 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.
Issue (denial-of-service): Does something need to be done about the 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 optionally preceded by an
@
character, then the priority is 0.
Otherwise, if the pattern consists of just a NodeTest, then the priority is -0.5.
Otherwise, the priority is 0.5.
The idea is that the most common kind of pattern (a pattern that just tests for an element with a specific name) has priority 0; a pattern more specific than this has priority 0.5; a pattern less specific than this has 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.
A template rule that is being used to override a template rule in
an imported stylesheet (see [6.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.
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. 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>
Issue (apply-imports-current-node): What does
xsl:apply-imports
do if the current node is not the same as the node for which the current template rule was instantiated? This can happen whenxsl:apply-imports
is used insidexsl:for-each
.
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.
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
and mode
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 a
xsl:apply-templates
element.
It is an error if a stylesheet contains more than one template with the same name and same import precedence. An XSLT processor may signal the error; if it does not signal the error, it must recover by choosing from amongst the templates with highest import precedence the one that occurs last in the stylesheet.
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 [15.1 Extension Elements]) is instantiated to create an element node
of the same type. 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
the namespace nodes that were present on the element node in the
stylesheet tree with the exception of any namespace node whose value
is the XSLT namespace URI
(http://www.w3.org/XSL/Transform/1.0
), a namespace URI
treated the same as the XSLT namespace URI (see [2.5 Forwards-Compatible Processing]), or a namespace URI declared as an extension
namespace (see [15.1 Extension Elements]).
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 ({}
).
Namespace URIs that occur literally in the stylesheet and that are being used to create nodes in the result tree can be quoted. 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 value of a namespace node on a literal result element in the stylesheet
A namespace URI is quoted by prefixing it with the string
quote:
. This prefix will be removed when the template is
instantiated to create the result element node with its associated
attribute nodes and namespace nodes.
When literal result elements are being used to create element, attribute, or namespace nodes that use the XSLT namespace URI, the namespace must be quoted to avoid misinterpretation by the XSLT processor.
NOTE: It may be necessary also to quote other namespaces. 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; quoting the namespace would avoid the possibility of such mishandling.
For example, the stylesheet
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0" xmlns:fo="http://www.w3.org/XSL/Format/1.0" xmlns:qxsl="quote:http://www.w3.org/XSL/Transform/1.0"> <xsl:template match="/"> <qxsl:stylesheet result-ns="fo"> <xsl:apply-templates/> </qxsl:stylesheet> </xsl:template> <xsl:template match="block"> <qxsl:template match="{.}"> <fo:block><qxsl:apply-templates/></fo:block> </qxsl: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>
xsl:element
The xsl:element
element allows an element to be
created with a computed name. The 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 value from instantiating the attribute
value template is not a QName.
An XSLT processor may signal the error; if it does not signal the
error, it must recover by not outputting the element or its
attributes, and outputting only the children of the element. If the
namespace
attribute is not present then the QName is expanded into a 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 value from instantiating the
attribute value template should be a URI reference. It is not an
error if the value is not a syntactically legal URI reference. If the
string value is empty, then the name of the element has no namespace.
Otherwise, the string value is used is used as the namespace URI of the
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 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. They are not however required
to do so.
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 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 value from instantiating is not a QName. An XSLT processor may signal
the error; if it does not signal the error, it must recover by not
outputting the attribute. If the namespace
attribute is
not present, then the QName is
expanded into a 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 value from instantiating it
should be a URI reference. It is not an error if the value is not a
syntactically legal URI reference. If the string value is empty, then
the name of the attribute has no namespace. Otherwise, the string
value is used is used as the namespace URI of the 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 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. They are not however
required to do so.
Adding an attribute to an element replaces any existing attribute of that element with the same 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 anything other than characters 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 was 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.
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
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 [12 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 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 with the same name and with 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 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.
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.
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
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 value 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
outputting the processing instruction.
NOTE: This means that xsl:processing-instruction
cannot be used to output an XML declaration.
It is an error if instantiating the content of
xsl:processing-instruction
creates anything other than
characters. 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 >
.
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 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 anything other than characters. 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.
The xsl:copy
element provides an easy way of copying
the current node. The xsl:copy
element is replaced by 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 not used for nodes of
types that do not have attributes or children (attributes, text,
comments and processing instructions).
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 [8.1.3 Creating Attributes with xsl: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 brace ({}
).
xsl:value-of
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 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 [12.3 Using Values of Variables and Parameters with
xsl:copy-of
].
For example, the following creates an HTML paragraph from a
person
element with first-name
and
surname
attributes. The paragraph will contain the value
of the first-name
attribute of the current node followed
by a space and the value of the surname
attribute of the
current node.
<xsl:template match="person"> <p> <xsl:value-of select="@first-name"/> <xsl:text> </xsl:text> <xsl:value-of select="@surname"/> </p> </xsl:template>
For example, the following creates an HTML paragraph from a
person
element with first-name
and
surname
children elements. The paragraph will contain
the value of the first first-name
child element of the
current node followed by a space and the value of the first
surname
child element of the current node.
<xsl:template match="person"> <p> <xsl:value-of select="first-name"/> <xsl:text> </xsl:text> <xsl:value-of select="surname"/> </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.
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
constant and the content
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; an XSLT processor may signal the error or recover by treating the right curly brace as if it had been doubled. 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}">
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
a 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 [8.7.1 Number to String Conversion Attributes]; when used with
xsl:number
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 a name, with the same name as the current
node.
The from
attribute is a pattern that specifies
where counting starts from.
In addition the xsl:number
element has the attributes
specified in [8.7.1 Number to String Conversion Attributes] for number to string
conversion.
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 nearest
ancestor (including the current node as its own ancestor) 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; thus neither
attribute nor namespaces nodes have any preceding siblings.
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; thus neither
attribute nor namespaces nodes have any preceding siblings.
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 [8.7.1 Number to String Conversion Attributes]; when used with
xsl:number
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 n-th format token will be used
to format the n-th 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
.
.
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 2.0 character property database),
and the Unicode value of preceding characters is one less than the
Unicode value of the last character. This generates a decimal
representation of the number where each number is at least as long as
the format token. Thus, a format token 1
generates the
sequence 1 2 ... 10 11 12 ...
, and a format token
01
generates the sequence 01 02 ... 09 10 11 12
... 99 100 101
.
A format token A
generates the sequence A
B C ... Z AA AB AC...
.
A format token a
generates the sequence a
b c ... z aa ab ac...
.
A format token i
generates the sequence i
ii iii iv v vi vii viii ix x ...
.
A format token I
generates the sequence I
II III IV V VI VII VIII IX X ...
.
Any other format token indicates a numbering sequence that
starts with that token. If an implementation does not support a
numbering sequence that starts with that token, it must use a format
token of 1
.
When numbering with an alphabetic sequence, the lang
attribute specifies which language's alphabet is to be used; it has
the same range of values as xml:lang
[XML];
if no lang
value is specified, the language should be
determined from the system environment
The letter-value
attribute disambiguates between
numbering sequences that use letters. In many languages there are two
commonly used numbering sequences that use letters. One numbering
sequence assigns numeric values to letters in alphabetic sequence, and
the other assigns numeric values to each letter in some other manner.
In English, these would correspond to the numbering sequences
specified by the format tokens a
and i
. In
some languages, the first member of each sequence is the same, and so
the format token alone would be ambiguous. A value of
alphabetic
specifies the alphabetic sequence; a value of
other
specifies the other sequence. If the
letter-value
attribute is not specified, then it is
implementation-dependent how any ambiguity is resolved.
The grouping-separator
attribute gives the separator
used as a grouping (e.g. thousands) separator in decimal numbering
sequences, and the optional grouping-size
specifies the
size (normally 3) of the grouping. For example,
grouping-separator=","
and grouping-size="3"
would produce numbers of the form 1,000,000
. If only one
of the grouping-separator
and grouping-size
attributes is specified, then it is ignored.
Here are some examples of conversion specifications:
format="ア"
specifies Katakana
numbering
format="イ"
specifies Katakana
numbering in the "iroha" order
format="๑"
specifies numbering with
Thai digits
format="א" letter-value="other"
specifies "traditional" Hebrew numbering
format="ა" letter-value="other"
specifies Georgian numbering
format="α" letter-value="other"
specifies "classical" Greek numbering
format="а" letter-value="other"
specifies Old Slavic numbering
When the result has a known regular structure, it is useful to be
able to specify directly the template for selected nodes. The
xsl:for-each
instruction contains a template, which is
instantiated for each node selected by the expression specified by the
select
attribute. The select
attribute is
required. The expression must evaluate to a node-set. The template
is instantiated with the selected node as the current node, and with a
list of all of the selected nodes as the current node list. The nodes
are processed in document order, unless a sorting specification is
present (see [11 Sorting]).
For example, given an XML document with this structure
<customers> <customer> <name>...</name> <order>...</order> <order>...</order> </customer> <customer> <name>...</name> <order>...</order> <order>...</order> </customer> </customers>
the following would create an HTML document containing a table with
a row for each customer
element
<xsl:template match="/"> <html> <head> <title>customers</title> </head> <body> <table> <tbody> <xsl:for-each select="customers/customer"> <tr> <th> <xsl:apply-templates select="name"/> </th> <xsl:for-each select="order"> <td> <xsl:apply-templates/> </td> </xsl:for-each> </tr> </xsl:for-each> </tbody> </table> </body> </html> </xsl:template>
There are two instructions in XSLT which support conditional
processing in a template: xsl:if
and
xsl:choose
. The xsl:if
instruction provides
simple if-then conditionality; the xsl:choose
instruction
supports selection of one choice when there are several
possibilities.
xsl:if
The xsl:if
element has a single attribute,
test
which specifies an expression. The content is a template.
The expression is evaluated and the resulting object is converted to a
boolean as if by a call to the boolean function.
If the result is true, then the content template is instantiated;
otherwise, nothing is created. In the following example, the names in
a group of names are formatted as a comma separated list:
<xsl:template match="namelist/name"> <xsl:apply-templates/> <xsl:if test="not(position()=last())">, </xsl:if> </xsl:template>
The following colors every other table row yellow:
<xsl:template match="item"> <tr> <xsl:if test="position() mod 2 = 0"> <xsl:attribute name="bgcolor">yellow</xsl:attribute> </xsl:if> <xsl:apply-templates/> </tr> </xsl:template>
xsl:choose
The xsl:choose
element selects one among a number of
possible alternatives. It consists of a series of
xsl:when
elements followed by an optional
xsl:otherwise
element. Each xsl:when
element has a single attribute, test
, which specifies an
expression. The content of the
xsl:when
and xsl:otherwise
elements is a
template. When an xsl:choose
element is processed, each
of the xsl:when
elements is tested in turn, by evaluating
the expression and converting the resulting object to a boolean as if
by a call to the boolean function. The content
of the first, and only the first, xsl:when
element whose
test is true is instantiated. If no xsl:when
is true,
the content of the xsl:otherwise
element is
instantiated. If no xsl:when
element is true, and no
xsl:otherwise
element is present, nothing is created.
The following example enumerates items in an ordered list using arabic numerals, letters, or roman numerals depending on the depth to which the ordered lists are nested.
<xsl:template match="orderedlist/listitem"> <fo:list-item indent-start='2pi'> <fo:list-item-label> <xsl:variable name="level" select="count(ancestor::orderedlist) mod 3"/> <xsl:choose> <xsl:when test='$level=1'> <xsl:number format="i"/> </xsl:when> <xsl:when test='$level=2'> <xsl:number format="a"/> </xsl:when> <xsl:otherwise> <xsl:number format="1"/> </xsl:otherwise> </xsl:choose> <xsl:text>. </xsl:text> </fo:list-item-label> <fo:list-item-body> <xsl:apply-templates/> </fo:list-item-body> </fo:list-item> </xsl:template>
Sorting is specified by adding xsl:sort
elements as
children of xsl:apply-templates
or
xsl:for-each
. The first xsl:sort
child
specifies the primary sort key, the second xsl:sort
child
specifies the secondary sort key and so on. When
xsl:apply-templates
or xsl:for-each
has one
or more xsl:sort
children, then instead of processing the
selected elements in document order, it sorts the elements according
to the specified sort keys and then processes them in sorted order.
When used in xsl:for-each
, xsl:sort
elements
must occur first. When a template is instantiated by
xsl:apply-templates
and xsl:for-each
, the
current node list consists of the complete list of nodes being
processed in sorted order.
xsl:sort
has a select
attribute whose
value is an expression. For
each node to be processed, the expression is evaluated with that node
as the current node. The resulting object is converted to a string as
if by a call to the string function; this string
is used as the sort key for that node. The default value of the
select
attribute is .
, which will cause the
value of the current node to be used as the sort key.
This string serves as a sort key for the node. The following
optional attributes on xsl:sort
control how the list of
sort keys are sorted:
order
specifies whether the strings should be
sorted in ascending or descending order; ascending
specifies ascending order; descending
specifies
descending order; the default is ascending
lang
specifies the language of the sort keys; it
has the same range of values as xml:lang
[XML]; if no lang
value is specified, the
language should be determined from the system environment
data-type
specifies the data type of the
strings; the following values are allowed
text
specifies that the sort keys should be
sorted lexicographically in the culturally correct manner for the
language specified by lang
number
specifies that the sort keys should be
converted to numbers and then sorted according to the numeric value;
the value specified by lang
can be used to assist in the
conversion to numbers; leading and trailing whitespace should be
ignored when converting the sort keys to numbers
The default value is text
.
NOTE: The XSL Working Group plans that future versions of XSLT will leverage XML Schemas to define further values for this attribute.
case-order
has the value
upper-first
or lower-first
; this applies
when data-type="text"
, and specifies that upper-case
letters should sort before lower-case letters or vice-versa
respectively. For example, if lang="en"
, then A a B
b
are sorted with case-order="upper-first"
and
a A b B
are sorted with
case-order="lower-first"
. The default value is language
dependent.
The values of all of the above attributes are interpreted as attribute value templates.
NOTE: It is recommended that implementers consult [UNICODE TR10] for information on internationalized sorting.
The sort must be stable: in the sorted list of nodes, any sub list that has sort keys that all compare equal must be in document order.
For example, suppose an employee database has the form
<employees> <employee> <name> <first>James</first> <last>Clark</last> </name> ... </employee> </employees>
Then a list of employees sorted by name could be generated using:
<xsl:template match="employees"> <ul> <xsl:apply-templates select="employee"> <xsl:sort select="name/last"/> <xsl:sort select="name/first"/> </xsl:apply-templates> </ul> </xsl:template> <xsl:template match="employee"> <li> <xsl:value-of select="name/first"/> <xsl:text> </xsl:text> <xsl:value-of select="name/last"/> </li> </xsl:template>
A variable is a name that may be bound to a value. The value to
which a variable is bound (the value of the variable) can
be an object of any of the types that can be returned by expressions.
There are two elements that can be used to bind variables:
xsl:variable
and xsl:param
. The difference
is that the value specified on the xsl:param
variable is
only a default value for the binding; when the template or stylesheet
within which the xsl:param
element occurs is invoked,
parameters may be passed that are used in place of the default
values.
Both xsl:variable
and xsl:param
have a
required name
attribute, which specifies the name of the
variable. The value of the name
attribute is a QName, which is expanded as described
in [2.4 Qualified Names].
For any use of these variable-binding elements, there is a region of the stylesheet tree within which the binding is visible; within this region any binding of the variable that was visible on the variable-binding element itself is hidden. Thus, only the innermost binding of a variable is visible. The set of variable bindings in scope for an expression consists of those bindings that are visible at the point in the stylesheet where the expression occurs.
Variables introduce an additional data-type into the expression
language. This additional data type is called result tree
fragment. A variable may be bound to a result tree fragment
instead of one of the four basic XPath data-types (string, number,
boolean, node-set). A result tree fragment represents a fragment of
the result tree. A result tree fragment is treated equivalently to a
node-set that either is empty (in which case it is called an empty
result tree fragment) or contains just a single root node.
However, the operations permitted on a result tree fragment are a
subset of those permitted on a node-set. In particular, it is not
permitted to use the /
, //
, and
[]
operators on result tree fragments. The only
operations that can be performed on a result tree fragment are to
convert it to a string, a number or a boolean. These conversions are
performed exactly as if the result tree fragment were the equivalent
node-set.
When a result tree fragment is copied into the result tree (see
[12.3 Using Values of Variables and Parameters with
xsl:copy-of
]), then all the nodes that are children of the
root node in the equivalent node-set are added in sequence to the
result tree, unless the result tree is an empty result tree fragment,
in which case nothing is added.
Expressions can only return values of type result tree fragment by referencing variables of type result tree fragment or calling extension functions that return a result tree fragment or getting a system property whose value is a result tree fragment.
A variable-binding element can specify the value of the variable in two alternative ways.
If the variable-binding element has a select
attribute, then the value of the attribute must be an expression and the value of the variable
is the object that results from evaluating the expression.
If the variable-binding element does not have a select
attribute, then the contents of the variable-binding element specifies
the value. The contents of the variable-binding element is a template,
which is instantiated to give the value of the variable. The value is
a result tree fragment equivalent to a node-set containing just a
single root node having as children the sequence of nodes produced by
instantiating the template. However, if instantiating the template
produces no nodes, then the value will be an empty result tree
fragment. Thus, a variable-binding element with no select
attribute and no content binds the variable to an empty result tree
fragment.
It is an error if the sequence of nodes produced by instantiating the template includes an attribute node or a namespace node, since a root node cannot have an attribute node or a namespace node as a child. An XSLT processor may signal the error; if it does not signal the error, it must recover by not adding the attribute node or namespace node.
xsl:copy-of
The xsl:copy-of
element can be used to insert a result
tree fragment into the result tree, without first converting it to a
string as xsl:value-of
does (see [8.6.1 Generating Text with xsl:value-of
]). The required select
attribute
contains an expression. When
the result of evaluating the expression is a result tree fragment, the
complete fragment is copied into the result tree. When it is
node-set, all the nodes in the set together with their content are
copied in document order over into the result tree. When it is of any
other type, the result is converted to a string and then inserted into
the result tree, as with xsl:value-of
.
Both xsl:variable
and xsl:param
are
allowed as top-level elements.
A top-level variable-binding element declares a global variable that
is visible everywhere. A top-level xsl:param
element
declares a parameter to the stylesheet; XSLT does not define the
mechanism by which parameters are passed to the stylesheet. It is an
error if a stylesheet contains more than one binding of a top-level
variable the same name and same import precedence. An XSLT
processor may signal the error; if it does not signal the error, it
must recover by choosing from amongst the bindings with the highest
import precedence the one that occurs last in the stylesheet. At the
top-level, the expression or template specifying the variable value is
evaluated with the same context as that used to process the root node
of the source document: the current node is the root node of the
source document and the current node list is a list containing just
the root node of the source document. If the template or expression
specifying the value of a global variable x references a
global variable y, then the value for y must
be computed before the value of x. It is an error if it
is impossible to do this for all global variable definitions, in other
words it is an error if the definitions are circular.
This example declares a global variable para-font-size
,
which it references in an attribute value template.
<xsl:variable name="para-font-size">12pt</xsl:variable> <xsl:template match="para"> <fo:block font-size="{$para-font-size}"> <xsl:apply-templates/> </fo:block> </xsl:template>
As well as being allowed at the top-level, both
xsl:variable
and xsl:param
are also
allowed in templates. xsl:variable
is allowed anywhere
within a template that an instruction is allowed. In this case, the
binding is visible for all following siblings and their descendants.
Note that the binding is not visible for the xsl:variable
element itself. xsl:param
is allowed as a child
at the beginning of an xsl:template
element. In this
context, the binding is visible for all following siblings and their
descendants. Note that the binding is not visible for the
xsl:param
element itself.
A binding
shadows another binding if the binding occurs at a point
where the other binding is visible, and the bindings have the same
name. It is an error if a binding established by an
xsl:variable
or xsl:param
element within a
template shadows another binding
established by an xsl:variable
or xsl:param
element also within the template. It is not an error if a binding
established by an xsl:variable
or xsl:param
element in a template shadows
another binding established by an xsl:variable
or
xsl:param
top-level
element. Thus the following is an error:
<xsl:template name="foo"> <xsl:param name="x" select="1"/> <xsl:variable name="x" select="2"/> </xsl:template>
But the following is allowed:
<xsl:param name="x" select="1"/> <xsl:template name="foo"> <xsl:variable name="x" select="2"/> </xsl:template>
NOTE: The nearest equivalent in Java to axsl:variable
element in a template is a final local variable declaration with an initializer. For example,<xsl:variable name="x" select="'value'"/>has similar semantics tofinal Object x = "value";XSLT does not provide an equivalent to the Java assignment operatorx = "value";because this would make it harder to create an implementation which processed a document other than in a batch-like way, starting at the beginning and continuing through to the end.
Parameters are passed to templates using the
xsl:with-param
element. The required name
attribute specifies the name of the parameter (the variable the value
of whose binding is to be replaced). The value of the
name
attribute is a QName, which is expanded as described
in [2.4 Qualified Names]. xsl:with-param
is allowed
within both xsl:call-template
and
xsl:apply-templates
. The value of the parameter is
specified in the same way as for xsl:variable
and
xsl:param
. The current node and current node list used
for computing the value specified by xsl:with-param
element is the same as that used for the
xsl:apply-templates
or xsl:call-template
element within which it occurs. It is not an error to pass a
parameter x to a template that does not have an
xsl:param
element for x; the parameter is
simply ignored.
This example defines a named template for a
numbered-block
with an argument to control the format of
the number.
<xsl:template name="numbered-block"> <xsl:param name="format">1. </xsl:param> <xsl:number format="{$format}"/> <fo:block><xsl:apply-templates/></fo:block> </xsl:template> <xsl:template match="appendix/title"> <xsl:call-template name="numbered-block"> <xsl:with-param name="format">A. </xsl:with-param> </xsl:call-template> </xsl:template>
The xsl:message
instruction sends a message in a way
that is dependent on the XSLT processor. The content of the
xsl:message
instruction is a template. The
xsl:message
is instantiated by instantiating the content
to create an XML fragment. This XML fragment is the content of the
message.
NOTE: An XSLT processor might implement xsl:message
by
popping up an alert box or by writing to a log file.
This section describes XSLT-specific additions to the core XPath function library. Some of these additional functions also make use of information specified by top-level elements in the stylesheet; this section also describes these elements.
Function: node-set document(object, node-set?)
The document function allows access to XML documents other than the initial source document.
When the first argument to the document function is of type node-set, then the result is the union, for each node in the argument node-set, of the result of calling the document function with the first argument being the string value of the node, and the second argument being a node-set with the node as its only member.
When the first argument to the document function is of any other type, the first argument is converted to a string as if by a call to the string function. This string is treated as a URI reference; the resource identified by the URI is fetched; a tree for the entire resource is constructed; the function returns a node-set containing the nodes in the tree identified by the fragment identifier of the URI reference. The semantics of the fragment identifier is dependent on the media type of the result of retrieving the URI. If the URI reference does not contain a fragment identifier, then a node-set containing just the root node of the document is returned.
The URI reference may be relative. The base URI (see [3.2 Base URI]) of the node in the second argument node-set that is
first in document order is used as the base URI for resolving the
relative URI into an absolute URI. If the second argument is omitted,
then it defaults to the node in the stylesheet that contains the
expression that includes the call to the document
function. Note that a zero-length URI reference is a reference to the
document relative to which the URI reference is being resolved; thus
document("")
refers to the root node of the stylesheet;
the tree representation of the stylesheet is exactly the same as if
the XML document containing the stylesheet was the initial source
document.
Issue (non-node-set-fragment-identifier): What happens if the fragment identifier with
document()
identifies something that is not a node-set (e.g. a span or a substring within a text node)?
Issue (document-media-type): What are legal media types for the resource referenced by
document()
? For example, what happens if referencing the URI returns data with media typetext/plain
?
The document function gives rise to the possibility that a node-set may contain nodes from more than one document. With such a node-set, the relative document order of two nodes in the same document is the normal document order defined by XPath [XPath]. The relative document order of two nodes in different documents is determined by an implementation-dependent ordering of the documents containing the two nodes. There are no constraints on how the implementation orders documents other than that it must do so consistently: an implementation must always use the same order for the same set of documents.
Keys provide a way to work with documents that contain an implicit
cross-reference structure. The ID
, IDREF
and IDREFS
attribute types in XML provide a mechanism to
allow XML documents to make their cross-reference explicit. XSLT
supports this through the XPath id function.
However, this mechanism has a number of limitations:
ID attributes must be declared as such in the DTD. If an ID
attribute is declared as an ID attribute only in the external DTD
subset, then it will be recognized as an ID attribute only if the XML
processor reads the external DTD subset. However, XML does not require
XML processors to read the external DTD, and they may well choose not
to do so, especially if the document is declared
standalone="yes"
.
A document can contain only a single set of unique IDs. There cannot be separate independent sets of unique IDs.
The ID of an element can only be specified in an attribute; in cannot be specified by the content of the element, or by a child element.
An ID is constrained to be an XML name. For example, it cannot contain spaces.
An element can have at most one ID.
At most one element can have a particular ID.
Because of these limitations XML documents sometimes contain a cross-reference structure that is not explicitly declared by ID/IDREF/IDREFS attributes.
A key is a triple containing:
the node which has the key
the name of the key (an expanded name)
the value of the key (a string)
A stylesheet declares a set of keys for each document using the
xsl:key
. When this set of keys contains a member with
node x, name y and value z, we
say that node x has a key with name y and
value z.
Thus, a key is a kind of generalized ID, which is not subject to the same limitations as an XML ID:
Keys are declared in the stylesheet using
xsl:key
elements.
A key has a name as well as a value; each key name may be thought of as distinguishing a separate, independent space of identifiers.
The value of a named key for an element may be specified in any convenient place; for example, in an attribute, in a child element or in content. An XPath expression is used to specify where to find the value for a particular named key.
The value of a key can be an arbitrary string; it is not constrained to be a name.
There can be multiple keys in a document with the same node, same key name, but different key values.
There can be multiple keys in a document with the same key name, same key value, but different nodes.
The xsl:key
element is used to declare keys. The
name
attribute specifies the name of the key. The value
of the name
attribute is a QName, which is expanded as described
in [2.4 Qualified Names]. The match
attribute is a Pattern; an xsl:key
element gives
information about the keys of any node that matches the pattern
specified in the match attribute. The use
attribute is
an expression specifying where
values of the key are to be found; the expression is evaluated once
for each node that matches the pattern. The result in each case must
be a node-set. For each node in the node-set, the node that matches
the pattern has a key of the specified name whose value is the value
of the node in the node-set. Thus, a node x has a key
with name y and value z if and only if there
is an xsl:key
element such that:
x matches the pattern specified in the
match
attribute of the xsl:key
element;
the value of the name
attribute of the
xsl:key
element is equal to y;
and
z is the value of one or more of the nodes in
the node-set that results from evaluating the expression specified in
the use
attribute of the xsl:key
element
with x as the current node and with a node list
containing just x as the current node list.
Note also that there may be more than one xsl:key
element that matches a given node; all of the matching
xsl:key
elements are used.
Function: node-set key(string, object)
The key function does for keys what the id function does for IDs. The first argument specifies the name of the key. The value of the argument must be a QName, which is expanded as described in [2.4 Qualified Names]. When the second argument to the key function is of type node-set, then the result is the union of the result of applying the key function to the string value of each of the nodes in the argument node-set. When the second argument to key is of any other type, the argument is converted to a string as if by a call to the string function; it returns a node-set containing the nodes in the same document as the context node that have a value for the named key equal to this string.
For example, given a declaration
<xsl:key name="idkey" match="div" use="@id"/>
an expression key("idkey",@ref)
will return the same
node-set as id(@ref)
, assuming that the only ID attribute
declared in the XML source document is:
<!ATTLIST div id ID #IMPLIED>
and that the ref
attribute of the current node
contains no whitespace.
Suppose a document describing a function library uses a
prototype
element to define functions
<prototype name="key" return-type="node-set"> <arg type="string"/> <arg type="object"/> </prototype>
and a function
element to refer to function names
<function>key</function>
Then the stylesheet could generate hyperlinks between the references and definitions as follows:
<xsl:key name="func" match="prototype" use="@name"/> <xsl:template match="function"> <b> <a href="{generate-id(key('func',.))}"> <xsl:apply-templates/> </a> </b> </xsl:template> <xsl:template match="prototype"> <p><a name="{generate-id()}"> <b>Function: </b> ... </xsl:template>
Issue (format-number-schemas): The Schema Datatypes WD has a facility for constraining the format of strings that in some cases supports conversion of strings to numbers. Can this be unified with what we have here?
Function: string format-number(number, string, string?)
The format-number function converts its first argument to a string using the format pattern string specified by the second argument and the locale named by the third argument, or the default locale, if there is no third argument. The format pattern string is in the syntax specified by the JDK 1.1 DecimalFormat class. The format pattern string is in a localized notation: the locale determines what characters have a special meaning in the pattern (with the exception of the quote character, which is not localized). The format pattern must not contain the currency sign (#x00A4); support for this feature was added after the initial release of JDK 1.1. The locale name must be a QName, which is expanded as described in [2.4 Qualified Names].
The xsl:locale
element declares a locale, which
controls the interpretation of a format pattern used by the
format-number function. If there is a
name
attribute, then the element declares a named locale;
otherwise, it declares the default locale. The value of the
name
attribute is a QName, which is expanded as described
in [2.4 Qualified Names].
The other attributes on xsl:locale
correspond to the
methods on the JDK 1.1 DecimalFormatSymbols class. For each
get
/set
method pair there is an attribute
defined for the xsl:locale
element. The default values
are given in the XSLT DTD (see [A DTD Fragment for XSLT Stylesheets]).
The following attributes both control the interpretation of characters in the format pattern and specify characters that may appear in the result of formatting the number:
decimal-separator
specifies the character used
for the decimal sign
grouping-separator
specifies the character used
as a grouping (e.g. thousands) separator
percent
specifies the character used as a
percent sign
per-mille
specifies the character used as a per
mille sign
zero-digit
specifies the character used as the
digit zero
The following attributes control the interpretation of characters in the format pattern:
digit
specifies the character used for a digit
in the format pattern
pattern-separator
specifies the character used
to separate positive and negative sub patterns in a pattern
The following attributes specify strings that may appear in the result of formatting the number:
infinity
specifies the string used to represent
infinity
NaN
specifies the string used to represent the
NaN value
minus-sign
specifies the string used as the
default minus sign
Issue (locale-number-harmonize): Can the
xsl:number
andxsl:locale
elements be harmonized more?
Function: string unparsed-entity-uri(string)
The unparsed-entity-uri returns the URI of the unparsed entity with the specified name in the same document as the context node (see [3.3 Unparsed Entities]). It returns the empty string if there is no such entity.
Function: string generate-id(node-set?)
The generate-id function returns a string that uniquely identifies the node in the argument node-set that is first in document order. The unique identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name. An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed. There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document. If the argument node-set is empty, the empty string is returned. If the argument is omitted, it defaults to the context node.
Function: object system-property(string)
The argument must evaluate to a string that is a QName. The QName is expanded into a name using the namespace declarations in scope for the expression. The system-property function returns an object representing the value of the system property identified by the name. If the name has no namespace, then the system-property function must return the string value of the operating system environment variable whose name is equal to the local part of the name. If there is no such system property, the empty string should be returned.
Implementations must provide the following system properties, which are all in the XSLT namespace:
xsl:version
, a number giving the version of XSLT
implemented by the processor; for XSLT processors implementing the
version of XSLT specified by this document, this is the number
1.0xsl:vendor
, a string identifying the vendor of the
XSLT processorxsl:vendor-url
, a string containing a URL
identifying the vendor of the XSLT processor (typically the host page
of the vendor's Web site)XSLT allows two kinds of extension, extension elements and extension functions.
This version of XSLT does not provide a mechanism for defining implementations of extensions. Therefore, an XSLT stylesheet that must be portable between XSLT implementations cannot rely on particular extensions being available. XSLT provides mechanisms that allow an XSLT stylesheet to determine whether the XSLT processor by which it is being processed has implementations of particular extensions available, and to specify what should happen if those extensions are not available. If an XSLT stylesheet is careful to make use of these mechanisms, it is possible for it to take advantage of extensions and still work with any XSLT implementation.
The element extension mechanism allows namespaces to be designated as extension namespaces. When a namespace is designated as an extension namespace and an element with a name from that namespace occurs in a template, then the element is treated as an instruction rather than as a literal result element. The namespace determines the semantics of the instruction.
NOTE: Since an element that is a child of an
xsl:stylesheet
element is not occurring in a
template, non-XSLT top-level elements are not extension
elements as defined here, and nothing in this section applies to
them.
A namespace is designated as an extension namespace by using an
extension-element-prefixes
attribute on an
xsl:stylesheet
element or an
xsl:extension-element-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 extension namespace. The
default namespace (as declared by xmlns
) may be
designated as an extension namespace by including
#default
in the list of namespace prefixes. The
designation of a namespace as an extension namespace is effective
within the subtree of the stylesheet rooted at the element bearing the
extension-element-prefixes
or
xsl:extension-element-prefixes
attribute.
If the XSLT processor does not have an implementation of a
particular extension element available, then the
extension-element-available function must return
false for the name of the element. If such an extension element
occurs in a template and the extension element is actually
instantiated, then the XSLT processor must signal an error unless the
extension element has one or more xsl:fallback
children
elements, in which case the content of each of the
xsl:fallback
children must be instantiated in sequence,
instead of signaling an error. The content of an
xsl:fallback
element is a template. An XSLT processor
must not signal an error merely because a template contains an
extension element for which no implementation is available.
If the XSLT processor has an implementation of a particular
extension element available, then the
extension-element-available function must return
true for the name of the element. When such an extension element is
instantiated, any xsl:fallback
children elements must be
ignored.
Function: boolean extension-element-available(string)
The argument must evaluate to a string that is a QName. The QName is expanded into a name using the namespace declarations in scope for the expression. The extension-element-available function returns true if and only if the XSLT processor has an implementation of the named extension element available.
If a FunctionName in a FunctionCall expression is not an NCName (i.e. if it contains a colon), then it is treated as a call to an extension function. The FunctionName is expanded to a name using the namespace declarations from the evaluation context.
If the XSLT processor does not have an implementation of an extension function of a particular name available, then the extension-function-available function must return false for that name. If such an extension function occurs in an expression and the extension function is actually called, the XSLT processor must signal an error. An XSLT processor must not signal an error merely because an expression contains an extension function for which no implementation is available.
If the XSLT processor has an implementation of an extension function of a particular name available, then the extension-function-available function must return true for that name. If such an extension is called, then the XSLT processor must call the implementation passing it the function call arguments; the result returned by the implementation is returned as the result of the function call.
Function: boolean extension-function-available(string)
The argument must evaluate to a string that is a QName. The QName is expanded into a name using the namespace declarations in scope for the expression. The extension-function-available function returns true if and only if the XSLT processor has an implementation of the named extension function is available.
The following entity can be used to construct a DTD for XSLT
stylesheets that create instances of a particular result DTD. Before
referencing the entity, the stylesheet DTD must define a
result-elements
parameter entity listing the allowed
result element types. For example:
<!ENTITY % result-elements " | fo:inline-sequence | fo:block ">
Such result elements should be declared to have
xsl:use-attribute-sets
and
xsl:extension-element-prefixes
attributes. The following
entity declares the result-element-atts
parameter for
this purpose. The content that XSLT allows for result elements is the
same as it allows for the XSLT elements that are declared in the
following entity with a content model of %template;
. The
DTD may use a more restrictive content model than
%template;
to reflect the constraints of the result
DTD.
The DTD may define the non-xsl-top-level
parameter
entity to allow additional top-level elements from namespaces other
than the XSLT namespace.
The use of the xsl:
prefix in this DTD does not imply
that XSLT stylesheets are required to use this prefix. Any of the
elements declared in this DTD may have attributes whose name starts
with xmlns:
or is equal to xmlns
in addition
to the attributes declared in this DTD.
<!ENTITY % char-instructions " | xsl:apply-templates | xsl:call-template | xsl:apply-imports | xsl:for-each | xsl:value-of | xsl:copy-of | xsl:number | xsl:choose | xsl:if | xsl:text | xsl:copy | xsl:variable | xsl:message "> <!ENTITY % instructions " %char-instructions; | xsl:processing-instruction | xsl:comment | xsl:element | xsl:attribute "> <!ENTITY % char-template " (#PCDATA %char-instructions;)* "> <!ENTITY % template " (#PCDATA %instructions; %result-elements;)* "> <!-- Used for the type pf an attribute value that is a URI reference.--> <!ENTITY % URI "CDATA"> <!-- Used for the type of an attribute value that is a pattern.--> <!ENTITY % pattern "CDATA"> <!-- Used for the type of an attribute value that is an attribute value template.--> <!ENTITY % avt "CDATA"> <!-- Used for the type of an attribute value that is a QName; the prefix gets expanded by the XSLT processor. --> <!ENTITY % qname "NMTOKEN"> <!-- Like qname but a whitespace-separated list of QNames. --> <!ENTITY % qnames "NMTOKENS"> <!-- Used for the type of an attribute value that is an expression.--> <!ENTITY % expr "CDATA"> <!-- Used for the type of an attribute value that consists of a single character.--> <!ENTITY % char "CDATA"> <!-- Used for the type of an attribute value that is a priority. --> <!ENTITY % priority "NMTOKEN"> <!ENTITY % space-att "xml:space (default|preserve) #IMPLIED"> <!-- This may be overridden to customize the set of elements allowed at the top-level. --> <!ENTITY % non-xsl-top-level ""> <!ENTITY % top-level " (xsl:import*, (xsl:include | xsl:strip-space | xsl:preserve-space | xsl:key | xsl:locale | xsl:attribute-set | xsl:variable | xsl:param | xsl:template %non-xsl-top-level;)*) "> <!-- result-ns is not declared as type NMTOKEN because it may be empty; extension-element-prefixes is not declared as NMTOKENS because it may include #default --> <!ENTITY % top-level-atts ' default-space (preserve|strip) "preserve" extension-element-prefixes CDATA #IMPLIED indent-result (yes|no) "no" result-ns CDATA #IMPLIED result-version NMTOKEN "1.0" result-encoding NMTOKEN #IMPLIED id ID #IMPLIED xmlns:xsl CDATA #FIXED "http://www.w3.org/XSL/Transform/1.0" %space-att; '> <!-- This entity is defined for use in the ATTLIST declaration for result elements. --> <!ENTITY % result-element-atts ' xsl:extension-element-prefixes CDATA #IMPLIED xsl:use-attribute-sets %qnames; #IMPLIED '> <!ELEMENT xsl:stylesheet %top-level;> <!ATTLIST xsl:stylesheet %top-level-atts;> <!ELEMENT xsl:transform %top-level;> <!ATTLIST xsl:transform %top-level-atts;> <!ELEMENT xsl:import EMPTY> <!ATTLIST xsl:import href %URI; #REQUIRED> <!ELEMENT xsl:include EMPTY> <!ATTLIST xsl:include href %URI; #REQUIRED> <!ELEMENT xsl:strip-space EMPTY> <!ATTLIST xsl:strip-space elements %qnames; #REQUIRED> <!ELEMENT xsl:preserve-space EMPTY> <!ATTLIST xsl:preserve-space elements %qnames; #REQUIRED> <!ELEMENT xsl:key EMPTY> <!ATTLIST xsl:key name %qname; #REQUIRED match %pattern; #REQUIRED use %expr; #REQUIRED > <!ELEMENT xsl:locale EMPTY> <!ATTLIST xsl:locale name %qname; #IMPLIED decimal-separator %char; "." grouping-separator %char; "," infinity CDATA "∞" minus-sign %char; "-" NaN CDATA "�" percent %char; "%" per-mille %char; "‰" zero-digit %char; "0" digit %char; "#" pattern-separator %char; ";" > <!ELEMENT xsl:template (#PCDATA %instructions; %result-elements; | xsl:param)* > <!ATTLIST xsl:template match %pattern; #IMPLIED name %qname; #IMPLIED priority %priority; #IMPLIED mode %qname; #IMPLIED %space-att; > <!ELEMENT xsl:value-of EMPTY> <!ATTLIST xsl:value-of select %expr; #REQUIRED > <!ELEMENT xsl:copy-of EMPTY> <!ATTLIST xsl:copy-of select %expr; #REQUIRED> <!ELEMENT xsl:number EMPTY> <!ATTLIST xsl:number level (single|multiple|any) "single" count %pattern; #IMPLIED from %pattern; #IMPLIED value %expr; #IMPLIED format %avt; '1' lang %avt; #IMPLIED letter-value %avt; #IMPLIED grouping-separator%avt; #IMPLIED grouping-size %avt; #IMPLIED > <!ELEMENT xsl:apply-templates (xsl:sort|xsl:with-param)*> <!ATTLIST xsl:apply-templates select %expr; "node()" mode %qname; #IMPLIED > <!ELEMENT xsl:apply-imports EMPTY> <!-- xsl:sort cannot occur after any other elements or any non-whitespace character --> <!ELEMENT xsl:for-each (#PCDATA %instructions; %result-elements; | xsl:sort)* > <!ATTLIST xsl:for-each select %expr; #REQUIRED %space-att; > <!ELEMENT xsl:sort EMPTY> <!ATTLIST xsl:sort select %expr; "." lang %avt; #IMPLIED data-type %avt; "text" order %avt; "ascending" case-order %avt; #IMPLIED > <!ELEMENT xsl:if %template;> <!ATTLIST xsl:if test %expr; #REQUIRED %space-att; > <!ELEMENT xsl:choose (xsl:when+, xsl:otherwise?)> <!ATTLIST xsl:choose %space-att;> <!ELEMENT xsl:when %template;> <!ATTLIST xsl:when test %expr; #REQUIRED %space-att; > <!ELEMENT xsl:otherwise %template;> <!ATTLIST xsl:otherwise %space-att;> <!ELEMENT xsl:attribute-set (xsl:attribute)*> <!ATTLIST xsl:attribute-set name %qname; #REQUIRED use-attribute-sets %qnames; #IMPLIED > <!ELEMENT xsl:call-template (xsl:with-param)*> <!ATTLIST xsl:call-template name %qname; #REQUIRED > <!ELEMENT xsl:with-param %template;> <!ATTLIST xsl:with-param name %qname; #REQUIRED select %expr; #IMPLIED > <!ELEMENT xsl:variable %template;> <!ATTLIST xsl:variable name %qname; #REQUIRED select %expr; #IMPLIED > <!ELEMENT xsl:param %template;> <!ATTLIST xsl:param name %qname; #REQUIRED select %expr; #IMPLIED > <!ELEMENT xsl:text (#PCDATA)> <!ELEMENT xsl:processing-instruction %char-template;> <!ATTLIST xsl:processing-instruction name %avt; #REQUIRED %space-att; > <!ELEMENT xsl:element %template;> <!ATTLIST xsl:element name %avt; #REQUIRED namespace %avt; #IMPLIED use-attribute-sets %qnames; #IMPLIED %space-att; > <!ELEMENT xsl:attribute %char-template;> <!ATTLIST xsl:attribute name %avt; #REQUIRED namespace %avt; #IMPLIED %space-att; > <!ELEMENT xsl:comment %char-template;> <!ATTLIST xsl:comment %space-att;> <!ELEMENT xsl:copy %template;> <!ATTLIST xsl:copy %space-att; use-attribute-sets %qnames; #IMPLIED > <!ELEMENT xsl:message %template;> <!ATTLIST xsl:message %space-att;> <!ELEMENT xsl:fallback %template;> <!ATTLIST xsl:fallback %space-att;>
This example is a stylesheet for transforming documents that conform to a simple DTD into XHTML. The DTD is:
<!ELEMENT doc (title, chapter*)> <!ELEMENT chapter (title, (para|note)*, section*)> <!ELEMENT section (title, (para|note)*)> <!ELEMENT title (#PCDATA|emph)*> <!ELEMENT para (#PCDATA|emph)*> <!ELEMENT note (#PCDATA|emph)*> <!ELEMENT emph (#PCDATA|emph)*>
The stylesheet is:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0" xmlns="http://www.w3.org/TR/xhtml1" indent-result="yes"> <xsl:strip-space elements="doc chapter section"/> <xsl:template match="doc"> <html> <head> <title> <xsl:value-of select="title"/> </title> </head> <body> <xsl:apply-templates/> </body> </html> </xsl:template> <xsl:template match="doc/title"> <h1> <xsl:apply-templates/> </h1> </xsl:template> <xsl:template match="chapter/title"> <h2> <xsl:apply-templates/> </h2> </xsl:template> <xsl:template match="section/title"> <h3> <xsl:apply-templates/> </h3> </xsl:template> <xsl:template match="para"> <p> <xsl:apply-templates/> </p> </xsl:template> <xsl:template match="note"> <p class="note"> <b>NOTE: </b> <xsl:apply-templates/> </p> </xsl:template> <xsl:template match="emph"> <em> <xsl:apply-templates/> </em> </xsl:template> </xsl:stylesheet>
With the following input document
<!DOCTYPE doc SYSTEM "doc.dtd"> <doc> <title>Document Title</title> <chapter> <title>Chapter Title</title> <section> <title>Section Title</title> <para>This is a test.</para> <note>This is a note.</note> </section> <section> <title>Another Section Title</title> <para>This is <emph>another</emph> test.</para> <note>This is another note.</note> </section> </chapter> </doc>
it would produce the following result
<html xmlns="http://www.w3.org/TR/xhtml1"> <head> <title>Document Title</title> </head> <body> <h1>Document Title</h1> <h2>Chapter Title</h2> <h3>Section Title</h3> <p>This is a test.</p> <p class="note"> <b>NOTE: </b>This is a note.</p> <h3>Another Section Title</h3> <p>This is <em>another</em> test.</p> <p class="note"> <b>NOTE: </b>This is another note.</p> </body> </html>
This is an example of transforming some data represented in XML using two different XSLT stylesheets to produce two different representations of the data, one in XHTML (see [XHTML]) and one in SVG.
The input data is:
<sales> <division id="North"> <revenue>10</revenue> <growth>9</growth> <bonus>7</bonus> </division> <division id="South"> <revenue>4</revenue> <growth>3</growth> <bonus>4</bonus> </division> <division id="West"> <revenue>6</revenue> <growth>-1.5</growth> <bonus>2</bonus> </division> </sales>
The following stylesheet transforms the data into XHTML:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0" xmlns="http://www.w3.org/TR/xhtml1" indent-result="yes"> <xsl:template match="/"> <html> <head> <title>Sales Results By Division</title> </head> <body> <table border="1"> <tr> <th>Division</th> <th>Revenue</th> <th>Growth</th> <th>Bonus</th> </tr> <xsl:for-each select="sales/division"> <!-- order the result by revenue --> <xsl:sort select="revenue" data-type="number" order="descending"/> <tr> <td> <em><xsl:value-of select="@id"/></em> </td> <td> <xsl:value-of select="revenue"/> </td> <td> <!-- highlight negative growth in red --> <xsl:if test="growth < 0"> <xsl:attribute name="style"> <xsl:text>color:red</xsl:text> </xsl:attribute> </xsl:if> <xsl:value-of select="growth"/> </td> <td> <xsl:value-of select="bonus"/> </td> </tr> </xsl:for-each> </table> </body> </html> </xsl:template> </xsl:stylesheet>
The XHTML output is:
<html xmlns="http://www.w3.org/TR/xhtml1"> <head> <title>Sales Results By Division</title> </head> <body> <table border="1"> <tr> <th>Division</th> <th>Revenue</th> <th>Growth</th> <th>Bonus</th> </tr> <tr> <td><em>North</em></td> <td>10</td> <td>9</td> <td>7</td> </tr> <tr> <td><em>West</em></td> <td>6</td> <td style="color:red">-1.5</td> <td>2</td> </tr> <tr> <td><em>South</em></td> <td>4</td> <td>3</td> <td>4</td> </tr> </table> </body> </html>
The following stylesheet transforms the data into SVG:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0" xmlns="http://www.w3.org/Graphics/SVG/svg-19990412.dtd" indent-result="yes"> <xsl:template match="/"> <svg width = "3in" height="3in"> <g style = "stroke: #000000"> <!-- draw the axes --> <line x1="0" x2="150" y1="150" y2="150"/> <line x1="0" x2="0" y1="0" y2="150"/> <text x="0" y="10">Revenue</text> <text x="150" y="165">Division</text> <xsl:for-each select="sales/division"> <!-- define some useful variables --> <!-- the bar's x position --> <xsl:variable name="pos" select="(position()*40)-30"/> <!-- the bar's height --> <xsl:variable name="height" select="revenue*10"/> <!-- the rectangle --> <rect x="{$pos}" y="{150-$height}" width="20" height="{$height}"/> <!-- the text label --> <text x="{$pos}" y="165"> <xsl:value-of select="@id"/> </text> <!-- the bar value --> <text x="{$pos}" y="{145-$height}"> <xsl:value-of select="revenue"/> </text> </xsl:for-each> </g> </svg> </xsl:template> </xsl:stylesheet>
The SVG output is:
<svg width="3in" height="3in" xmlns="http://www.w3.org/Graphics/SVG/svg-19990412.dtd"> <g style="stroke: #000000"> <line x1="0" x2="150" y1="150" y2="150"/> <line x1="0" x2="0" y1="0" y2="150"/> <text x="0" y="10">Revenue</text> <text x="150" y="165">Division</text> <rect x="10" y="50" width="20" height="100"/> <text x="10" y="165">North</text> <text x="10" y="45">10</text> <rect x="50" y="110" width="20" height="40"/> <text x="50" y="165">South</text> <text x="50" y="105">4</text> <rect x="90" y="90" width="20" height="60"/> <text x="90" y="165">West</text> <text x="90" y="85">6</text> </g> </svg>
The following have contributed to authoring this draft:
This specification was developed and approved for publication by the W3C XSL Working Group (WG). WG approval of this specification does not necessarily imply that all WG members voted for its approval. The current members of the XSL WG are:
Sharon Adler, Inso (Co-Chair); Anders Berglund, Inso; Perin Blanchard, Novell; Scott Boag, Lotus; Jeff Caruso, Bitstream; James Clark; Peter Danielsen, Bell Labs; Don Day, IBM; Stephen Deach, Adobe; Angel Diaz, IBM; Dwayne Dicks, SoftQuad; Andrew Greene, Bitstream; Paul Grosso, Arbortext; Eduardo Gutentag, Sun; Juliane Harbarth, Software AG; Mickey Kimchi, Enigma; Chris Lilley, W3C; Chris Maden, O'Reilly; Jonathan Marsh, Microsoft; Alex Milowski, Lexica; Boris Moore, RivCom; Steve Muench, Oracle; Carolyn Pampino, Interleaf; Scott Parnell, Xerox; Vincent Quint, W3C; Dan Rapp, Novell; Gregg Reynolds, Datalogics; Jonathan Robie, Software AG; Mark Scardina, Oracle; Henry Thompson, University of Edinburgh; Philip Wadler, Bell Labs; Norman Walsh, Arbortext; Sanjiva Weerawarana, IBM; Umit Yalcinalp, Sun; Steve Zilles, Adobe (Co-Chair)Changes to the part of the expression language that has been separated out into XPath are described in the XPath Working Draft [XPath].
An unparsed-entity-uri function has been added.
The xml:lang
attribute on xsl:number
has
been renamed to lang
.
The key
and keyref
functions have been
merged into the key function.
The doc
and docref
functions have been
merged into the document function.
Implementations are no longer required to detect non-terminating processing loops.
A built-in template rule for attribute nodes has been added (see [6.8 Built-in Template Rules]).
The default priority values have been changed from 1 and -1 to 0.5 and -0.5 (see [6.5 Conflict Resolution for Template Rules]).
It is an error to use xsl:element
or
xsl:attribute
to create an element or attribute with an
illegal name.
An empty value for the namespace
attribute on
xsl:element
or xsl:attribute
causes the name
of the element or attribute not to have a namespace URI.
It is an error to use xsl:processing-instruction
to
create a processing instruction with an illegal target name.
The behavior of xsl:number
with level
any
when the current node does not match the
count
pattern has been changed (see [8.7 Numbering]).
Adding a duplicate attribute to an element replaces the previous
attribute (see [8.1.3 Creating Attributes with xsl:attribute
]).
The xsl:use-attribute-set
element has been replaced by
use-attribute-sets
and xsl:use-attribute-sets
attributes (see [8.1.4 Named Attribute Sets]).
A result-version
attribute has been added to
xsl:stylesheet
for specifying the version of XML to be
used for outputting the result tree (see [4 Using the Result Tree]).
A result-encoding
attribute has been added to
xsl:stylesheet
(see [4 Using the Result Tree]).
Restrictions on the children of the root node of the source and result trees have been relaxed (see [3.1 Root Node Children]).
Names of internal XSLT objects (named templates, modes, attribute sets, keys, locales, variables, parameters) may have prefixes (see [2.4 Qualified Names]).
A literal result element may be used as a stylesheet (see [2.3 Literal Result Element as Stylesheet]).
The digit-group-sep
attribute on
xsl:number
has been renamed to
grouping-separator
.
The n-digits-per-group
attribute on
xsl:number
has been renamed to
grouping-size
.
The expr
attribute on
xsl:number
has been renamed to
value
.
The expr
attribute on xsl:variable
,
xsl:param
and xsl:with-param
has been
renamed to select
.
The sequence-src
attribute on xsl:number
has been removed.
System properties xsl:vendor
and
xsl:vendor-url
have been added (see [14.4 Miscellaneous Additional Functions]).
The xsl:functions
element has been removed.
The function-available
function has been renamed to
extension-function-available.
An element extension mechanism has been added (see [15.1 Extension Elements]).
The per-mill
attribute on xsl:locale
has
been renamed to per-mille
(see [14.3 Number Formatting]).
The document function now has an optional second argument giving the node from which to get the base URI for resolving relative URIs.
The xsl:copy-of
element is no longer restricted to
result tree fragments and node-sets; for other types of object it
behaves like xsl:value-of
(see [12.3 Using Values of Variables and Parameters with
xsl:copy-of
]).
When there is no matching template rule in a mode, then the built-in template rules now continue processing in that same mode (see [6.8 Built-in Template Rules]).
xsl:param-variable
has been renamed to
xsl:param
and xsl:param
has been renamed to
xsl:with-param
.
The xsl:stylesheet
element may contain elements from
non-XSLT namespaces (see [2.2 Stylesheet Element]).
It is an error if a variable or parameter binding established within a template shadows another variable or parameter binding also established within the template.
The multi
value for the level
attribute
on xsl:number
has been renamed to
multiple
.
The following features are under consideration for future versions of XSLT:
a conditional function if(boolean, object,
object)
;
a function current()
that returns the current
node (i.e. the context node for the outermost expression);
support for XML Schema datatypes and archetypes;
support for something like style rules in the original XSL submission;
an attribute to control the default namespace for names occurring in XSLT attributes;
support for entity references;
support for DTDs in the data model;
support for notations in the data model;
a way to get back from an element to the elements that reference it (e.g. by IDREF attributes);
an easier way to get an ID in another document;
support for regular expressions for matching against any or all of text nodes, attribute values, attribute names, element type names;
case-insensitive comparisons;
normalization of strings before comparison, for example for compatibility characters;
a function string resolve(node-set)
function
that treats the value of the argument as a relative URI and turns it
into an absolute URI using the base URI of the node;
multiple result trees;
defaulting the select
attribute on
xsl:value-of
to the current node;
an attribute on xsl:attribute
to control how the
attribute value is normalized;
an attribute on xsl:sort
containing a label that
identifies the sorting scheme;
a way to put the text of a resource identified by a URI into the result tree;
allow unions in steps eg foo/(bar|baz)
.