Home > Online Product Documentation > Table of Contents > Getting Started with XSLT
This section provides an introduction to using Extensible Stylesheet Language Transformations (XSLT). It discusses the following topics:
The Extensible Stylesheet Language (XSL) is the World Wide Web Consortium's (W3C) language for manipulating XML data. XSLT is the component of XSL that allows you to write a stylesheet that you can apply to XML documents. The result of applying a stylesheet is that the XSLT processor creates a new XML, HTML, or text document based on the source document. The XSLT processor follows the instructions in the stylesheet. The instructions can copy, omit, and reorganize data in the source document, as well as add new data.
XSL is an XML-based language. It was developed by the W3C XSL working group within the W3C Stylesheets Activity. The W3C activity group has organized its specification of XSL into three parts:
A stylesheet is an XML document that contains instructions for generating a new document based on information in the source document. This can involve adding, removing, or rearranging nodes, as well as presenting the nodes in a new way.
This following topics provide more information:
When you work with a stylesheet, three documents are involved:
For example, suppose you have the following XML document:
You can use a stylesheet to transform this XML document into an HTML document that appears as follows in a Web browser:
The Web page in Figure 189 is defined by the following HTML document:
The HTML document contains HTML markup that is not in the source document. In the HTML document, the data from the source document is not in the same order as it is in the XML source document. Also, this HTML document does not include some data that is in the XML source document. Specifically, the HTML document does not include information about the date of publication (the
published elements).
To create this HTML file, the stylesheet contains two templates that provide instructions for
Following is a stylesheet that does this.
Stylesheets are XML documents. They contain a combination of
Each XSLT element is an instruction to the XSLT processor. For information about all XSLT instructions, see XSLT Instructions Quick Reference.
The root element of a stylesheet must declare a namespace that associates a prefix with the URI for an XSLT processor. The URI in the namespace declaration in the previous example identifies the W3C standard XSLT processor. This declaration, shown again below, instructs the XSLT processor to recognize the XSLT elements and attributes by their
xsl prefix:
In this stylesheet, you must use the
xsl prefix for all XSLT instructions.
|
Note
|
|
The Stylus Studio XSLT processor requires the namespace URI to be
|
When you write a stylesheet, you specify the actions you want the XSLT processor to perform when it processes a particular source node. To do this, you define XSLT templates, which are described in the next section.
A template defines what the XSLT processor should do when it processes a particular node in the XML source document. The XSLT processor populates the result document by instantiating a sequence of templates. Instantiation of a template means that the XSLT processor
The following topics further describe what a template is:
The
stylesheet example in
Stylesheet used defines the following templates using the
xsl:template instruction:
In the
xsl:template tag, the value of the
match attribute is an XPath pattern. This pattern matches (identifies) a node or a set of nodes in the source XML document. The value of the
match attribute is the
template rule.
The template body defines actions you want the XSLT processor to perform each time it instantiates this template. It contains
When the XSLT processor applies a stylesheet to an XML document, it begins processing with the root node of the XML source document. To process the root node, the XSLT processor searches the stylesheet for a template rule that matches the root node. A template rule matches the root node when the value of the template's
match attribute is
"/".
If you explicitly defined a template rule that matches the root node, the XSLT processor finds it and instantiates its template. If the XSLT processor does not find an explicitly defined template rule that matches the root node, the processor instantiates the default template that matches the root node. Every stylesheet includes this default template.
|
Note
|
|
Whether or not you explicitly define a template rule that matches the root node, the XSLT processor always instantiates a template that matches the root node. |
In the sample stylesheet, the template rule in the first template matches the root node:
The XSLT processor instantiates this template to start generating the result document. It copies the first few lines from the template to the result document. Then the XSLT processor reaches the following XSLT instruction:
When the XSLT processor reaches the
select attribute, it creates a list of all source nodes that match the specified pattern. In this example, the list contains
book elements. The processor then processes each node in the list in turn by instantiating its matching template. First, the XSLT processor searches for a template that matches the first
book element. The template rule in the second template matches the
book element:
After instantiating this template for the first
book element, the XSLT processor searches for a template that matches the second
book element. The XSLT processor instantiates the
book template again, and then repeats the process for the third
book element. That is, the XSLT processor searches for a matching template, and instantiates that template when it is found.
After three instantiations of the
book template, the XSLT processor returns to the first template (the template that matches the root node) and continues with the line after the
xsl:apply-templates instruction.
Consider the following instructions:
The
xsl:apply-templates instruction uses the
select attribute to specify an XPath expression. The
xsl:template instruction uses the
match attribute to specify an XPath pattern.
When the XSLT processor reaches an expression that is the value of a
select attribute, it evaluates the expression relative to the current node. The result of the evaluation is that the XSLT processor selects a set of nodes to be processed.
When the XSLT processor reaches a pattern that is the value of a
match attribute, it evaluates the pattern alone. The result of the evaluation is that the XSLT processor determines whether or not the pattern matches the node already selected for processing.
For example, suppose you have the following instruction:
This instruction selects the
book elements for processing. For each
book element, the XSLT processor searches for a template that matches the
book element. The following template matches the
book element because the pattern identifies all elements that contain
author elements. Because
book elements contain
author elements, this template is a match:
This example shows that the expression that the XSLT processor uses to select nodes and the pattern it uses to match nodes are independent of each other.
When the XSLT processor applies a stylesheet, it starts by automatically selecting the root node for processing and then searching for a template that matches the root node. The XSLT processor then iterates through the process of instantiating templates, selecting nodes in the source document for processing, and matching patterns, until no more templates need to be instantiated.
This section uses the sample stylesheet on Stylesheet used to present this process in more detail in the following topics:
To apply a stylesheet, the XSLT processor searches for a template that matches the source document root. The XSLT processor then instantiates the matching template and begins to process it line by line.
The specific processing depends on the contents of the template that matches the root node. The parts of the template include
It is important to understand that the contents of the XML source document do not dictate the order of XSLT processing. The XSLT processor performs only those actions that you specify, and operates on only the source nodes that you select. For example:
This template matches the root node. Consequently, the XSLT processor begins processing by instantiating this template. This means it processes each part of the template in the order in which it appears.
In the preceding example, the XSLT processor first copies the first four lines in the template body directly into the result document. Then it executes the
xsl:apply-templates instruction. When execution of that instruction is complete, the XSLT processor continues processing this template with the last line in the template body. After that, processing of this template is complete, and processing of the stylesheet is also complete.
Aside from the root node, the XSLT processor operates on only those nodes in the source document that are selected as the result of executing an XSLT instruction. In a stylesheet, there are two XSLT instructions that select nodes in the source document for processing:
The value of the
select attribute is an XPath expression. To evaluate this expression, the XSLT processor uses the current source node as the initial context node. This is the node for which the instruction that contains the
select attribute is being executed. For example, if this instruction is in the template that matches the root node, the root node is the current source node.
In an
xsl:apply-templates or
xsl:for-each instruction, the XSLT processor uses the
select expression you specify plus the current source node to select a set of nodes. 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.
When the XSLT processor reaches an
xsl:apply-templates instruction, the XSLT processor processes each node in the list of selected nodes by searching for its matching template and, if a matching template is found, instantiating it. In other words, the XSLT processor instantiates a template for each node if a matching template is found. The matching template might not be the same template for all selected nodes. If the XSLT processor does not find a matching template, it continues to the next selected node.
In an
xsl:for-each instruction, the XSLT processor instantiates the embedded template body once for each node in the list of selected nodes.
Typically, the template that matches the root node includes an
xsl:apply-templates instruction. When the XSLT processor executes the
xsl:apply-templates instruction, it performs the following steps:
xsl:apply-templates
select attribute to create a list of the source nodes identified by the expression.
xsl:apply-templates instruction and continues processing that template at the next line.
It is important to note that in step 2, the matching template might itself contain one or more
xsl:apply-templates instructions. As part of the instantiation of the matching template, the XSLT processor searches for a template that matches the nodes identified by the new
xsl:apply-templates instruction. In this way, the XSLT processor can descend many levels to complete processing of the first selected node in the initial
xsl:apply-templates instruction. The
xsl:apply-templates instruction allows you to access any elements in the source document in any order.
The
sample template on
Instantiating the First Template contains the following
xsl:apply-templates instruction:
The
select attribute specifies
"/bookstore/book" as the expression. This selects the set of
book elements in the source document as the nodes you want to process. For each selected node, the XSLT processor performs the following steps:
"book".
book element, it instantiates it. The following template matches the
book elements selected by the
xsl:apply-templates instruction:
xsl:value-of instructions. These instructions insert the values for the matching book's
title,
author, and
price elements into the table.
The XSLT processor repeats this process for each
book node. In other words, it instantiates this template three times, once for each
book element in the source document.
It is important to note that the XSLT processor does not search for a matching template once and then instantiate that matching template for each selected element. Rather, the XSLT processor performs the search for a matching template for each node selected for processing. For each node selected for processing, the XSLT processor
Another way to control the order of operation is to specify the
xsl:if,
xsl:choose, and
xsl:when instructions. See
XSLT Instructions Quick Reference.
The XSLT processor operates on only those nodes that you specify. If a node in your XML source document is never referenced in a stylesheet, the XSLT processor never does anything with it.
For example, the sample source XML document on Source XML document includes more than the title, author, and price for each book. It also includes the year of publication:
However, the template that matches the
book element does not specify any processing for the
published element. Consequently, the
published elements do not appear in the result document.
Sometimes, more than one template matches the node selected by an
xsl:apply-templates instruction. In this situation, the XSLT processor chooses the best match. Which match is the best match depends on the template's priority, mode, and order in the stylesheet. Priority, mode, and order are template properties that you can set.
mode="xyz
", for example) in both the
xsl:template and
xsl:apply-template instructions. Once you have specified a mode, the processor applies a template only if the modes match.
For information on specifying these attributes, see xsl:template and xsl:apply-templates.
When the XSLT processor cannot find a template that matches a selected node, it uses built-in templates. Every stylesheet includes built-in templates whether or not you explicitly define them.
The XSLT processor supports these built-in templates:
Although Stylus Studio does not explicitly insert these templates in stylesheets you create with Stylus Studio, they are always present. That is, as specified by the W3C XSLT Recommendation, these templates are always defined, whether or not they are explicitly defined. See Using Stylus Studio Default Templates.
This section highlights some of the XSLT instructions you can specify in a stylesheet to control the contents of the result document. This section discusses the following topics:
In a stylesheet, you can specify that the XSLT processor should format the result as XML, HTML, or text. Table 29 describes the XSLT processor output for each alternative:
See xsl:output for information about specifying formatting in a stylesheet.
The simplest way to create new nodes in a result document is to specify them as literal result elements or literal result text in a stylesheet template. For example:
This template creates many nodes in the result document that were not in the source document.
You can also use XSLT instructions to create new nodes. Typically, you use XSLT instructions when you need to compute the name or value of the node. You can find information about using the following instructions in the XSLT Instructions Quick Reference:
You can use the xsl:value-of instruction to provide the contents for a new node. You can also create a new node by copying the current node from the source document to the result document. The current node is the node for which the XSLT processor instantiates a template. See xsl:copy.
For readability, XML documents (both source documents and stylesheets) often include extra white space. White space in XML documents includes spaces, tabs, and new-line characters. Because this white space is for readability, it receives special treatment.
Text nodes that contain only white space are
Stylus Studio recommends that you specify
xsl:text in a stylesheet whenever you want to create significant white space in the result. Significant white space is white space that you want to appear in the result in exactly the way that you specify.
To obtain white space for readability during output formatting, specify the
xsl:output instruction with the
indent attribute. Default values are
yes for HTML, and
no for XML. With Stylus Studio, you can select the
Indent check box on the
Params/Other tab to display indented output instead of one long string. Note that the value of the
indent attribute, if specified in the stylesheet, has precedence over the
Indent option.
In a stylesheet's
xsl:template,
xsl:apply-templates,
xsl:for-each, and
xsl:value-of instructions, you specify patterns or expressions as the values for the
match or
select attributes. These patterns are XPath expressions. You specify patterns or expressions to
Depending on the context, an XSLT pattern or expression can mean one of the following:
Patterns or expressions can match or select any type of node. The XSLT processor can match a pattern to a node based on the existence of the node, the name of the node, or the value of the node. You can combine patterns and expressions with Boolean operators. For detailed information about patterns and expressions, see Chapter 9Writing XPath Expressions.
Following are examples of patterns and expressions you can specify in stylesheet instructions:
Matches any
price element that is a child of a
book element.
Matches any
award element that is a descendant of a
book element.
Matches any
book element that has a child that is a
price element.
Matches any
book element that has a
price attribute.
Matches any
book element that has a child that is a
price element whose value is
14.
Matches any
book element that has a
price attribute whose value is
14.
Selects all
book elements that are children of the current element.
Selects all
price elements that are children of
book elements that are children of the current element.
Selects all
book elements in the source document.
Selects all
book elements that are descendants of the current element.
How can I use quoted strings inside an attribute value?
If you need to include a quoted string inside an attribute value (in a
select expression, for example), you can use the single quotation mark character (') in the value of the attribute. For example:
How do I choose when to use xsl:for-each and when to use xsl:apply-templates?
The way
xsl:for-each and
xsl:apply-templates select nodes for processing is identical. The way these instructions find the templates to process the selected nodes is different.
With
xsl:for-each, the template to use is fixed. It is the template that is contained in the body of the
xsl:for-each element. With
xsl:apply-templates, the XSLT processor finds the template to be used for each selected node by matching that node against the template rules in the stylesheet.
Finding a template by matching requires more time than using the contained template. However, matching allows for more flexibility. Also, matching lets you avoid repeating templates that might be used in more than one place in a stylesheet.
Named templates are another option for invoking a template from more than one place in a stylesheet, when you know which template you want. It is a common mistake to use (and bear the overhead of) matching when it is not needed. But it allows you to do powerful things. Matching can take into account the following:
Most complex document-formatting stylesheets use
xsl:apply-templates extensively.
|
TIp
|
|
Use the XSLT Profiler to help you understand where the processor is spending most of its time. See Profiling XSLT Stylesheets. |
How can I insert JavaScript in my result document?
If you want your result document to contain JavaScript commands, you must properly escape the JavaScript code. Use the following format in your XSLT template:
However, this method does not work when your JavaScript section contains a block of XSLT code. In this case, enclosing the JavaScript in a
CDATA tag causes the XSLT processor to ignore not just the JavaScript but also the markup code within that tag.
In this situation, enclose the entity reference within an
<xsl:text> tag with
disable-output-escaping set to
"yes". For example:
You can use this wherever an entity reference needs to be handled specifically, as opposed to being handled as part of an entire JavaScript section.
My browser does not understand the tag <br/>. How can I output just <br>?
Although your XSLT stylesheet must contain valid XML (meaning all tags must be either empty or have a closing element), you can instruct the XSLT processor to generate output compliant with HTML. See Deleting Templates.
Alternative: To ensure that your stylesheet always generates correct HTML, specify the
xsl:output instruction with the
method attribute set to
html. See
xsl:output.
For additional information about XSL and XSLT, visit the following Web sites:
Now that you have an understanding of what a stylesheet can do, you can appreciate the benefits of using Stylus Studio to create stylesheets. Stylus Studio is the first integrated environment for creating, managing, and maintaining an XSL-enabled Web presence. By combining the tools needed to create XSLT stylesheets in a visual editing environment, Stylus Studio speeds initial development and eases maintenance. Key features of Stylus Studio include
Stylus Studio graphically displays the structure, or schema, of the XML data to which you want to apply a stylesheet.
Using this tree view, you can apply formatting to your XML - double-clicking a node in the tree automatically adds an
xsl:template match= instruction for that node, for example. Similarly, when you drag a node into the XSLT source, Stylus Studio displays a pop-up menu that allows you to easily insert an XSLT instruction.
Finally, you can also use the tree to move quickly among different XSLT templates - clicking a node in the tree places the cursor at the corresponding template in the XSLT source.
The Stylus Studio editor allows you to edit both the XML source document and the XSLT stylesheet. There is no need to memorize complicated syntax. As you type, Stylus Studio Sense:X technology automatically suggests XSLT or HTML tag and attribute names, and ensures that all XML is well formed.
Sense:X also adapts to your document by suggesting more frequently used tags first. Valid XSLT and HTML tag names are color coded to improve readability.
Complex stylesheets require robust debugging features. With Stylus Studio, you can do the following:
Also, you can click in the stylesheet and the backmapping feature highlights the text generated by that template.
Stylus Studio integrates an XML parser with an XSLT processor. This allows Stylus Studio to instantly show the output of your stylesheet. Each time you apply a stylesheet to an XML document, Stylus Studio detects and flags any errors in your stylesheet or XML data.
Stylus Studio's default XSLT processor is compliant with the W3C XSLT Recommendation. You can also use the Xalan-J processor, or custom processors of your own.