What Is the Difference Between xsl:include and xsl:import?
Modularizing XSLT code into reusable files is essential for
maintainable stylesheets, and XSLT provides two top-level elements for
this purpose: <xsl:include> and
<xsl:import>. While both elements bring external
templates and definitions into a primary stylesheet, they handle rule
precedence and template overriding in fundamentally different ways.
<xsl:include> treats external code as if it were
pasted directly in place with equal precedence, whereas
<xsl:import> assigns lower precedence to the external
code, enabling precise stylesheet customization and overriding
mechanisms.
Understanding
<xsl:include>
The <xsl:include> element is used to merge
stylesheet modules at the same precedence level. When an XSLT processor
encounters <xsl:include href="..."/>, it incorporates
all the templates, variables, and definitions from the referenced file
as though they were written directly inside the including stylesheet at
that location.
Because included templates carry the same import precedence as the
main stylesheet, standard template conflict resolution rules apply. If
the main stylesheet and the included stylesheet define matching
templates with the exact same match pattern and
priority attribute, the XSLT processor will either raise an
error or select the last declared template in document order.
Key characteristics of <xsl:include>:
- Equal Precedence: Included rules share the same import precedence as the including document.
- Placement Flexibility: Can appear anywhere among the top-level elements of the stylesheet.
- Conflict Behavior: Duplicate templates with identical match patterns and priorities cause ambiguity errors or default to the last template defined.
Understanding
<xsl:import>
The <xsl:import> element is designed specifically
for stylesheet inheritance and specialization. Stylesheets brought in
via <xsl:import> are explicitly assigned a lower
import precedence than the importing stylesheet.
This lower precedence allows the main stylesheet to selectively
redefine or override templates from the imported module without
generating conflicts. Furthermore, the importing stylesheet can invoke
the overridden template logic using the
<xsl:apply-imports> instruction, similar to calling
super() in object-oriented programming.
Key characteristics of <xsl:import>:
- Lower Precedence: Imported templates always have lower import precedence than the importing stylesheet.
- Strict Placement:
<xsl:import>elements must appear before all other top-level elements (including<xsl:include>) in the stylesheet. - Overriding Capability: Overridden templates can
still be executed using
<xsl:apply-imports>or<xsl:next-match>(in XSLT 2.0+).
Key Differences at a Glance
| Feature | <xsl:include> |
<xsl:import> |
|---|---|---|
| Import Precedence | Same precedence as the parent stylesheet | Lower precedence than the parent stylesheet |
| Placement Rules | Anywhere as a top-level child of
<xsl:stylesheet> |
Must precede all other top-level elements |
| Template Overriding | Leads to conflict errors if priority and match are identical | Seamlessly overrides lower-precedence templates |
| Calling Overridden Code | Not supported | Supported via <xsl:apply-imports> |
| Primary Use Case | Splitting large stylesheets into manageable utility files | Creating specialized customizations of a base stylesheet |
When to Use Each Element
Use <xsl:include> when building a shared library
of independent utility templates, named templates, or global constants
where no overriding is intended. It acts as a straightforward structural
breakdown of a monolithic stylesheet.
Use <xsl:import> when designing a base stylesheet
meant to be extended, customized, or skinned for specific output formats
or clients. This approach keeps the core logic intact while allowing
individual implementations to override only the specific rules that
require modification.