	XSLT Manual

1	Basics
	1.1	Calling XSL stylesheets
	1.2	Nodes
	1.3	Basic structure
	1.4	Template structures
2	Display XML content
	2.1	value-of
	2.2	HTML attributes
3	Operators
	3.1	Booleans
	3.2	Numbers
4	XPath functions
	4.1	last()
	4.2	position()
	4.3	count(node)
	4.4	id()
	4.5	local-name()
	4.6	namespace-uri()
	4.7	name()
	4.8	string()
	4.9	concat()
	4.10	starts-with()
	4.11	contains()
	4.12	substring-before()
	4.13	substring-after()
	4.14	substring()
	4.15	string-length()
	4.16	normalize-space()
	4.17	translate()
	4.18	boolean()
	4.19	not()
	4.20	true()
	4.21	false()
	4.22	lang()
	4.23	number()
	4.24	sum()
	4.25	floor()
	4.26	ceiling()
	4.27	round()
5	XSLT funtions
	5.1	document()
	5.2	key()
	5.3	format-number()
	5.4	current()
	5.5	unparsed-entity-uri()
	5.6	generate-id()
	5.7	system-property()
	5.8	element-available()
	5.9	function-available()
6	Control structures
	6.1	if
	6.2	for-each
	6.3	choose-when
7	Variables
	7.1	variable
	7.2	param
	7.3	with-param
8	Examples
	8.1	Datasets
9	Study XML

1 - Basics

This chapter describes the basis things about XSL stylesheets.

1.1 - Calling XSL stylesheets

Style sheets must be called from XML documents with the <?xml-stylesheet?> tag. This tag contains the attributes type and href. Since XSL documents are text documents, the attribute must contain text/xsl. The attribute href points to the location of the XSL document.

Example:

<?xml-stylesheet type="text/xsl" href="www.foo.org/stylesheet.xsl"?>

1.2 - Nodes

1.3 - Basic structure

A XSL stylesheet is a special XML document. It contains tags just like HTML. This is a basic XSL stylesheet which only displays the text 'This displays the root'.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:template match="/">
                This displays the root.
        </xsl:template>
</xsl:stylesheet>

This first set of tags define this document as a XSL stylesheet.
The 'template' tag selects a match with the XML document. In this case it matches the root '/' element. if a match is found, the code within the template tag is executed (displaying of the text).

The above example will always display the text once, since there can only be one root element.
Since the root is the most toplevel tag, all other tags must be defined within this template.

The next example will make things more clear:

<xsl:template match="cd">
        This is a cd.
</xsl:template>

When we execute this XSL code, the following output will be generated:

This is a cd.
This is a cd.
This is a cd.
This is a cd.
American Pie 2Jason BiggsShannon ElizabethNatasha LyonneAlyson HanniganJ.B. Rogers21...

Notice that for every <cd> tag, the text 'This is a cd.' will be displayed. But for all the <movie> tags all texts are displayed, even it's child tags.
XSL will see only a template match for cd and executes the template for every cd tag. But XSL will not find any movie tags, so it displays the complete tag tree for the movie tag.

1.4 - Template structures

Displaying just one template makes no sense. So we can use several templates, one for every tag if we wish.
To tell XSL to continue with searching for templates, a apply-templates tag can be used.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:template match="/">
                This is the root.<br/>
                <xsl:apply-templates/>
        </xsl:template>

        <xsl:template match="cd">
                This is a cd.<br/>
        </xsl:template>

        <xsl:template match="movie">
                This is a movie.<br/>
        </xsl:template>
</xsl:stylesheet>

This will output:

This is the root.
This is a cd.
This is a cd.
This is a cd.
This is a cd.
This is a movie.
This is a movie.
This is a movie.

First the root template will be executed. The all other templates are executed. for the cd tag, the cd template will be executed. The movie template is executed on every movie tag.

2 - Display XML content

The purpose for XSL stylesheets is to display the XML information in a more readable and customized way.

2.1 - value-of

