PRODUCTS

DOWNLOAD

BUY

LEARN

SUPPORT

COMPANY

Cart

< Previous | Next >

XSLT Instructions Quick Reference

This section provides a quick reference for the XSLT instructions supported by the Stylus Studio XSLT processor. For additional information, see the W3C XSLT Recommendation. The instructions described in this section are listed below.

xsl:apply-imports

xsl:apply-templates

xsl:attribute

xsl:attribute-set

xsl:call-template

xsl:choose

xsl:comment

xsl:copy

xsl:copy-of

xsl:decimal-format

xsl:element

xsl:fallback

xsl:for-each

xsl:if

xsl:import

xsl:include

xsl:key

xsl:message

xsl:namespace-alias

xsl:number

xsl:otherwise

xsl:output

xsl:param

xsl:preserve-space

xsl:processing-instruction

xsl:sort

xsl:strip-space

xsl:stylesheet

xsl:template

xsl:text

xsl:transform

xsl:value-of

xsl:variable

xsl:when

xsl:with-param

xsl:apply-imports

Invokes overridden template rules.

Stylus Studio does not support the xsl:apply-imports instruction.

xsl:apply-templates

Selects source nodes for processing.

Format


<xsl:apply-templates [select="pattern"][mode="qname"]> [<xsl:sort/>] [<xsl:with-param/> </xsl:apply-templates>

Description

If you specify the select attribute, specify a pattern that resolves to a set of source nodes. For each source node in this set, the XSLT processor searches for a template that matches the node. When it finds a matching template, it instantiates it and uses the node as the context node. For example:


<xsl:apply-templates select="/bookstore/book">

When the XSLT processor executes this instruction, it constructs a list of all nodes that match the pattern in the select attribute. For each node in the list, the XSLT processor searches for the template whose match pattern best matches that node.

If you do not specify the select attribute, the XSLT processor uses the default pattern, "node()", which selects all child nodes of the current node.

If you specify the mode attribute, the selected nodes are matched only by templates with a matching mode attribute. The value of mode must be a qualified name or an asterisk ( *). If you specify an asterisk, it means continue the current mode, if any, of the current template.

If you do not specify a mode attribute, the selected nodes are matched only by templates that do not specify a mode attribute.

By default, the new list of source nodes is processed in document order. However, you can use the xsl:sort instruction to specify that the selected nodes are to be processed in a different order. See xsl:sort.


Tip		You can create an `xsl:apply-templates` element automatically using the XSLT mapper.

Example

In the previous example, the XSLT processor searches for a template that matches /bookstore/book. The following template is a match:

<xsl:template match="book">
               

              
                <tr><td><xsl:value-of select="title"/></td>
                   
<td><xsl:value-of select="author"/><td>
                   
<td><xsl:value-of select="price"/><td></tr>
                   

                
              
</xsl:template>

The XSLT processor instantiates this template for each book element.

xsl:attribute

Creates an attribute.

Format


`<xsl:attribute name="`qualified_name `">` attribute_value </xsl:attribute>

Description

You can specify the xsl:attribute instruction in the

Contents of a stylesheet element that creates a result element

Contents of an xsl:attribute-set instantiation

In a stylesheet element that creates a result element, the xsl:attribute instruction causes an attribute to be added to the created result element.

The prefix part of the name attribute value becomes the prefix for the attribute you are creating. The local part of the name attribute value becomes the local name of the attribute you are creating.

The XSLT processor interprets the name attribute as an attribute value template. The string that results from instantiating the attribute value template must be a qualified name. If it is not, the XSLT processor reports an error.

The result of instantiating the content of the xsl:attribute instruction is used as the value of the created attribute. It is an error if instantiating this content generates anything other than characters.

If you add an attribute to an element and that element already has an attribute with the same expanded name, the attribute you are creating replaces the existing attribute.

Example


`<xsl:attribute name="library:ISBN"` `namespace="http://www.library.org/namespaces/library">` 1-2222-333-4 </xsl:attribute>

If this instruction is inside a book element, the resulting book element would include the following attribute:


library:ISBN="1-22222-333-4"

The XSLT processor reports an error if you try to do any of the following:

Add an attribute to a node that is not an element.

Add an attribute to an element that already has child nodes.

Create anything other than characters during instantiation of the contents of the xsl:attribute element.

xsl:attribute-set

Defines a named set of attributes.

Format

<xsl:attribute-set name="set_name"> 
               

              
                <xsl:attribute name="attr_name">attr_value</xsl:attribute>
                   
<xsl:attribute name="attr_name">attr_value</xsl:attribute> 
                   
...
                   

                
              
</xsl:attribute-set>

Description

The name attribute specifies the name of the attribute set. This must be a qualified name. The contents of the xsl:attribute-set element consists of zero or more xsl:attribute elements. Each xsl:attribute element specifies an attribute in the set.

To use an attribute set, specify the use-attribute-sets attribute in one of the following elements:

xsl:element

xsl:copy

xsl:attribute-set

The value of the use-attribute-sets attribute is a white-space-separated list of names of attribute sets. When you specify the use of an attribute set, it is equivalent to adding an xsl:attribute element for each attribute in each named attribute set to the beginning of the contents of the element in which you specify the use-attribute-sets attribute.

An attribute set cannot include itself. In other words, if attribute set A specifies the use-attribute-sets attribute, the list of attribute sets to use cannot include attribute set A.

You can also specify an attribute set in an xsl:use-attribute-sets attribute on a literal result element. The value of the xsl:use-attribute-sets attribute is a white-space-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 one additional rule. The additional rule is 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 are added first, in the order listed in the attribute. Next, attributes specified on the literal result element are added. Finally, any attributes specified by xsl:attribute elements are 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. Consequently, only variables and parameters declared by top-level xsl:variable and xsl:param elements are visible.

The XSLT processor merges multiple definitions of an attribute set with the same expanded name. If there are two attribute sets with the same expanded name that both contain the same attribute, the XSLT processor chooses the attribute definition that was specified last in the stylesheet.

Example

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>

xsl:call-template

Instantiates a named template.

Format


<xsl:call-template name="template_name"> [<xsl:with-param/>] </xsl:apply-templates>

Description

The name attribute is required and the value must be a qualified name. It specifies the name of the template you want to instantiate. The template you want to instantiate must specify the name attribute with a value identical to template_name.

Unlike the xsl:apply-templates instruction, the xsl:call-template instruction does not change the current node.


Tip		You can create an `xsl:call-template` element automatically using the XSLT mapper.

xsl:choose

Selects one template to instantiate from a group of templates.

Format

<xsl:choose>
               

              
                <xsl:when test="expression1">
                   
template_body 
                   
</xsl:when>
                   
[<xsl:when test="expression2">
                   
template_body 
                   
</xsl:when>] ...
                   
[<xsl:otherwise>
                   
template_body  
                   
</xsl:otherwise>]
                   

                
              
</xsl:choose>

Description

An xsl:choose element contains one or more xsl:when elements followed by zero or one xsl:otherwise element. Each xsl:when element contains a required test attribute, whose value is an expression. Each xsl:when and xsl:otherwise element contains a template.

When the XSLT processor processes an xsl:choose element, it starts by evaluating the expression in the first xsl:when element. The XSLT processor converts the result to a Boolean value. If the result is true, the XSLT processor instantiates the template contained by that xsl:when element. If the result is false, the XSLT processor evaluates the expression in the next xsl:when element.

The XSLT processor instantiates the template of only the first xsl:when element whose test expression evaluates to true. If no expressions evaluate to true and there is an xsl:otherwise element, the XSLT processor instantiates the template in the xsl:otherwise element.

If no expressions in xsl:when elements are true and there is no xsl:otherwise element, the xsl:choose element has no effect.


Tip		You can create an `xsl:choose` element automatically using the XSLT mapper.

xsl:comment

Adds a comment node to the result tree.

Format


<xsl:comment> comment_text </xsl:comment>

Description

The XSLT processor instantiates the contents of the instruction to generate the text of the new comment.

The XSLT processor reports an error if instantiating the contents of the xsl:comment instruction creates anything other than characters, or if the resulting string contains the substring "--" or ends with "-".

Example

The following instruction creates a comment in the result document:


<xsl:comment>Unique Irish band</xsl:comment>

The comment is


<!--Unique Irish band-->

xsl:copy

Adds a copy of the current node to the result tree.

Format


<xsl:copy>copy_contents</xsl:copy>

Description

The copy includes the current node's namespace information but does not include the current node's attributes or children. The contents of the xsl:copy element is a template for the attributes and children of the node being created. If the current node cannot have attributes or children (that is, if it is an attribute, text, comment, or processing instruction node), the content of the instruction is ignored.

If the current node is the root node, the XSLT processor does not create a root node. Instead, it uses copy_contents as a template.

Example

Following is an example from the W3C XSLT Recommendation. It generates a copy of the source document.


<xsl:template match="@* \| node() "> <xsl:copy> <xsl:apply-templates select="@* \| node() " /> </xsl:copy> </xsl:template>

xsl:copy-of

Inserts the value of an expression into the result tree, without first converting it to a string.

Format


<xsl:copy-of select = "expression" />

Description

The required select attribute contains an expression. When the result of evaluating the expression is a result tree fragment, the XSLT processor copies the complete fragment into the result tree. When the result is a node set, the XSLT processor copies all nodes in the set, together with their contents, in document order into the result tree. When the result is of any other type, the XSLT processor converts the result to a string and then inserts the string into the result tree in the same way that xsl:value-of does.

xsl:decimal-format

Declares a decimal format.

Format

<xsl:decimal-format
               

              
                name = qname 
                   
decimal-separator = char 
                   
grouping-separator = char 
                   
infinity = string 
                   
minus-sign = char 
                   
NaN = string 
                   
percent = char 
                   
per-mille = char 
                   
zero-digit = char 
                   
digit = char 
                   
pattern-separator = char />

Description

The xsl:decimal-format instruction declares a decimal format, which controls the interpretation of a format pattern that is used by the format-number() function.

If there is a name attribute, the element declares a named decimal format. Otherwise, it declares the default decimal format. The value of the name attribute is a qualified name.

The other attributes on xsl:decimal-format correspond to the methods on the JDK DecimalFormatSymbols class. For each get/set method pair, there is an attribute defined for the xsl:decimal-format instruction.

The following attributes control the interpretation of characters in the format pattern and specify characters that can appear in the result of formatting the number:

decimal-separator specifies the character used for the decimal sign; the default value is the dot character (.).

grouping-separator specifies the character used as a grouping (for example, thousands) separator; the default value is the comma character (,).

percent specifies the character used as a percent sign; the default value is the percent character (%).

per-mille specifies the character used as a per mille sign; the default value is the Unicode per mille character (#x2030).

zero-digit specifies the character used as the digit zero; the default value is the digit zero (0).

The following attributes control the interpretation of characters in the format pattern:

digit specifies the character used for a digit in the format pattern; the default value is the number sign character (#).

pattern-separator specifies the character used to separate positive and negative subpatterns in a pattern; the default value is the semicolon character (;).

The following attributes specify characters or strings that can appear in the result of formatting the number:

infinity specifies the string used to represent infinity; the default value is the string "Infinity".

minus-sign specifies the character used as the default minus sign; the default value is the hyphen (minus) character (-, #x2D).

NaN specifies the string used to represent the NaN value; the default value is the string "NaN".

xsl:element

Adds an element to the result tree.

Format


`<xsl:element name="`qualified_name `">` element_contents </xsl:element>

Description

The XSLT processor uses the contents of the xsl:element instruction as a template for the attributes and contents of the new element.

The prefix part of the name attribute becomes the prefix for the element you are creating. The local part of the name attribute becomes the local name of the element you are creating.

Example


              <xsl:element name="audio:CD">
               

              
                <xsl:element name="audio:title">Celtic Airs</xsl:element>
                   
<xsl:element name="audio:artist">Chieftains</xsl:element>
                   

                
              
</xsl:element>

The result of this instruction looks like the following:


<audio:CD> <audio:title>Celtic Airs</audio:title> <audio:artist>Chieftains</audio:artist> </audio:CD>

xsl:fallback

Normally, instantiating an xsl:fallback element does nothing. However, when an XSLT processor performs fallback for an instruction element, if the instruction element has one or more xsl:fallback children, then the content of each of the xsl:fallback children must be instantiated in sequence; otherwise, an error is signaled. The content of an xsl:fallback element is a template.

xsl:for-each

Selects a set of nodes in the source document and instantiates the contained template once for each node in the set.

Format


`<xsl:for-each select="`pattern `">` [<xsl:sort[select="expression"][optional_attribute]/>] template_body </xsl:for-each>

Description

The select attribute is required and the pattern must evaluate to a node set. The XSLT processor instantiates the embedded template with the selected node as the current node and with a list of all selected nodes as the current node list.

The xsl:for-each instruction is useful when the result document has a regular, known structure. When you know that you want to instantiate the same template for each node in the current node list, the xsl:for-each instruction eliminates the need to find a template that matches each node.


Tip		You can create an `xsl:for-each` element automatically using the XSLT mapper.

Example

For example, suppose your source document includes the following XML:

<books>
               

              
                <author>
                   
<name>Sara Peretsky</name>
                   
<booktitle>Bitter Medicine</booktitle>
                   
<booktitle>Killing Orders</booktitle>
                   
</author>
                   
<author>
                   
<name>Dick Francis</name>
                   
<booktitle>Reflex</booktitle>
                   
<booktitle>Proof</booktitle>
                   
<booktitle>Nerve</booktitle>
                   
</author>
                   

                
              
</books>

The following stylesheet creates an HTML document that contains a list of authors. Each author is followed by the titles of the books the author wrote. It does not matter how many authors there are nor how many titles are associated with each author. The stylesheet uses the xsl:for-each instruction to process each author and to process each title associated with each author.

<xsl:stylesheet 
               

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

                
              
<xsl:template match = "/">
               

              
                <html>
                   
<head><title>Authors and Their Books</title></head>
                   
<body> 
                   
<xsl:for-each select = "books/author">
                   

                
              
<p>
               
<xsl:value-of select = "name"/>
               
<br>
               
<xsl:for-each select = "booktitle">
               
<xsl:value-of select = "."/>
               
<br>
               
</xsl:for-each>
               
</p>
               

              
                </xsl:for-each>
                   
</body>
                   
</html>
                   

                
              
</xsl:template>
               
</xsl:stylesheet>

The result document looks like this:

<html>
               
<head>
               
<title>Authors and Their Books</title>
               
</head>
               
<body>
               
<p>
               
Sara Peretsky<br>
               
Bitter Medicine<br>
               
Killing Orders<br>
               
</p>
               
<p>
               
Dick Francis<br>
               
Reflex<br>
               
Proof<br>
               
Nerve<br>
               
</p>
               
</body>
               
</html>

xsl:if

Conditionally instantiates the contained template body.

Format


<xsl:if test = "expression"> template_body </xsl:if>

Description

The XSLT processor evaluates the expression and converts the result to a Boolean value. If the result is true, the XSLT processor instantiates template_body. If the result is false, the xsl:if element has no effect.

Example

This following example formats a group of names as a comma-separated list:

<xsl:template match="namelist/name">
               

              
                <xsl:value-of select="." />
                   
<xsl:if test="not(position()=last())">, </xsl:if>
                   

                
              
</xsl:template>

If you want the XSLT processor to choose which template to instantiate from several possibilities, specify the xsl:choose instruction. See xsl:choose.

xsl:import

Imports a stylesheet into the stylesheet containing this instruction.

Format


<xsl:import href="stylesheet_path">

stylesheet_path specifies the stylesheet you want to import. Specify a URL, a relative path, or a DOS-style path.

Description

An XSLT stylesheet can import another XSLT stylesheet by using an xsl:import instruction. Importing a stylesheet is the same as including it, except that definitions and template rules in the importing stylesheet take precedence over template rules and definitions in the imported stylesheet.

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.

When you use the xsl:import instruction, templates have an importance property.

xsl:include

Specifies an XSLT stylesheet that is included in and combined with the stylesheet that specifies xsl:include.

Format


<xsl:include href="stylesheet_path">

stylesheet_path specifies the stylesheet you want to import. Specify a URL, a relative path, or a DOS-style path.

Description

The xsl:include instruction must be a child of an xsl:stylesheet element. The XSLT processor effectively replaces the xsl:include instruction with the children of the root xsl:stylesheet element of the included stylesheet. If the root element of the included stylesheet is a literal result element, the XSLT processor effectively replaces the xsl:include instruction with the following new element whose only child is that literal result element:


`<xsl:template match="/">`

A stylesheet cannot include itself directly or indirectly.

xsl:key

Declares a key for a document.

Format


<xsl:key name="qname" match = "pattern" use = "use" />

Description

Keys provide a way to work with documents that contain an implicit cross-reference structure. A stylesheet declares a key for a document with the xsl:key instruction.

The xsl:key instruction must be a top-level element. It has no contents, but it specifies three attributes.

Replace qname with the name of the key. You must specify a qualified name.

Replace pattern with a pattern that identifies one or more nodes that have this key. In other words, the nodes in the document that match the pattern are included in the key. The default is node().

Replace use with an expression that you want to use for the key values. The XSLT processor evaluates the expression once for each node in the set identified by pattern.

Each key name represents a separate, independent set of identifiers. Each node included in a key is associated with a set of string key values. These values result from evaluating the use expression with that node as the current node.

A document can contain multiple keys with the same node and the same key name, but with different key values. A document can contain multiple keys with the same key name and value, but with different nodes. In other words:

A node can be included in more than one key.

For a given key, a key value can be associated with more than one node.

The same key value can be associated with different nodes in different keys.

The value of a key can be an arbitrary string. It need not be a name.

Use the XSLT key() function to retrieve the list of nodes included in a given key that have given key values. See Finding an Element with a Particular Key.

Restriction

You cannot specify multiple declarations for the same key in a stylesheet. Stylus Studio expects to remove this restriction in a future release.

xsl:message

Sends a message in a way that is dependent on the XSLT processor.

Format


<xsl:message terminate="yes" \| "no"> <!-- Content: template --> </xsl:message>

Description

The content of the xsl:message instruction is a template. If the value of the terminate attribute is yes, the XSLT processor instantiates the template to create text. The processor aborts stylesheet processing and sends the text as part of the error message that indicates that stylesheet processing has terminated.

The default value of the terminate attribute is no. If you specify terminate="no" or if you do not specify the terminate attribute, the XSLT processor displays the message in the Stylus Studio Output Window but does not terminate the process.

xsl:namespace-alias

Causes the namespace URI to be changed in the output.

Format


<xsl:namespace-alias stylesheet-prefix = prefix \| "#default" result-prefix = prefix \| "#default" />

Description

Declares that one namespace URI is an alias for another namespace URI. When a literal namespace URI has been declared to be an alias for another namespace URI, then the namespace URI in the result tree is the namespace URI that the literal namespace URI is an alias for, instead of the literal namespace URI itself.

xsl:number

Inserts a formatted number into the result tree.

Format

<xsl:number 
               

              
                [level = "single" | "multiple" | "any"]
                   
[count = 
                  pattern]
                   
[from = 
                  pattern]
                   
[value = 
                  number-expression]
                   
[format = {
                  string}]
                   
[lang = {
                  nmtoken}]
                   
[letter-value = {"alphabetic" | "traditional"}]
                   
[grouping-separator = {
                  char}]
                   
[grouping-size = {
                  number}]/>

Description

You can use the value attribute to specify an expression for the number to be inserted. The XSLT processor evaluates the expression. The resulting object is converted to a number as if by a call to the number() function. The processor rounds the number to an integer and then uses the specified attributes to convert it to a string. The value of each attribute is interpreted as an attribute value template. After conversion, the resulting string is inserted in the result 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. The default is single.

The count attribute is a pattern that specifies what nodes should be counted at those levels.

The from attribute is a pattern that specifies where counting starts.

The value attribute can specify an expression that represents the number you want to insert. If no value attribute is specified, the XSLT processor inserts a number based on the position of the current node in the source tree.

The format attribute specifies the format for each number in the list. The default is 1.

The lang attribute specifies which language's alphabet is to be used.

The letter-value attribute distinguishes between the numbering sequences that use letters.

The grouping-separator attribute specifies the separator used as a grouping (for example, thousands) separator in decimal numbering sequences.

The grouping-size attribute specifies the size of the grouping. Normally, this is 3.

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>

xsl:otherwise

See xsl:choose.

xsl:output

Specifies the output for the result tree.

Format


<xsl:output attribute_list />

Description

The xsl:output instruction specifies how you want the result tree to be output. However, if you use the XSLT processor to format the result as a string, or to generate DOM nodes, the xsl:output instruction has no effect.

If you specify the xsl:output instruction, the XSLT processor outputs the result tree according to your specification. If you specify it, the xsl:output instruction must be a top-level element.

The attribute list can include the method attribute. The method attribute identifies the overall method you want the XSLT processor to use to output the result tree. The value must be xml, html, or text.

xml formats the result tree as XML.

html formats the result tree as HTML. The stylesheet applies special formatting rules for empty tags, binary attributes, and character escaping, among other things. The values of the attributes named href and src are URL encoded.

text concatenates the text nodes in the result tree. The concatenated string does not include any tags.

Note that the XSLT processor formats the results of applying the stylesheet. If your stylesheet generates XML or HTML that does not follow all syntax rules, the XSLT processor does not do anything to fix this. For example, if a stylesheet generates multiple root elements, the XSLT processor neither fixes this nor generates an error. You receive a string, and it is only upon examination or use of the string that you would learn that it is not well-formed XML.

If you do not specify an xsl:output instruction that includes the method attribute, the XSLT processor chooses a default as follows:

html is the default output method if the name of the first element child of the root node is html.

text is the default output method if the root node has no element child nodes.

xml is the default output method in all other cases.

The other attributes that you can specify in attribute_list provide parameters for the output method. You can specify the following attributes:

doctype-public specifies the public identifier to be used in the document type declaration.

doctype-system specifies the system identifier to be used in the document type declaration.

encoding specifies the preferred character encoding that the XSLT processor should use to encode sequences of characters as sequences of bytes.

indent specifies whether the XSLT processor can add additional white space when outputting the result tree. The value must be yes or no.

media-type specifies the media type (MIME content type) of the data that results from outputting the result tree. Do not explicitly specify the charset parameter. Instead, when the top-level media type is text, add a charset parameter according to the character encoding actually used by the output method.

omit-xml-declaration specifies whether the XSLT processor should omit or output an XML declaration. The value must be yes or no. If you do not specify this attribute, whether or not the output contains an XML declaration depends on the output method.

If the output method is html, the XSLT processor does not insert an XML declaration.

If the output method is xml, the XSLT processor inserts an XML declaration.

The XSLT processor ignores this attribute when the output method is text.

standalone specifies whether the XSLT processor should output a stand-alone document declaration. The value must be yes or no.

A stylesheet can include multiple xsl:output elements. The XSLT processor effectively merges multiple xsl:output elements into one xsl:output element. If there are multiple values for the same attribute, the XSLT processor uses the last specified value.

Ignored attributes

In this release, the XSLT processor ignores the following attributes:

cdata-section-elements specifies a list of the names of elements whose text node children should be output using CDATA sections.

version specifies the version of the output method.

xsl:param

Declares a parameter for a stylesheet or template, and specifies a default value for the parameter.

Format


<xsl:param name="parameter_name" [select = "expression1"] [expr = "expression2"]> [template_body] </xsl:param>

Description

The xsl:param instruction declares a parameter and specifies its default value. Another value can be passed to this parameter when the template or stylesheet that contains this xsl:param instruction is invoked.

The xsl:param element must be a child of either an xsl:stylesheet or xsl:template element.

The name attribute is required, and it must be a string. The value of the name attribute is a qualified name.

The value that you bind to a parameter can be an object of any of the types that are returned by expressions. You can specify the value of the parameter in several ways:

Specify the select attribute. The value of the select attribute must be an expression. The XSLT processor evaluates the expression, and the result is the default value of the parameter. If you specify the select attribute, the XSLT processor ignores any value you might specify for the expr attribute, and also ignores any contents of xsl:param.

Specify the expr attribute. The expr attribute allows computation of an expression. For example:


<xsl:param name="query" expr="//VEHICLE[MAKE='{$make}']"/>

The XSLT processor interprets the value of the expr attribute as an attribute value template and uses the resulting string as if it were the value of the select attribute. If you specify the expr attribute, the XSLT processor ignores any contents of xsl:param.

The use of the expr attribute is an extension to the XSLT specification.

Specify template_body. The XSLT processor instantiates this template to obtain the default value of the parameter.

If you do not specify the select attribute, the expr attribute, or template_body, the default value of the parameter is an empty string.

For any use of the xsl:param element, there is a region of the stylesheet tree within which the binding is visible. This region includes the siblings that follow the xsl:param instruction together with their descendants. Within this region, any binding of the parameter that was visible on the xsl:param element itself is hidden. Thus, only the innermost binding of a parameter is visible. The set of parameter bindings in scope for an expression consists of those bindings that are visible at the point in the stylesheet where the expression occurs.

The xsl:param instruction can be a top-level element. If it is, it declares a global parameter that is visible to the entire stylesheet. When the XSLT processor evaluates the select or expr attribute in a top-level xsl:param instruction, the current node is the root node of the document.

Passing parameters to templates

Use the xsl:with-param instruction to pass a value for a parameter to a template.

xsl:preserve-space

The xsl:preserve-space instruction is not supported by Stylus Studio. If this instruction is in a stylesheet, it is ignored.

xsl:processing-instruction

Adds a processing instruction node to the result tree.

Format


<xsl:processing-instruction name = "pi_name"> processing_instruction </xsl:processing-instruction>

Description

The XSLT processor interprets the name attribute as an attribute value template, and uses the resulting string as the target of the created processing instruction. The XSLT processor then instantiates the contents of xsl:processing-instruction to generate the remaining contents of the processing instruction.

Errors are reported under the following conditions:

If the string that results from evaluating the name attribute is not both an NCName and a PITarget (see the XSLT Recommendation). Also, the value of the name attribute cannot be xml.

If instantiation of the contents of the xsl:processing-instruction element creates anything other than characters or if the resulting string contains the substring "?>".

Example


<xsl:processing-instruction name = "xml-stylesheet"> `href="book.css" type="text/css"` </xsl:processing-instruction>

This instruction creates the following processing instruction in the result document:


<?xml-stylesheet href="book.css" type="text/css"?>

xsl:sort

Sorts the set of nodes selected by an xsl:apply-templates or xsl:for-each instruction.

Format


<xsl:sort [select="expression"] [optional_attribute]/>

Description

The xsl:sort instruction must be the child of an xsl:apply-templates or xsl:for-each instruction. Each xsl:apply-templates and xsl:for-each instruction can contain more than one xsl:sort instruction. The first xsl:sort child specifies the primary sort key. The second xsl:sort child, if any, specifies the secondary sort key, and so on.

When an xsl:apply-templates or xsl:for-each element contains an xsl:sort instruction, the selected nodes are processed in the order specified by the xsl:sort instructions. When xsl:sort elements are in an xsl:for-each element, they must appear first before all other child elements.

You can specify the sort key by using the select attribute, whose value is an expression. For each node selected by the xsl:apply-templates or xsl:for-each instruction, the XSLT processor evaluates the expression using the node as the context node. The resulting string is the sort key for that node. If you do not specify the select attribute, the XSLT processor uses the string value of the node as the sort key.

When all sort keys for two nodes are equal, nodes remain in document order.

The following optional attributes on xsl:sort determine how the XSLT processor sorts the list of sort keys. The XSLT processor interprets each of these attribute values as an attribute value template.

data-type specifies the data type of the strings. The following values are allowed:

text specifies that the sort keys should be sorted lexicographically. All text sorting is based on Unicode text values.

number specifies that the sort keys should be converted to numbers and then sorted according to the numeric value. Sort keys that are strings that do not match the syntax for numbers are sorted as zeros.

The default value is text.

order specifies whether the strings should be sorted in ascending or descending order. The default is ascending. If the value of the data-type attribute is text, ascending means that keys are sorted in alphabetical order, and descending means that keys are sorted in reverse alphabetical order. If the value of data-type is number, ascending means that keys are sorted in increasing order, and descending means that keys are ordered in descending order.

The XSLT processor can evaluate xsl:sort order at run time by using an attribute value template. For example:


<xsl:sort order="{$order)"

$order is a run-time specified attribute value template.

The XSLT processor ignores the lang and case-order attributes.

Example

The following example is from the W3C XSLT Recommendation. Suppose an employee database has the following form:


<employees> <employee> <name> <first>James</first> <last>Clark</last> </name> ... </employee> </employees>

The following stylesheet fragment sorts the list of employees by name:

<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>

xsl:strip-space

The xsl:strip-space instruction is not supported by Stylus Studio. If this instruction is in a stylesheet, it is ignored.

xsl:stylesheet

Specifies the start of a stylesheet.

Format

<xsl:stylesheet
               

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

                  version="1.0" >
                   
stylesheet_body
                   

                
              
</xsl:stylesheet>

Description

A stylesheet must specify the xsl:stylesheet element unless it contains only a literal result element as the root element. The xsl:transform instruction is a synonym for xsl:stylesheet.

All XSLT elements must appear between the <xsl:stylesheet> and </xsl:stylesheet> tags. An element that is a child of an xsl:stylesheet element is a top-level element.

xsl:template

Specifies a template rule.

Format

<xsl:template 
               

              
                [match = "pattern"]
                   
[name = "qname"] 
                   
[mode = "mode"] 
                   
[priority = "priority"]>
                   
template_body
                   

                
              
</xsl:template>

Description

The match attribute is required except when you specify the name attribute. The pattern you specify for the match attribute identifies the source node or set of source nodes to which the template rule applies.

The optional name attribute specifies a name for the template. You can use the name of a template to invoke it with the xsl:call-template instruction. The value you specify for name must be a qualified name. If you specify a name attribute, a match attribute is not required.

The optional mode attribute prevents the template from matching nodes selected by an xsl:apply-templates instruction that specifies a different mode. The value of mode must be a qualified name or an asterisk ( *). If you specify an asterisk, it means match any node.

If an xsl:apply-templates instruction contains a mode attribute, the xsl:apply-templates instruction can apply to only those xsl:template instructions that specify a mode attribute with the same value. If an xsl:apply-templates instruction does not contain a mode attribute, the xsl:apply-templates instruction can apply to only those xsl:template instructions that do not specify a mode attribute.

If you specify the match and mode attributes, they have no effect if the template is instantiated by the xsl:call-template instruction. If you specify the name attribute, you can still instantiate the template as a result of an xsl:apply-templates instruction.

If two or more templates have the same name, Stylus Studio uses the template that appears last in the stylesheet.

The template body contains literal results and XSLT instructions. The XSLT processor instantiates the template body for each node identified by pattern. This means the XSLT processor copies literal results to the result document and executes the XSLT instructions.

If there is more than one matching template rule, the XSLT processor chooses the matching template rule with the higher priority. If both have the same priority, the XSLT processor chooses the one that occurs last in the stylesheet.

For examples and additional information about templates, see Working with Templates.


Tip		You can create an `xsl:template` element automatically using the XSLT mapper.

xsl:text

Adds a text node to the result tree.

Format


<xsl:text [disable-output-escaping="yes\|no"]> text_node_contents </xsl:text>

Description

The XSLT processor reports an error if instantiating text_node_contents results in anything other than characters.

You can also add text nodes to result documents by embedding the text in elements that you define.

You can specify the disable-output-escaping attribute of the xsl:text instruction. The allowed values are yes or no. The default is no. If the value is yes, the text node generated by instantiating the xsl:text element is output without any escaping. For example:


<xsl:text disable-output-escaping="yes"><</xsl:text>

This instruction generates the single character <.

Examples

The following fragment adds two text nodes by embedding text.

<xsl:template match = "/">
               

              
                <html>
                   
<head><title>Authors and Their Books</title></head>
                   
<body>
                   
<intro>Books in stock are listed here.</intro> 
                   
...
                   
</body>
                   
</html>
                   

                
              
</xsl:template>

The next example specifies the xsl:text instruction:


<xsl:text>Following is a list of authors.</xsl:text>

xsl:transform

The xsl:transform instruction is a synonym for xsl:stylesheet .

xsl:value-of

Creates a new text node that contains the string value of an expression.

Format


<xsl:value-of select="expression" [disable-output-escaping="yes\|no"]/>

Description

The XSLT processor evaluates expression and converts the result to a string. If the string is not empty, a text node is created and added to the result. If the string is empty, the xsl:value-of instruction has no effect.

You can specify the disable-output-escaping attribute of the xsl:value-of instruction. The allowed values are yes and no. The default is no. If the value is yes, the text node generated by instantiating the xsl:value-of element is output without any escaping.


Tip		You can create an `xsl:value-of` element automatically using the XSLT mapper.

Example


              <xsl:template match = "author">
               

              
                <p>
                   
<xsl:value-of select = "first-name"/>
                   
<xsl:text> </xsl:text>
                   
<xsl:value-of select = "last-name"/>
                   
</p>
                   

                
              
</xsl:template>

This example creates an HTML paragraph from an author element. The author element has first-name and last-name children. The resulting paragraph contains the value of the first first-name child element of the current node, followed by a space, followed by the value of the first last-name child element of the current node.

xsl:variable

Declares a variable and binds a value to that variable.

Format


<xsl:variable name="variable_name" [select = "expression2"] [expr = "expression3"]> [template_body] </xsl:variable>

Description

The name attribute is required, and it must be a string. The value of the name attribute is a qualified name.

The value that you bind to a variable can be an object of any of the types that are returned by expressions. You can specify the value of the variable in several ways:

Specify the select attribute. The value of the select attribute must be an expression. The XSLT processor evaluates the expression, and the result is the value of the variable. If you specify the select attribute, you must not specify any contents for the xsl:variable instruction. In other words, do not specify template_body.

Specify the expr attribute. It is interpreted as an attribute value template. It allows computation of the value expression.

The expr attribute of the xsl:variable instruction is an extension of the XSLT standard. If you want to use an XSLT processor other than the Stylus Studio processor, you cannot specify the expr attribute in your stylesheet.

Specify template_body. The XSLT processor instantiates this template to obtain the value of the variable. If you specify template_body, you must not specify the select attribute.

Specify none of the above. In this case, the value of the variable is an empty string.

The difference between the xsl:param and xsl:variable instructions is that xsl:param defines a default value while xsl:variable defines a fixed value.

Scope

For any use of the xsl:variable element, there is a region of the stylesheet tree within which the binding is visible. This region includes the siblings that follow the xsl:variable instruction together with their descendants. Within this region, any binding of the variable that is visible on the xsl:variable 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.

The xsl:variable instruction can be a top-level element. If it is, it declares a global variable that is visible to the entire stylesheet. When the XSLT processor evaluates the select or expr attribute in a top-level xsl:variable instruction, the current node is the root node of the document. The xsl:variable instruction is also allowed anywhere in a template that an XSLT instruction is allowed.

xsl:when

See xsl:choose.

xsl:with-param

Passes a parameter value to a template.

Format

<xsl:with-param 
               

              
                name = "parameter_name" 
                   
[select = "expression1]"
                   
[expr = "expression2"]>
                   
[parameter_value]
                   

                
              
</xsl:with-param>

Description

The xsl:with-param instruction passes a parameter value to a template. If the template has no matching xsl:param declaration, the XSLT processor ignores the parameter. The value of parameter_name is a qualified name.

The name attribute is required, and it must be a string. The value of the name attribute is a qualified name.

The value that you pass to a template can be an object of any of the types that are returned by expressions. You can specify the value of the parameter in several ways:

Specify the select attribute. The value of the select attribute must be an expression. The XSLT processor evaluates the expression, and the result is the value of the parameter. If you specify the select attribute, you must not specify any contents for the xsl:with-param instruction. In other words, do not specify parameter_value.

Specify the expr attribute. It is interpreted as an attribute value template. It allows computation of the value expression.

Specify parameter_value. If you specify parameter_value, you must not specify the select or expr attribute.

Specify none of the above. In this case, the value of the parameter is an empty string.

The xsl:with-param element must be a child of xsl:apply-templates or xsl:call-template.

You can specify the xsl:with-param instruction in xsl:call-template and xsl:apply-template instructions.

Example

Suppose you specify the following parameter for a template:


<xsl:template name="Appendix"> <xsl:param name = "heading"> 1. </xsl-param> ... </xsl:template>

You can pass another value for this variable as follows:


<xsl:call-template name = "Appendix"> <xsl:with-param name = "heading"> A. </xsl:with-param> </xsl:call-template>

Standard XML declaration.

xsl:stylesheet is an XSLT instruction. It must be the root element in a stylesheet to be used with Stylus Studio.

xsl:template is an XSLT instruction. It contains literal data to be copied to the result document and XSLT instructions to be followed by the XSLT processor. The processor performs these steps for the source nodes identified by the match attribute value. In this template, the match attribute identifies the root node of the source document.

Namespace declaration for W3C XSLT namespace.

xsl:output is an XSLT instruction. In this stylesheet, it specifies that the result document will be in HTML format.

xsl:apply-templates is an XSLT instruction. For each node identified by this instruction's select attribute, the XSLT processor goes to another template in this stylesheet, and performs the actions defined in that template. When done, the processor returns here, and moves to the next line in this template. In this template, the select attribute identifies all book elements in the source document.

xsl:sort is an XSLT instruction. The XSLT processor processes the book nodes in alphabetical order by author.

This template matches book elements in the source document. That is, the template's match attribute identifies book elements. In this stylesheet, the XSLT processor performs the actions in this template three times, once for each book element in the source document.

xsl:value-of is an XSLT instruction. The XSLT processor extracts the contents of the source node specified in the select attribute and copies it into the result document.

< Previous | Next >

Download a 15 Day Free Trial Now >

See What's New in Stylus Studio® X16 XML >

Buy Stylus Studio Now >