Appendix D. XSL Reference

CONTENTS

IN THIS APPENDIX

  •  XSLT and XPath
  •  Reference

The Extensible Stylesheet Language (XSL) was created for the presentation and formatting of XML documents for visual display. XSL is broken into three parts. The first, XSL Transformations (XSLT), is a set of XML elements used for transforming XML documents. The next part is XPath, which is an expression language used to access or refer to parts of an XML document; XPath is used in the XSL stylesheets to choose XML document parts to process or transform. The third part is XSL-FO (XSL Formatting Objects). This is an XML vocabulary for specifying formatting semantics, and is not covered here.

This appendix contains information related to XSLT and XPath. XSLT uses XPath for the selection of parts of an XML document. Once selected, these parts can be processed in various ways.

The appendix is broken into two sections. The first is a short discussion of XSLT and XPath, and the last is a quick reference of the commonly found tags and functions. An introductory discussion of how to use XPath expressions and XSLT can be found in Chapter 2, "Introduction to XML/XSL."

XSLT and XPath

XSL is based on recognition through matching. Each transformation is expressed as a set of rules that will match patterns found in the input. The transformation required is described, instead of providing sequential instructions to achieve it.

XSL works by matching nodes of XML documents through the matching capabilities of XPath. (If you don't know what a node is, read Chapter 2 first.) These nodes are selected through a combination of their location path in the tree structure, the text data contained therein, and the literal name of the element. After these nodes are selected, they can be processed through the rules of XSLT.

The set of rules transforms the tree structure, not the XML document itself. XSLT transforms the XML document through its content and structure, not the document itself. That means that the XML and XSL have to be parsed into a tree structure before they can be transformed. The transformation results in another tree that can be output or processed in some other way.

Context and Current Nodes

To use XSLT successfully, it is necessary to understand the difference between the context node and the current node. This knowledge will make XPath statements much easier to write.

The current node is always that node which is currently being processed, of the set of nodes causing the processing. The context node is the node that an XPath expression is currently matching through an XPath expression.

That is to say that each node being processed within an xsl:template element becomes the current node within the template body. This is also true of xsl:for-each elements. As each node of a node-set is being processed within an xsl:for-each structure, it becomes the current node.

Along the same lines, when that xsl:for-each element is closed, the current node will revert back to the node that it was before encountering the element.

The . always refers to the context node, whereas current() will always return the current node.

For example, let's suppose we had the following XML document. The first child element of the root contains descriptions for abbreviations, and the second element contains items that have abbreviated descriptions:

<?xml version="1.0" ?> <ROOT>     <KEYS>         <LKUP abbv="AB">AB description</LKUP>         <LKUP abbv="BC">BC description</LKUP>         <LKUP abbv="CD">CD description</LKUP>         <LKUP abbv="DE">DE description</LKUP>         <LKUP abbv="EF">EF description</LKUP>     </KEYS>     <PRODUCTS>         <ITEM desc="AB">MP3 player</ITEM>         <ITEM desc="DE">Wrench</ITEM>         <ITEM desc="EF">Car</ITEM>     </PRODUCTS> </ROOT>

Upon outputting the list of items, the descriptions have to be unabbreviated. This has been done in the following code. The xsl:for-each element selects the node-set consisting of all ITEM elements found descending from PRODUCTS elements that descend from the ROOT element. Each node of this set is processed one at a time in the body of the xsl:for-each element, and becomes the current node during that processing.

<xsl:for-each select="/ROOT/PRODUCTS/ITEM" >     <xsl:value-of select="current()" />     Description:     <xsl:value-of select="/ROOT/KEYS/LKUP[./@abbv = current()/@desc]" />     <hr /> </xsl:for-each>

In the following XPath expression, notice the use of . and current() together. This expression selects the text data of the LKUP element whose abbv attribute value is the same as the desc attribute value found in the ITEM element being processed.

/ROOT/KEYS/LKUP[./@abbv = current()/@desc]

The context node, namely the LKUP element that XPath selected, is referenced with .. In the same expression, the current node is referenced with the current() function. The current node is the ITEM element currently being processed within the xsl:for-each element.

Reference

This section is designed to serve as a quick reference for the more commonly used XSLT elements and XPath functions. It is by no means exhaustive.

In the following subsections, the word expression is used to denote the placement of an XPath statement.

XSLT Elements

The following XSLT elements are used together to create the declarative construct used to process an XML document representation. The definition of the unlisted XSLT elements can be found at http://www.w3c.org/TR/xslt.

The <xsl:apply-templates select=expression /> Element

This instruction causes the set of nodes selected by expression to be processed using the appropriate template rules. The xsl:sort and xsl:with-param elements are permitted in this element's body.

The <xsl:call-template name=string /> Element

This instruction invokes the template named string. This is analogous to a procedure call in other programming languages. The xsl:sort and xsl:with-param elements are permitted in this element's body.

The <xsl:choose /> Element

This instruction causes one choice to be selected out of a number of alternatives. It is analogous to the switch keyword in Java. The xsl:when and xsl:otherwise elements are permitted in this element's body. At least one xsl:when element must be found within this element.

The following code demonstrates its structure:

<xsl:choose>     <xsl:when test="$PageNum = 1">           ...     </xsl:when>     <xsl:when test="$PageNum = $Total">           ...     </xsl:when>     <xsl:otherwise>           ...     </xsl:otherwise> </xsl:choose>
The <xsl:for-each select=expression /> Element

This instruction selects a node-set using the XPath expression, and then processes each node of that node-set one by one using the instructions found in the body of this element. All elements are permitted in this element's body.

The <xsl:if test=expression /> Element

This instruction encloses processing that will only occur if expression resolves to true. All elements are permitted in this element's body.

The <xsl:otherwise /> Element

This instruction encloses the processing that will occur within an xsl:choose element when all xsl:when element expressions have resolved to false. This is analogous to the default keyword found in a switch structure in Java. This element can only be found within an xsl:choose element and can contain any elements. See xsl:choose for an example.

The <xsl:output method=string /> Element

This instruction controls the format of the serial output of the stylesheet. Some of the possible values for string are xml, html, and text. This element must be placed directly as a child of the root element, and other attributes exist for this element. No other elements are permitted in this element's body.

The <xsl:param name=string select=expression /> Element

This element is used either directly beneath the root element to define a global parameter, or immediately within a template as a parameter local to the template. The name of the parameter is defined in string, and the default value is assigned using expression. No other elements are permitted in this element's body.

The <xsl:sort select=expression /> Element

This instruction is used to sort a node-set prior to processing according to the node specified in expression. expression can select this node using its name or a number representing the child number to sort on. This element can only be placed within the xsl:apply-templates element, or as the first child of a xsl:for-each element. No other elements are permitted in this element's body.

The <xsl:stylesheet version=string namespacedeclaration /> Element

This element will always be the root element of a stylesheet, and therefore will contain all elements of the stylesheet. The version string will contain the version of XSLT required by this stylesheet. Currently, this can only be 1.0. Also, at a minimum there will be one namespace declaration on this element. Typically, namespacedeclaration will be xmlns:xsl = "http://www.w3.org/1999/XSL/Transform".

The <xsl:template name=string match=expression /> Element

This element is used to contain a block of processing instructions for producing output. The combined contents of this element can be thought of and used like a function definition. It can either be a template named string and invoked with xsl:call-template, or it can match particular XML nodes through expression and xsl:apply-templates. All elements are permitted in this element. If a parameter is to be defined here, it must be the first child of this element. Also, this element must appear as a child of the xsl:stylesheet element. All elements are permitted in this element's body.

The <xsl:value-of select=expression /> Element

This instruction results in the string value of expression being written to the output tree. No other elements are permitted in this element's body.

The <xsl:variable name=string select=expression /> Element

This instruction creates a variable whose name is string and whose value is the result of expression. Unlike in most programming languages, XSLT variables cannot be updated once they are assigned an initial value. They retain their value until they go out of scope. No other elements are permitted in this element's body.

The <xsl:when test=expression /> Element

This instruction defines actions to be performed if the condition in expression is true. This element can only be found within an xsl:choose element and can contain any elements. See xsl:choose for an example.

The <xsl:with-param name=string select=expression /> Element

This instruction sets the value of the parameter named string to the value of expression when calling a template. This element can only be found in either xsl:call-template or xsl:apply-templates elements. No other elements are permitted in this element's body.

XPath Functions

The following XPath functions are available for use within any XPath expression. They are grouped according to return value, and some examples are provided.

The functions listed here by no means present an extensive list. Instead, these are the functions that have been most commonly used in stylesheet authoring. The complete listing of XPath functions can be found at http://www.w3c.org/TR/xpath#corelib.

Boolean Functions

The following functions return Boolean values. If the argument is not already a Boolean, it is first converted using the boolean() function, after which the function is evaluated.

boolean(argument) returns the Boolean value of argument. The return values are as follows:

  • Number The number zero converts to false; all others convert to true.

  • String The empty string returns false; all else converts to true.

  • Node Set An empty node-set returns false; all else returns true.

false() XPath doesn't have any Boolean constants available for XPath expressions. As a result, false() and true() can be used where a constant is required.

not(argument) Results in the Boolean negation of the argument value: false if the argument is true, and true if the argument is false.

true() See false().

Number Functions

The following functions provide number-handling capabilities. If the argument is not already a number, it is first converted using the number() function, after which the function is evaluated.

ceiling(argument) Results in the smallest integer that is greater than or equal to the numeric value of argument.

floor(argument) Results in the largest integer that is less than or equal to the numeric value of argument.

format-number(argument, format) Returns argument formatted according to the pattern and rules of the format string. The following characters can be used to define the format string:

  • Pound (#) Used to match one digit. If a digit is in the specified location of argument, it is output. Otherwise, it is rounded to fit the pattern.

  • Zero (0) Zero-digit, causes a 0 to be placed in this output position if there is no number present in argument. Otherwise, the number in this position is output.

  • Period (.) Decimal-point, always matches to decimal place of number. Results in the output of a decimal place if followed by 0. Otherwise, decimal will only be output if number already contains one.

  • Comma (,) Grouping-separator, will be placed in the location specified by the pattern.

  • Percent (%) Multiply the number by 100 and show percentage.

  • Semicolon (;) Pattern separator. A pattern defined before this is for positive numbers, and a pattern found after this is for negative numbers.

  • Literal any character found inside the format string that is not one of the previously defined format characters can be output anywhere.

For example, the following expressions will return the noted results:

  • format-number(12.345, ##.##) returns 12.35

  • format-number(12345.1, ##.###) returns 12345.1

  • format-number(12.345, ##.0000) returns 12.3450

  • format-number(.1234, 00.00#) returns 00.123

  • format-number(1234.2, 00.###) returns 1234.2

  • format-number(1234.2, 0,0) returns 1,2,3,4

  • format-number(1234.2, 0,00.00) returns 12,34.20

  • format-number(.2345, 0.#%) returns 23.5%

  • format-number(2.345, $##.00;($##.00)) returns $2.35

  • format-number(-2.345, $##.00;($##.00)) returns ($2.35)

  • format-number(2345, $##.00 dollars) returns $2345.00 dollars

number(argument) Returns the argument converted to a number.

  • Boolean true becomes one; false becomes zero.

  • String Leading and trailing whitespace is removed. The string is then converted to a number. If it fails, the resulting value will be NaN (not a number).

  • Node Set The node-set is converted to a string using string(). The resulting string is then converted to a number as in the preceding.

round(argument) Returns argument rounded to the nearest integer.

sum(argument) Returns the sum of all nodes in the node-set argument. It is an error if any node in the node-set cannot be successfully converted using number(). It is also an error if argument is not a node-set.

String Functions

The following functions provide XPath with string-handling capabilities. If the argument is not already a string, it is first converted using the string() function, after which the function is evaluated.

concat(arguments) Returns a string consisting of the concatenation of all the arguments. There must be two or more values in arguments.

contains(string, substring) Returns the Boolean value true if substring can be found in string; otherwise, it returns false.

string(argument) Returns the string value of argument.

  • Boolean true becomes "true;" false becomes "false."

  • Number Integers are converted into a string representing their value.

  • Node Set The string value of the first node found is returned.

substring(string, start, length) Returns a string created by taking length characters of string, starting from the start character position.

translate(string, oldchars, newchars) Returns string with all the oldchars characters or strings found replaced with newchars.

Set Node Functions

The following functions either return node-sets or supply information in terms of node-sets.

count(node-set) Returns the number of nodes found in node-set. There is an error if node-set is not a node-set.

current() Returns the current node as a node-set. The current node is the node that is currently being processed when a set of nodes is being iterated. The current node does not change during the evaluation of expressions; the context node does.

last() Returns a number that is the value of the context size. This function is useful when you are trying to create a comma-separated list from a node-set. Adding the commas within the following statement will prevent the addition of a comma after the last node has been processed:

xsl:if position()!=last()

local-name() Returns a string whose value is the name of either the element or attribute without a namespace prefix whether or not there is one.

name() Returns a string value of the node exactly as it appears in the source document. This will include any namespace prefixes.

position(node) Returns a number that is the place number of node in the set of context nodes. For example, when iterating through a node-list using xsl:for-each, the position of each node processed will increment.

CONTENTS


JSP and XML[c] Integrating XML and Web Services in Your JSP Application
JSP and XML[c] Integrating XML and Web Services in Your JSP Application
ISBN: 672323540
EAN: N/A
Year: 2005
Pages: 26

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net