The <xsl:value-of> tag displays a XML tag or attribute.

<xsl:value-of select="title"/>

All titles are displayed with the above command.
It is also possible to display a attribute like the prise discount attribute.

<xsl:value-of select="./@discount"/>

The dot sets the tag level on the current level. The '@' sign means we specify an attribute and not a tag. if the tag has not the correct attribute, nothing is displayed.

2.2 - HTML attributes

Sometimes we want to add a XML element to a HTML attibute. E.g. the href attribute in a link.
for example, we want to create a link to an artist page. (<a href="www.foo.com/artists/jewel">Jewel</a>)

<a>
        <xsl:attribute name="href">
                www.foo.com/artists/<xsl:value-of select="artist"/>
        </xsl:attribute>

        <xsl:value-of select="artists"/>
</a>

The xsl:attribute tag defines an attribute for the <a> HTML tag. The attribute is named 'href' and the value for this attribute (href) will be the contents between the xsl:attribute tag.
It is not possible to do a value-of within a quoted HTML tag, so '<a href="<xsl:value-of...' will not work.

3 - Operators

The XPath operators can be used within the test attribute in the control structures like if and choose. Or they can be used to control the output.

3.1 - Booleans

Boolean operators are mostly used in if and choose structures. A boolean checks if the expression is valid and returns true or false.

Boolean	Description
=	True if left and right expressions are equal
!=	True if left and right expressions are not equal
<	True if left expression is less than right expression
<=	True if left expression is less than or equal to right expression
>	True if left expression is greater than right expression
>=	True if left expression is greater than or equal to right expression
and	Logical and, both expressions must be true
or	Logical or, one or both expression must be true

Since most XSL parsers can not handle the greater and less than symbols, the HTML code for these symbols must be used. Use < for < and > for >. The sample below uses the less than function:

<xsl:template match="cd">
        <xsl:if test="price &lt; 15">
                <xsl:value-of select="title"/> is costs less than $15.<br/>
        </xsl:if>
</xsl:template>

This will result in:

International Superhits! is costs less than $15.
This Way is costs less than $15.

3.2 - Numbers

Number operators are use to calculate numbers. This can be used in varies functions like xsl:value-of or within boolean expressions.

Operator	Description
+	Calculates the sum of both numbers
-	The difference between both numbers
*	Multiply both numbers
div	The left number divided by the right
mod	The remainder of the division

Look at the following example:

<xsl:template match="/">
        <xsl:value-of select="30 div 4"/><br/>
        <xsl:value-of select="30 mod 4"/>
</xsl:template>

The result will be:

7.5
2

The result of 30 mod 4 is 2. This is explained by 4 * 7 = 28 + 2 = 30.

4 - XPath functions

4.1 - last()

Returns the number of the last node in the same level with the same parent.

<xsl:template match="cd/title">
        <xsl:value-of select="last()"/>
</xsl:template>

The above example will return 5, since there are 5 title elements with cd as parent.

4.2 - position()

Returns the number of the current element in the same tree level.

<xsl:template match="cd">
        <xsl:value-of select="position()"/>.<xsl:value-of select="title"/><br/>
</xsl:template>

This is the same function that I use for the index and the chapter numbering.

4.3 - count(node)

Returns the number of child elements of the current node.

<xsl:template match="movie">
        <xsl:value-of select="title"/> Has <xsl:value-of select="count(actor)"/> actors.<br/>
</xsl:template>

This will return:

American Pie 2 Has 2 actors.
The Sixth Day Has 3 actors.
Predator Has 3 actors.

A child node must be provided in the function.

4.4 - id()

Future.

4.5 - local-name()

Future.

4.6 - namespace-uri()

Future.

4.7 - name()

Returns the name of the selected node, if no node is specified the current node is returned.

<xsl:template match="cd">
        <xsl:value-of select="name()"/><br/>
</xsl:template>

This example will return 4 times cd.

4.8 - string()

Future.

4.9 - concat()

Future.

4.10 - starts-with()

