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

See Also

on page 282

xsl:import

is a top-level element used to import the contents of one stylesheet module into another. The declarations in the importing stylesheet module have a higher
import precedence
than those in the imported module, which usually means that they will be used in preference, but the detailed rules vary for each type of declaration.

Changes in 2.0

There are no changes to the syntax of this instruction in XSLT 2.0. The rules for the
href
attribute have been reformulated to reflect current practice with XSLT 1.0: In effect, the way in which the URI is dereferenced to obtain a stylesheet module is now largely implementation defined. This allows for options such as catalogs or user-specified URI resolvers, as well as implementations that cache or precompile stylesheet modules.

Format

Position

is a top-level element, which means that it must appear as a child of the

element. Within an

element, the

child elements must come before any other children.

Attributes

Like all other XSLT elements, the

declaration may also have a
use-when
attribute. This is described in Chapter 3 (see page 127).

Content

None; the element is always empty.

Effect

The

declaration loads the stylesheet module identified in its
href
attribute. First, we'll look at how this module is located and then at the question of import precedence, which determines how the declarations in the imported module are used.

Locating the Stylesheet Module

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 the system will, by default, look for
date.xsl
in the same directory as
main.xsl
. You can change this behavior by using the
xml:base
attribute, as described in Chapter 2 on page 54. This allows you to specify a different base URI for resolving the relative reference.

The URI, once resolved, must identify an XML document that is a valid XSLT stylesheet module. The declarations in the imported stylesheet are logically inserted into the importing stylesheet at the point where the

element appears. However:

• Imported declarations have lower import precedence than the declarations that appear directly in the importing stylesheet, or are incorporated into it using
  
  . This is explained in more detail below.
  
• Imported elements retain their base URI, so anything that involves resolving a relative URI reference is done relative to the original URI of the imported stylesheet. This includes, for example, expansion of further
  
  elements, or use of 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 imported stylesheet module does not inherit namespace declarations from the module that imports it. This includes
  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 imported stylesheet, as well as
  xml:lang
  and
  xml:space
  , are those that were defined in the
  
  element of their own stylesheet module, not those on the
  
  element of the importing module.
  

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

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

The imported stylesheet module may contain

declarations to include further stylesheet modules, or

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

It is not an error to import the same stylesheet module more than once, either directly or indirectly, but it is not usually a useful thing to do. The effect is that the same definitions or templates will be present with several different import precedences. The situation is exactly the same as if two stylesheet modules with different names but identical contents had been imported.

The
href
attribute must be a fixed value—it isn't possible to compute its value at runtime. This is because the first thing an XSLT processor does, long before any source document is available, is to assemble the stylesheet from all its constituent modules and compile it into some internal representation. However, there is a new facility in XSLT 2.0 that allows stylesheets to be tailored to different environments. The
use-when
attribute is allowed on

(and indeed on any other XSLT element) to define a compile-time condition defining whether this element should be included or ignored. For example, you can write:

to import different modules depending on whether you are running Saxon, Gestalt, or AltovaXML. (See
product-switch.xsl
in the downloaded code for a full version of the stylesheet).

If you use a relative URI reference in the
href
attribute, and the system can't resolve it, check that the base URI of the main stylesheet module is known. If you're using the JAXP API for invoking a transformation, a common mistake occurs when you supply the main stylesheet as a
StreamSource
object. If you do this, you need to call the
setSystemId()
method to ensure that the system knows where the input stream comes from. Similar problems often arise on the Microsoft platform if you supply the stylesheet in the form of a DOM Document.

Determining the Import Precedence

Each stylesheet module that is imported has an import precedence. The rules are:

• The precedence of a module that is imported is always lower than the precedence of the module importing it.
  
• If one module imports several others, then the one it imports first has lower precedence than the next, and so on.
  

This means that in the structure shown in
Figure 6-3
, the highest precedence module is A followed by C, F, B, E, and finally D. The numbers on the diagram illustrate this. The absolute values have no significance, it is only the relative order of import precedence that matters.[insert]
6.3
[\insert]