xsl:include

<xsl:include> is a top-level element used to include the contents of one stylesheet module within another. The definitions in the included stylesheet module have the same import precedence as those in the including module, so the effect is as if these definitions were textually included at the point in the including module where the <xsl:include> element appears.

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: 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

 <xsl:include   href = uri-reference~/>

Position

<xsl:include> is a top-level declaration, which means that it must appear as a child of the <xsl:stylesheet> element. There are no constraints on its ordering relative to other declarations in the stylesheet.

Attributes

Name	Value	Meaning
href mandatory	URI	The URI of the stylesheet to be included

Name

Value

Meaning

href

mandatory

URI

The URI of the stylesheet to be included

Like all other XSLT elements, the <xsl:include> declaration may also have a «use-when » attribute. This is described in Chapter 3 (see page 122). This can be used in the same way as on <xsl:import> : see the example on page 314.

Content

None; the element is always empty.

Effect

The URI contained in the href attribute may be an absolute URI or a relative URI. If relative, it is interpreted relative to the base URI of the XML document or external entity containing the <xsl:include> element. For example, if a file main.xsl contains the element <xsl:include href="date.xsl"/> 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 53.

The URI 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 <xsl:include> element appears. However:

These elements retain their base URI, so anything that involves referencing a relative URI is done relative to the original URI of the included stylesheet. This rule applies, for example, when expanding further <xsl:include> and <xsl:import> 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 <xsl:element> .
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 <xsl:stylesheet> element, not those on the <xsl:stylesheet> 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 <HTML> . 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 <xsl:include> statements to include further stylesheets, or <xsl:import> 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 stylesheet contains definitions of global variables or named templates, and is included more than once at the same import precedence, such errors are almost inevitable. In some other situations it is implementation-defined whether an XSLT processor will report duplicate declarations as an error, so the behavior may vary from one product to another.

Usage and Examples

<xsl:include> 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 <xsl:include> . If there are definitions you want to override, use <xsl:import> .

<xsl:include> 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 <xsl:import> 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 <xsl:include> 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 <xsl:include> 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.

Using <xsl: Include> with Named Attribute Sets

This example shows the use of <xsl:include> to incorporate declarations (in this case of a named attribute set) from one stylesheet module into another.

Source

This example can be used with any source document.

Stylesheet

Consider a principal stylesheet picture.xsl that includes a stylesheet attributes.xsl , as follows :

  <xsl:stylesheet version="1.0"   xmlns:xsl="http://www.w3.org/1999/XSL/Transform">   <xsl:include href="attributes.xsl"/>   <xsl:template match="/">   <picture xsl:use-attribute-sets="picture-attributes">   <xsl:attribute name="color">red</xsl:attribute>   </picture>   </xsl:template>   </xsl:stylesheet>

This includes the module attributes.xsl :

  <xsl:stylesheet version="1.0"   xmlns:xsl="http://www.w3.org/1999/XSL/Transform">   <xsl:attribute-set name="picture-attributes">   <xsl:attribute name="color">blue</xsl:attribute>   <xsl:attribute name="transparency">100</xsl:attribute>   </xsl:attribute-set>   </xsl:stylesheet>

The named attribute set in the included stylesheet is used exactly as if it were defined in the principal stylesheet, at the point where the <xsl:include> statement appears.

Output

The resulting output is:

  <picture transparency="100" color="red"/>

This is because attributes generated using <xsl:attribute> override those generated by using a named attribute set; it has nothing to do with the fact that the attribute set came from an included stylesheet.