Returns true if string 1 starts with string 2, this function is case sensitive.

<xsl:template match="cd">
        <xsl:if test="starts-with(title, 'Th')">
                <xsl:value-of select="title"/> is true.<br/>
        </xsl:if>
</xsl:template>

Only the title 'This way' starts with 'Th' so only this one will be displayed.

4.11 - contains()

return true if string 1 contains string 2. Also this function is case sensitive.

<xsl:template match="cd">
        <xsl:if test="contains(title, 'er')">
                <xsl:value-of select="title"/> is true.<br/>
        </xsl:if>
</xsl:template>

The result will be:

International Superhits! is true.
Silver Side Up is true.

Both keys contain 'er', the other key don't.

4.12 - substring-before()

Returns everything before string 2, this can be one or more characters. And this function is again case sensitive.

<xsl:template match="cd">
        <xsl:value-of select="substring-before(title,'Side')"/><br/>
</xsl:template>

Will return 'Silver'.
The text between the title tags is 'Silver Side Up'.

4.13 - substring-after()

Returns everything after string 2. String 2 can be one or more characters, and is case sensitive.

<xsl:template match="cd">
        <xsl:value-of select="substring-after(title,'Side')"/><br/>
</xsl:template>

Example returns 'Up'.
The text between the title tags is 'Silver Side Up'.

4.14 - substring()

Returns a part of the string. Syntax is substring(string, startpos, length). if no length is given, it will return the complete string from startpos.

<xsl:template match="cd">
        <xsl:value-of select="substring(title,4,7)"/><br/>
</xsl:template>

This will result in:

ernatio
a Nelly
ver Sid
s Way

The start position and the length must be numbers.

4.15 - string-length()

This function returns the length of an string.

<xsl:template match="cd">
        <xsl:value-of select="string-length(title)"/><br/>
</xsl:template>

Returns the length of the cd titles.

4.16 - normalize-space()

Removes all spaces at the beginning and end of the string. Also all blocks of spaces will be reduced to a single space.

<xsl:template match="/">
        <xsl:value-of select="normalize-space(' a   lot  of stupid     spaces    ')"/><br/>
</xsl:template>

Will return 'a lot of stupid spaces'.

4.17 - translate()

This function translates the given characters within a string. All characters are processed individualy, not the whole word.

<xsl:template match="cd">
        <xsl:value-of select="translate('A Space Odissei', 'isa', 'yt')"/>
</xsl:template>

This will output:

A Spce Odyttey

The 'i' characters are replace for a 'y' character. The 's' character change to a 't', but not the 'S' (capital) character. The 'a' characters are replaced by nothing, this may not give the same result on different parsers, sometime the 'a' character will be ignored.

4.18 - boolean()

Future.

4.19 - not()

The not function will convert the boolean result to it's opponent. So true becomes false and false becomes true.

<xsl:template match="cd">
        <xsl:if test="not(stock=0)">
                CD <xsl:value-of select="title"/> is on stock.<br/>
        </xsl:if>
</xsl:template>

First the XSLT will look for every cd with the element stock is 0. It will then inverse the outcome. Only the titles where the stock is not 0 will be displayed.

CD International Superhits! is on stock.
CD Whoa Nelly! is on stock.
CD Silver Side Up is on stock.

4.20 - true()

Future.

4.21 - false()

Future.

4.22 - lang()

The lang function checks the nodes language setting with the given language. if both languages are the same, it will return true.

<xsl:template match="cd">
        <xsl:if test="lang('en')">
                ...
        </xsl:if>
</xsl:template>

Can be used for multilanguage XML documents.

4.23 - number()

Convert the parameter to a number.

<xsl:template match="cd">
        <xsl:value-of select="number('-23.42')"/>
</xsl:template>

Will return '-23.42'. No localisation is performed.

4.24 - sum()

Returns the sum of all specified nodes in the set.

<xsl:template match="catalog">
        <xsl:value-of select="sum(cd/stock)"/>
</xsl:template>

