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

Content

None; the element is always empty.

Effect

The URI contained in the
href
attribute may be an absolute URI or a relative URI reference. If relative, it is interpreted relative to the base URI of the XML document or external entity containing the

element. For example, if a file
main.xsl
contains the element

, then by default the system will look for
date.xsl
in the same directory as
main.xsl
. You can change this behavior by using the
xml:base
attribute to specify a base URI explicitly, as described in Chapter 2 on page 54.

The URI (once resolved) must identify an XML document that is a valid XSLT stylesheet. The top-level elements of this stylesheet are logically inserted into the including stylesheet module at the point where the

element appears. However:

• These elements retain their base URI, so anything that involves resolving a relative URI reference is done relative to the original URI of the included stylesheet. This rule applies, for example, when expanding further
  
  and
  
  elements, or when using relative URIs as arguments to the
  document()
  function.
  
• When a namespace prefix is used (typically within a
  QName
  , but it also applies to freestanding prefixes such as those in the
  xsl:exclude-result-prefixes
  attribute of a literal result element), it is interpreted using only the namespace declarations in the original stylesheet module in which the
  QName
  occurred. An included stylesheet module does not inherit namespace declarations from the module that includes it. This even applies to
  QNames
  constructed at execution time as the result of evaluating an expression, for example an expression used within an attribute value template for the
  name
  or
  namespace
  attribute of
  
  .
  
• The values of the
  version
  ,
  extension-element-prefixes
  ,
  exclude-result-prefixes
  , and
  xpath-default-namespace
  attributes that apply to an element in the included stylesheet module, as well as
  xml:lang
  ,
  xml:base
  , and
  xml:space
  , are those that were defined on their own
  
  element, not those on the
  
  element of the including stylesheet module.
  

The included stylesheet module may use the simplified stylesheet syntax, described in Chapter 3. This allows an entire stylesheet module to be defined as the content of an element such as

. It is then treated as if it were a module containing a single template, whose match pattern is
/
and whose content is the literal result element.

The included stylesheet module may contain

statements to include further stylesheets, or

statements to import them. A stylesheet must not directly or indirectly include itself.

It is not an error to include the same stylesheet module more than once, either directly or indirectly, but it is not a useful thing to do. It may well cause errors due to the presence of duplicate declarations; in fact, if the module contains definitions of global variables or named templates and is included more than once at the same import precedence, such errors are inevitable.

Usage and Examples

provides a simple textual inclusion facility analogous to the
#include
directive in C. It provides a way of writing a stylesheet in a modular way so that commonly used definitions can be held in a library and used wherever they are needed.

If you are handling a wide range of different document types, the chances are they will have some elements in common, which are to be processed in the same way regardless of where they occur. For example, these might include standard definitions of toolbars, backgrounds, and navigation buttons to appear on your Web pages, as well as standard styles applied to data elements such as product names, e-mail contact addresses, or dates.

To incorporate such standard content into a stylesheet without change, use

. If there are definitions you want to override, use

.

is a compile-time facility; it is used to assemble the complete stylesheet before you start executing it. People sometimes ask how to include other stylesheets conditionally at runtime, based on conditions found in the source document. The answer is simple: you can't. It would be like writing a program in Visual Basic that modifies itself as it executes. If you do want different sets of rules to be active at different times, consider using modes, or consider inverting the logic, so that instead of having an all-purpose stylesheet that tries to include different sets of rules on different occasions, you make your principal stylesheet module the one that is most closely tailored to the circumstances, and use

to import the all-purpose rules into it, at a lower import precedence than the specialized rules.

It can make a difference where in your stylesheet the

statement is placed. There are some kinds of objects—notably, template rules—where if there is no other way of deciding which one to use, the XSLT processor has the option of giving priority to the one that occurs last in the stylesheet. This isn't something you can easily take advantage of, because in all these cases the processor also has the option of reporting an error. As a general principle, it's probably best to place

statements near the beginning of the file, because then if there are any accidental overlaps in the definitions, the ones in your principal stylesheet will either override those included from elsewhere, or be reported as errors.

See Also

on page 357

xsl:key

The

element is a top-level declaration used to declare a named key, for use with the
key()
function in expressions and patterns.

Changes in 2.0

The restrictions on using global variables in the
match
and
use
attributes have been eased.

It is now possible to define keys of any type (for example numbers or dates) and to a specify a collation to be used when deciding whether two string-valued keys match.

The key values for a node can now be evaluated using a sequence constructor contained in the

element, as an alternative to using the
use
attribute. This allows the evaluation to invoke templates or other XSLT constructs such as

.

Format

Position

is a top-level declaration, which means that it must be a child of the

element. It may appear any number of times in a stylesheet.

Attributes

The syntax for a
Pattern
is defined in Chapter 12.

The
use
attribute and the sequence constructor are mutually exclusive: if the
use
attribute is present, the element must be empty, and if it is absent, then there must be a nonempty sequence constructor.

Content

A sequence constructor. This is used as an alternative to the
use
attribute to determine the value of the key.

Effect

The
name
attribute specifies the name of the key. It must be a valid lexical QName; if it contains a namespace prefix, the prefix must identify a namespace declaration that is in scope on the

element. The effective name of the key is the expanded name, consisting of the namespace URI and the local part of the name.

The
match
attribute specifies the nodes to which the key applies. The value is a
Pattern
, as described in Chapter 12. If a node doesn't match the pattern, then it will have no values for the named key. If a node does match the pattern, then the node will have zero or more values for the named key, as determined by the
use
attribute or the contained sequence constructor.

The simplest case is where each node has one key value, and the key values are unique. For example, consider the following source document:

In the stylesheet you can define a key for the registration number of these vehicles, as follows:

The
use
attribute (or in its absense, the contained sequence constructor) specifies an expression used to determine the value or values of the key. This expression doesn't have to select an attribute, like
@reg
in the example above. For example, it could select a child element. It could also be a computed value, such as
count(*)
(the number of child elements that the node has). If the value is a sequence, the system creates an index entry for each item in the sequence, and the node can be found using any one of these values.