XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (146 page)

Examples

The following example returns the name of a state in the USA based on a two-letter abbreviation for the state. If the abbreviation is not that of a recognized state, it outputs the abbreviation itself.

An alternative way of coding such an expression is to use template rules, perhaps in a particular mode:

The following example declares a variable called
width
and initializes its value to the
width
attribute of the current node, if there is one, or to 100 otherwise.

You might be tempted to write this as follows:

This is legal XSLT, but it does not achieve the required effect. This is because both the variables called
width
have a scope that is bounded by the containing element, so they are inaccessible outside the

instruction.

Everyone has personal preferences when coding. I tend to prefer constructs that are more compact than

. I would usually write the above example as:

See Also

on page 515

on page 420

on page 353

xsl:comment

The

instruction is used to write a comment node to the result sequence.

Changes in 2.0

A
select
attribute is added in XSLT 2.0, allowing the content of the comment to be defined by an XPath expression rather than by a sequence constructor. It's no longer an error to include two adjacent hyphens in the value of a comment—the processor will insert a space to make it legal XML.

Format

Position

is an instruction; it is always used within a sequence constructor.

Attributes

The
select
attribute and the sequence constructor are mutually exclusive; if one is present, the other must be absent.

Content

A sequence constructor.

Effect

The value of the comment is produced by evaluating either the
select
attribute or the sequence constructor. If neither is present, the comment will be empty.

The value is computed in the same way as for

(see page 254), except that the separator between adjacent values is always a single space. The resulting string forms the string value of the new comment node.

If the comment includes a hyphen that is immediately followed either by a second hyphen or by the end of the comment, a single space will be added after the offending hyphen to ensure that the comment follows the XML rules.

In XML or HTML output, the comment will appear as:

Usage

In theory, a comment has no meaning to the software that processes the output document—it is intended only for human readers. Comments are therefore useful to record when and how the document was generated, or perhaps to explain the meaning of the tags.

Comments can be particularly useful for debugging the stylesheet. If each

in the stylesheet starts with an

instruction, you will find it much easier to trace back from the output to your stylesheet.

Comments in HTML output are used for some special markup conventions, for example surrounding Dynamic HTML scripts. The purpose of the comment here is to ensure that browsers that don't understand the script will skip over it rather than display it as text. An example is shown below.

Examples

Three examples follow.

Example 1: Showing the Date and Time of Transformation

The following example generates a comment showing the date and time at which the output file was generated, and identifying the XSLT processor that was used:

Typical output might be:

Example 2: Generating Commented-Out JavaScript

The following example outputs a piece of client-side JavaScript to an HTML output file:

The output will look like this:

The comment cannot be written as a comment in the stylesheet, of course, because then the XSLT processor would ignore it entirely. Comments in the stylesheet are not copied to the output destination.

Example 3: Generating Comments Containing Markup

Sometimes you want to generate comments that contain markup, for example:

It's not possible to do this by creating a result tree that contains an element node as a child of a comment node, because comment nodes can't have children. This leaves two possibilities: either create the serialized representation of the element “by hand”, as a string, or trick the serializer into generating the comment delimiters by using character maps. The first approach looks like this:

The alternative solution uses a character map:

where the two entities
if-lt-IE6
and
endif
are defined in the DTD to map to arbitrary private-use-area characters, followed by:

xsl:copy

The

instruction copies the context item in the source document to the result sequence. This is a shallow copy; it does not copy the children, descendants, or attributes of the context node, only the context node itself and (if it is an element) its namespaces. For a deep copy, you need to use

, see page 292.

Changes in 2.0

New attributes
copy-namespaces
and
inherit-namespaces
have been added, to allow finer control over whether namespace nodes for an element should be copied or not.

New attributes
validation
and
type
have been added to control whether and how a copied node is validated against a schema.

Format

Position

is an instruction. It is always used within a sequence constructor.

Attributes

Name	Value	Meaning
copy-namespaces optional	yes or no . (Default is yes ).	Indicates whether the namespace nodes of an element should be copied.
inherit-namespaces optional	yes or no . (Default is yes ).	Indicates whether the children of a copied element will inherit its namespaces.
use-attribute-sets optional	Whitespace-separated list of lexical QNames	The names of attribute sets to be applied to a copied element.
validation optional	strict , lax , preserve , or skip	Indicates whether and how the copied nodes should be subjected to schema validation, or whether existing type annotations should be retained or removed.