This example will calculate the sum of all stock tags, wich gives us the current stock. In the example XML it will return '41'.

4.25 - floor()

The floor function will round a number to the smallest whole integer.

<xsl:template match="/">
        <xsl:value-of select="floor('2.43')"/><br/>
        <xsl:value-of select="floor('-2.43')"/>
</xsl:template>

The first function will return '2'.
The second function will return '-3'.

4.26 - ceiling()

The ceiling function will round a number to the largest whole integer.

<xsl:template match="/">
        <xsl:value-of select="ceiling('2.43')"/><br/>
        <xsl:value-of select="ceiling('-2.43')"/>
</xsl:template>

The fist function will return '3'.
The second function will return '-2'.

4.27 - round()

The round function will round a number to the closest whole integer.

<xsl:template match="/">
        <xsl:value-of select="round('2.43')"/><br/>
        <xsl:value-of select="round('-2.43')"/>
</xsl:template>

The fist function will return '2'.
The second function will return '-2'.

5 - XSLT funtions

5.1 - document()

Includes an external XSL stylesheet. The first parameter is the object that must be included (the XSL stylesheet). The second parameter is the node that becomes the root node for the external stylesheet.

I have not tested this function yet.

5.2 - key()

Future.

5.3 - format-number()

Formats a number value to a formated and localized number representation.

<xsl:template match="/">
        <xsl:value-of select="format-number('-2.43','000.0')"/>
</xsl:template>

This will output the number '-002.4'.

Future: include list of number attributes.

5.4 - current()

Will return the current node.

<xsl:template match="cd">
        <xsl:value-of select="current()"/><br/>
</xsl:template>

