lect34-xslt-intro
XSLT
value-of, for-each

Originally based on XML Visual Quickstart Guide by Kevin Howard Goldberg, and notes therefrom by Jack Davis (jcdavis@radford.edu).

ch02 - XSLT basics

The next step in learning to use XML is understanding how to format these documents. The details for formatting XML documents was originally in a specification called XSLT, which stands for eXtensible Style Language Transformations. Chapters 2-4 explain how to use XSL to transform XML documents. The end result might be another XML document, or an HTML document (most common). You can transform an XML document into practically any document type.

Transforming an XML document means taking in one XML tree and producing another — a function from XML trees to XML trees. For example, consider the input

<my_children>
	<child>
		<name>Logan</name>
		<gender>M</gender>
		<age>7</age>
	</child>
	<child>
		<name>Rebecca</name>
		<gender>F</gender>
		<age>3</age>
	</child>
	<child>
		<name>Lee</name>
		<gender>F</gender>
		<age>2</age>
	</child>
</my_children>

An XSLT program might take this and return a new XML tree:

<html>
  <body>
    <h3>Some Kids</h3>
    <ul>
      <li>Logan, who is 7</li>
      <li>Rebecca, who is 3</li>
      <li>Lee, who is 2</li>
    </ul>
  </body>
</html>

Rather than write such a function in Java or a general-purpose programming language, XSLT is a domain-specific language, specifically invented to make these tree-transformations easy to write. XSLT can be used to reorder the ouput according to user established criteria, display only portions of the document, and more.

Examples of data stored as XML:

xhtml web documents (duh)
iTunes library-backup: see ~/Music/iTunes/iTunes Music Library.xml. (If you modify that file ¹, it doesn't actually change the iTunes data unfortunately; the .xml is provided by iTunes for other programs to be able to read.)
.svg (“Scalable Vector Graphics”) files, which are supported by all major browsers. E.g. show-source this .svg file. Note that because the information is not a bitmap, but rather how-to-create-the-image, it has the potential to scale particularly well.
Microsoft Office documents — .docx files (etc.) are actually in zip format; if you unzip, you can see sub-folders, including the content as an xml file.
Example: (click to see some xml source)

Overview

The transformation process starts with two documents: the XML document (the input data, .xml) and the XSLT document (the program, .xsl).
Interestingly, a XSLT program is itself written in XML(!). Its commands are tags which start with “xsl:” — for example,
<xsl:for-each select="nodeSpec"> results... </xsl:for-each>
(We'll discuss how the xsl:for-each loop works below.)
Alas, if you just have your browser request foo.xml, the server doesn't auto-magically look for a corresponding foo.xsl (even though that'd be a mildly sensible convention). Instead, you must specify, in the xml file, a processing instruction telling the server that this xml file should be processed by a particular xsl template:
<?xml-stylesheet type="text/xsl" href="foo.xsl"?>
oneWonder.xml (show-source; note line 3)
oneWonder.xsl
Once the browser has constructed the XML data tree, it then transforms that XML tree using the XSLT instructions, yeilding a new tree. The transformation rules are called “templates”; they correspond to functions in a programming language — a function which is given an XML node as input, and returns a (new) XML node.

(Note: usually the output happens to be XHTML, but it can in theory be any XML.)

A particular transformation (“template”) looks at one node of the input tree [including its subtree], and produces a (sub)tree to include in the overall output. In the my_children example above, there might be one “helper” XSLT template which, given a child node, produces (say) some HTML li tags incorporating some of the info from the child. A different “main” template might take the root element, and return a ul tag, followed by the results of applying the above child→li template to each child node.

In our context, it's the browser which invokes the XSLT processor, and the result is html. (The XSLT is being run client-side.) However, that's not required — XSLT can produce any XML output, and the XSLT processing can be run stand-alone.
Each XSLT template has two parts:
- First, a label that identifies the nodes in the XML document to which the template applies;
- Second, instructions about the actual transformation. The instructions, or rules, will either output or further process the nodes in the source document. They can also contain literal elements that should be output as is. The XSLT transformation begins by processing the root template.
Every XSLT style sheet must have a root template; this is the template that applies to the source document's root node², /.

Building an XSL Style Sheet

Every XSLT style sheet itself an XML document, so it begins with a standard XML declaration. Next, the W3C namespace for style sheets is defined.

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

Of course, at the end of the file the stylesheet tag will be closed:
</xsl:stylesheet>
Create the root template
This is the template that defines the set of rules to apply to the root of the XML document.
<xsl:template match="/" >  </xsl:template>
Note:If you do not include a root template in the XSLT stylesheet, a root template built in to XSLT will be used (typically not what you want).
Recall how php programs intermingle HTML and php processing directives. Well, XSLT is similar: programs can intermingle XML tags with XSLT processing tags. Any tag that's not a xsl processing instruction is passed along as part of the result.
After running the XSLT program, we have newly-built XML tree; the very last step is to flatten that tree back to a string and print it as output. We can use the xsl:output instruction to choose what “to-string” function will be used for this. (What character encoding is used, any DOCTYPE declaration to precede the output with, etc.).

In 95% of all cases, our resulting XML tree is HTML, and so we'll include
<xsl:output method="html"/>
You can give further arguments to specify the character-encoding, etc..

Note that xsl:output only is specified once, at the top level of the XSLT stylesheet.

Example: Putting the above together, we'll make a trivial XSLT program which ignores its input entirely, always generating the same, constant output page:
constant.xml
constant.xsl
Extracting data from an input node:
Use the xsl:value-of command to extract data from the XML input. (It can do more than this, but we'll come back to it.) <xsl:value-of select="expression"/>
where the expression selects a particular node in the xml document
If the select expression matches more than one node in the XML, only the first node's value will be used
nameOneWonder.xsl
nameOneWonder.xml
Looping over Nodes
Use xsl:for-each to loop over several nodes:
<xsl:for-each select="expression"> body</xsl:for-each>
Example:
wonders-table.xsl
wonders-table.xml

The body of the loop is XSLT, where the implicit-root of any relative XPATHS is one of the things selected by the for-each.

Note how the syntax of xsl:for-each gathers the control-flow into attributes, and the activity-to-be-repeated is exactly the tag's body. This is reminiscent of how (say) Java's for loops are an improvement over while loops which cleanly pull the loop-control into one line instead of while, where the initialization and end-of-loop update are more co-mingled with other code.

A conditional construct is xsl:choose, which is like an if-else-if in other languages:

<p>
  This person is
    <xsl:choose>                     
       <xsl:when test="height > 200">
         extremely
       </xsl:when>                 
       <xsl:when test="height != 0">
         <xsl:value-of select="height"/> cm
       </xsl:when>                 
       <xsl:otherwise>            
          unknown
       </xsl:otherwise>         
    </xsl:choose>
  tall.
</p>

Example: The 'height' column:
choose.xml
choose.xsl
(These are also examples of using xsl:if (below), for the non-English name, if present.)

The one-armed if:
<xsl:if test="boolean expression">  </xsl:if>
For example, if we only want to include the name when the language attribute is “English”:
<xsl:if test="name[@language='English']"> It's called <xsl:value-of select='name'>. </xsl:if>
Rather unintuitively³, the xsl:if instruction does not have a complementary ~~xml:else~~ instruction! So in practice use xsl:if to explicitly tell readers “I'll do nothing otherwise”⁴, and you'll find xsl:choose will get used relatively often.
Example:
if.xml
if.xsl
Sorting Nodes
To sort nodes before processing:
- Directly after an xsl:for-each element, insert a xsl:sort tag (which has attributes, but is otherwise empty).
- <xsl:sort select="criteria" order="descending" data-type="text" />
- Example:
  sort.xsl
  sort.xml
observation: Placing the xsl:sort tag as the first-child inside the loop's body is definitely odd. It would be more natural to have a stand-alone sort tag which takes the XPATH of the nodes to sort, and returns a “list” of the sorted nodes. Or, the loop's control-flow should all be set via attributes. Alas, they didn't ask me when designing it. (There is actually a vague scoping reason for their design choice: there are XPATH issues since the xsl:for-each is working on the parent node, but the sort's select expression is relative to a child. In most langauges this is solved via sort being passed a function, and that function knows it will handle the individual-element type.)

To create attributes: (that is, using XSLT to insert attributes into the xml/html node being generated)

            <xsl:attribute name="att_name">
              <!-- Here, specify the value of the new attribute.
                   Of course, you can use any XML: literal, or and XSLT instructions.
                   This body gets spliced into the enclosing tag (!) -->
            </xsl:attribute>

Suppose we want each Wonder to be a link — that is instead of the plain text “Colossus of Rhodes” we want to generate “<a href="#Colossus%20of%20Rhodes">Colossus of Rhodes</a>”. However, we can't do this with the xsl directives above(!)⁵ — we can either use pre-determined html, or select expressions from a tree as text, but not select an expression which gets spliced in, mid-tag, as an attribute. That's where xsl:attribute comes to the rescue:

            <a>
               <xsl:attribute name="href"> 
                 #<xsl:value-of select="name" />  <!-- link-target -->
               </xsl:attribute> 
               <xsl:value-of select="name" /> <!-- link-text -->

evaluates to the desired node, <a href="#Colossus%20of%20Rhodes">Colossus of Rhodes</a>.
attributes.xml
attributes.xsl

(Like xsl:sort, this is another weird placement; we put the xsl:attribute inside the parent tag's body, but the xsl:attribute doesn't affect our parent's body — it affects the parent itself.)

Note: The xsl:attribute tag must be the first child within the tag you're trying to effect. If we swapped the xsl:value-of and xsl:attribute nodes within the a, nothing renders at all. (There is no deep conceptual reason for this restriction.)

In the above example, note that although the code happens to work, it is not actually valid: the value of the id attribute can't contain spaces. The solution is to call the XSLT function translate, changing every space to (say) a hyphen: <xsl:attribute name="href"><xsl:value-of select="translate(name,' ','-')"/> We'll discuss xslt-functions shortly.

An xslt short-cut: curly-braces
In XSLT, curly-brackets are interpreted as an xpath expression. This provides a quick-and-dirty way to avoid value-of statements:

This shortcut that works particularly well when generating attributes: rather than requiring xsl:attribute tags, you can simply write: This is an <a href=#{@name}>internal link</a>.

Defining templates for re-use, and calling(applying) them:

Note: We will not emphasize this feature, in this course. Even though abstracting-into-a-function is one of the most fundamental aspects of programming, it's a bit unwieldy (and non-intuitive, and therefore not-particularly-common) to do so in XSLT. (Besides, our interest in XSLT is more as a vehicle to introduce the domain-specific languages xpath and DTDs, rather than than the language XSLT itself.)

The root template is the first thing processed in an XSLT style sheet. XSLT allows you to create more templates than just the root template. This allows you to create different sets of processing rules to apply to different parts of the XML document.

One of the main benefits of using templates is the ability to reuse a template for other nodes in your document. In the same way that one can use functions in most programming languages, you would create a template, and simply apply that template whenever necessary. This eliminates the need to repeat the same processing instructions.

In our ongoing example: We have been putting the non-english name in parentheses and italics. Suppose we want to do that throughout, consistently, and make it easy to maintain any changes or tweaks to this decision. We can define a template to process non-English name nodes, and then apply it in different contexts. (E.g. if there are tags for “newspaper”, we could apply the same template for non-English names there.)

                <!-- Define the function -->
                <xsl:template match="name[@language!='English']">
                   (<em><xsl:value-of select="."/></em>)
                </xsl:template>

As mentioned above, we call that function using apply-templates:
demo-templates.xsl
demo-templates.xml

The system looks for and calls the template for "/" automatically; other templates are only invoked via apply-templates.

There is a default template that gets called, if one doesn't otherwise apply: For a text node, just return the text; for a tag node, recursively call apply-templates on all its children.

You can't provide other arguments to templates — just the xpath of the element to process. And you can't call templates on any ol' node — you must specify (when you create the template) what xpaths it applies to.

Note that even when ~~calling a function~~ applying a template (so that your xsl:apply-templates tag has no body), you still can have a xsl:sort tag inside:

    <xsl:apply-templates select="ancient_wonders/wonder">
      <xsl:sort select="height" order="descending" data-type="number" />
    </xsl:apply-templates>

One data file, many pages

Similar to how a web-page (data) can have a css-stylesheet directive (processing), XML data files have a xml-stylesheet tag, with what XSLT file processes them.

It's annoying, that the xml-stylesheet processing instruction should be in the same file as the raw XML data. What if you have one data file, and you want to use it to produce several different views/results? Alas, the usual solution is to fall back to a different technology: Have a php file which prints the xml-stylesheet line, and then require's the XML file:

// The file children.php:
<?xml-stylesheet type="text/xsl" href="children.xsl"?>
<?php
  require('children-data.xml');
?>

In fact, this might happen often enough that you choose to write a php util function — say, renderXMLWith([string] $xmlDataFile, [string] $xslTransformFile ) — which prints out these lines. (So the file being linked to (children.php) actually contains just two lines: requiring utils.php, and then a call to renderXMLWith).

¹Don't try editing the file w/o make a copy of the file and probably the .itl (real library file) as well. ↩

² Remember, one of the XML requirements is that there is exactly one top-level tag. ↩

³ The reason for the lack of xsl:else is because it's a bit unclear where the else tag should be placed — conceptually it belongs beside the if tag, but requiring side-by-side tags is unlike any other instruction. Putting the else inside the if makes more sense, but even then the condition attributes now seem placed oddly. A more appropriate version might have an if tag with exactly two children: “then” and “else”. … hey now we've arrived back at what xsl:choose does, except we're limited to exactly-two! I guess they designed the choice tag correctly after all! ↩

⁴ Perhaps they should use an English term beside “if”; perhaps when or unless? ↩

⁵ In php it's no problem to have an expression whose result was inserted into the middle of an attribute. However, since XSLT is itself written in XML, and XML of course doesn't allow opening a tag in the middle of an attribute, the syntax physically precludes putting xls:select (etc.) expressions in the middle of an attribute. ↩

home—lects—hws
D2L—breeze (snow day)

©2014, Ian Barland, Radford University
Last modified 2014.Nov.21 (Fri) Please mail any suggestions
(incl. typos, broken links)
to ibarlandradford.edu

lect34-xslt-intro XSLTvalue-of, for-each

ch02 - XSLT basics

Overview

Building an XSL Style Sheet

One data file, many pages

lect34-xslt-intro
XSLT
value-of, for-each