This will return the complete cd node (and all it's childs).

5.5 - unparsed-entity-uri()

5.6 - generate-id()

5.7 - system-property()

5.8 - element-available()

5.9 - function-available()

6 - Control structures

XSL is a sort of a program language, this means we can use structures to controll the program flow, make decisions based on input.

6.1 - if

The xsl:if function is used to test if a condition is true, if so execute the code within the tag. if not, continue after the tag.

<xsl:template match="cd">
        <xsl:if test="stock=0">
                CD <xsl:value-of select="title"/> is not on stock.
        </xsl:if>
</xsl:template>

This will output:

CD This Way is not on stock.

Every time the XSL parser passes a <cd> tag it will read it's <stock> tag. if this tag contains a '0', it will parse the code between the xsl:if tags.
To test if a attribute contains a certain value, use:

<xsl:if test="./@attribute='text'">

Only the equal compare '=' condition can be used with the xsl:if tag.

6.2 - for-each

The for-each structure will select every specified XML tag and executes the code for this.

<xsl:template match="cd">
        <xsl:for-each select="title">
                CD Title found.<br/>
        </xsl:for-each>
</xsl:template>

for every title tag, the text will be displayed (4 times in out example).

6.3 - choose-when

The choose function can be compared with a case or select function in other languages. The structure is explained below:

<xsl:template match="cd">
        <xsl:choose>
                <xsl:when test="stock=0">
                        CD is not on stock.<br/>
                </xsl:when>
                <xsl:otherwise>
                        CD is on stock.<br/>
                </xsl:otherwise>
        </xsl:choose>
</xsl:template>

The xsl:choose tag is the main structure, it must contain at least one xsl:when tag. The xsl:otherwise is optional. There may be more then one xsl:when tags, but only one xsl:otherwise.
The XSL parser checks if the <stock> tag contains '0', if so it displays the not on stock text. When the tag doesn't contain '0', it continous with the next statement. In this case the next statement is xsl:otherwise, so if all previous statements were not true, it displays the on stock text.

7 - Variables

XSLT has 2 types of variable objects, xsl:variable and xsl:param. The difference between the variable and the param is that the param may contain a default value for an existing XSL parameter (attribute). if the parameter is filled, the XML content is used. if the parameter does not exist, the XSL param value is used.

Variables and Params can be filled in 3 ways:

Variable binding is empty

<xsl:variable name="var"/>

This is the equivalent to:

<xsl:variable name="var" select="''"/>

Variable binding is filled with an expression.
```
<xsl:variable name="var" select="expression"/>
```
This is the most used type. And is the same as a variable used in other languages like Java or Basic.
Variable binding contains content.
```
<xsl:variable name="var">Content%lt;/xsl:variable>
```
The content may be a XSL template, the result of this template will be the content of the variable. The content may also be a tree fragment.

It is not possible to combine the last 2 types. A variable with a select attribute can not contain a content.

7.4 - variable

A variable is used to store information temporary.

<xsl:template match="/">
        <xsl:variable name="var" select="'1234'"/>
        
        The value of the variable is: <xsl:value-of select="$var"/><br/>
</xsl:template>

This will output:

The value of the variable is: 1234

The variable is only valid within the same template. It is not possible to pass variable to other templates. So the following sample will generate an error when it is processed:

<xsl:template match="/">
        <xsl:variable name="var" select="'1234'"/>
        
        The value of the variable is: <xsl:value-of select="$var"/><br/>
        
        <xsl:apply-templates/>
        
</xsl:template>

<xsl:template match="catalog">
	In the catalog template, the variable is: <xsl:value-of select="$var"/>
</xsl:template>

Microsoft Internet Explorer 6.0 will return the following error:

A reference to variable or parameter 'var' cannot be resolved. The variable or parameter may not be defined, or it may not be in scope.

7.5 - param

The param can be overwritten by an XSL attribute.

<xsl:template match="/">
        <xsl:param name="var" select="'1234'"/>
        
        The value of the param is: <xsl:value-of select="$var"/><br/>
</xsl:template>

This will output:

The value of the param is: 1234

Params are only valid within the same template, however it is possible to pass a param to an other template. See the with-param chapter for a description.

7.6 - with-param

The xsl:with-param function is used to pass param's to other templates. The xsl:with-param function defines the param and it's value to pass to other templates. The xsl:param defines the param in the template, the value is passed from the xsl:with-param function.

<xsl:template match="/">
        <xsl:apply-templates>
        	<xsl:with-param name="var" select="1234"/>
        </xsl:apply-templates>
</xsl:template>

<xsl:template match="catalog">
	<xsl:param name="var"/>
	In the catalog template, the param is: <xsl:value-of select="$var"/>
</xsl:template>

First the root template (/) is processed which includes the param value. From here the catalog template is processed, with the param from the root template. This will resul in:

In the catalog template, the param is: 1234

8 - Examples

This chapter describes some real life examples.

8.1 - Datasets

Rows of data retrieved from a source (like a database) are often displayed on a webpage using a table. The dataset template is used to display table based on the XML file. The XML file must be formatted correctly, but it only contains the data. The XML file contains no layout, only a basic table like structure.

The following XML file is used as input:

<dataset name="datasetname">
  <header>Column 1</header>
  <header>Column 2</header>
  <row>
    <field>Cell 1</field>
    <field>Cell 2</field>
  </row>
  <row>
    <field>Cell 3</field>
    <field>Cell 4</field>
  </row>
</dataset>

This XML file contains the descriptions of the headers (header titles) and per row every column value.
The Stylesheet for processing will look like this:

<xsl:template match="dataset">
  <table width="100%">
    <!-- Headers -->
    <thead>
      <tr>
        <xsl:for-each select="header">
          <th class="data"><xsl:value-of select="."/></th>
        </xsl:for-each>
      </tr>
    </thead>

    <!-- Table data -->
    <tbody>
      <xsl:for-each select="row">
        <tr>
          <xsl:variable name="oddeven" select="position() mod 2"/>
          <xsl:for-each select="field">
            <td>
              <xsl:attribute name="class">data<xsl:value-of select="$oddeven"/></xsl:attribute>
              <xsl:value-of select="."/>
            </td>
          </xsl:for-each>
        </tr>
      </xsl:for-each>
    </tbody>
  </table>
</xsl:template>

For every <header> tag a table header cell will be displayed. Then for every <row> tag a table row is created. The variable oddeven is filled with 1 on odd row numbers an 0 on even. This is used to select the correct CSS class attribute.
For every <field> in the same row a table cell is displayed.

This stylesheet is just a simple HTML table. There could be a stylesheet for a more advanced table with some graphics or even a PDF table.

This script will output the following table:

Column 1	Column 2
Cell 1	Cell 2
Cell 3	Cell 4

9 - Study XML

The following XML document is used in this guide.

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="/test.xsl"?>
<catalog>
        <cd>
                <title>International Superhits!</title>
                <artist>Green Day</artist>
                <label>Reprise</label>
                <price discount="10">14.49</price>
                <stock>3</stock>
        </cd>
        <cd>
                <title>Whoa Nelly!</title>
                <artist>Nelly Furtato</artist>
                <label>Dreamworks SKG</label>
                <price>15.99</price>
                <stock>24</stock>
        </cd>
        <cd>
                <title>Silver Side Up</title>
                <artist>Nickelback</artist>
                <label>Roadrunner</label>
                <price discount="10">15.49</price>
                <stock>14</stock>
        </cd>
        <cd>
                <title>This Way</title>
                <artist>Jewel</artist>
                <label>Atlantic</label>
                <price>14.49</price>
                <stock available="2 weeks">0</stock>
        </cd>
        <movie>
                <title>American Pie 2</title>
                <starring>Jason Biggs</starring>
                <actor>Shannon Elizabeth</actor>
                <actor>Natasha Lyonne</actor>
                <director>J.B. Rogers</director>
                <price>21.58</price>
                <stock>34</stock>
        </movie>
        <movie>
                <title>The Sixth Day</title>
                <starring>Arnold Schwarzenegger</starring>
                <actor>Robert Duvall</actor>
                <actor>Tony Goldwyn</actor>
                <actor>Michael Rapaport</actor>
                <director>Roger Spottiswoode</director>
                <price>19.96</price>
                <stock>6</stock>
        </movie>
        <movie>
                <title>Predator</title>
                <starring>Arnold Schwarzenegger</starring>
                <actor>Jesse Ventura</actor>
                <actor>Bill Duke</actor>
                <actor>Sonny Landham</actor>
                <director>John McTiernan</director>
                <price discount="15">16.99</price>
                <stock>18</stock>
        </movie>
</catalog>

The information in the XML document may be incorrect, it's for demonstration only.

Amé Schaake
Senna Schaake

XSLT Manual

Table of contents

1 - Basics

1.1 - Calling XSL stylesheets

1.2 - Nodes

1.3 - Basic structure

1.4 - Template structures

2 - Display XML content

2.1 - value-of

2.2 - HTML attributes

3 - Operators

3.1 - Booleans

3.2 - Numbers

4 - XPath functions

4.1 - last()

4.2 - position()

4.3 - count(node)

4.4 - id()

4.5 - local-name()

4.6 - namespace-uri()

4.7 - name()

4.8 - string()

4.9 - concat()

4.10 - starts-with()

4.11 - contains()

4.12 - substring-before()

4.13 - substring-after()

4.14 - substring()

4.15 - string-length()

4.16 - normalize-space()

4.17 - translate()

4.18 - boolean()

4.19 - not()

4.20 - true()

4.21 - false()

4.22 - lang()

4.23 - number()

4.24 - sum()

4.25 - floor()

4.26 - ceiling()

4.27 - round()

5 - XSLT funtions

5.1 - document()

5.2 - key()

5.3 - format-number()

5.4 - current()

5.5 - unparsed-entity-uri()

5.6 - generate-id()

5.7 - system-property()

5.8 - element-available()

5.9 - function-available()

6 - Control structures

6.1 - if

6.2 - for-each

6.3 - choose-when

7 - Variables

7.4 - variable

7.5 - param

7.6 - with-param

8 - Examples

8.1 - Datasets

9 - Study XML