|Chapter 12 - Combining XSLT Stylesheets|
|XSLT For Dummies|
|by Richard Wagner|
|Hungry Minds 2002|
XSLT offers two closely related top-level elements for incorporating one stylesheet into another. These are:
Both of these elements sound pretty similar, dont they? At first glance, the differences between xsl:include and xsl:import seem nominal, almost esoteric. But, on closer inspection, you notice some important differences in their usage and behavior. In the following sections, I discuss some of their similarities and differences.
Tip When the XSLT processor encounters an xsl:include or xsl:import element, the processor takes all the contents of the referenced stylesheet (all the code between the xsl:stylesheet s start and end tags) and processes them based on the rules of the import/include element.
Remember You use xsl:include and xsl:import to include other XSLT stylesheets, not XML documents. If you want to combine codes from various XML documents, you can use the document() function, which I cover in Chapter 14.
Referencing valid stylesheets
Both the xsl:include and xsl:import elements must reference a valid XSLT stylesheet in their href attribute. You cant incorporate a file that has a snippet of XSLT code. Rather, you need to define a xsl:stylesheet element in the code and follow normal XSLT stylesheet conventions. Make sure that any stylesheet you want to reference can be called and run by itself, apart from any stylesheet that calls it.
Technical Stuff If youve worked with other programming languages before, such as C++ or Java, youre probably familiar with an include statement to incorporate source code from one file into another. The xsl:include is similar to these uses, except that the included file must be a normal stylesheet, not part of one.
Placing the elements
Both xsl:include and xsl:import must be added as top-level elements of the calling stylesheet. xsl:import has the strictest rules for its placement: It must appear as the first child element under an xsl:stylesheet element, or you get a processing error. In contrast, xsl:include can appear anywhere within the calling stylesheet as long as its a top-level element. You cant, for example, place an xsl:include element inside a template rule.
The most important difference between xsl:include and xsl:import is the different ways they handle conflicts. A conflict occurs when a top-level element from the incoming stylesheet is identical to an element in the calling stylesheet. xsl:import handles any collisions neatly: The element from the calling stylesheet wins because it has greater import precedence, discarding the element from the referenced stylesheet. In contrast, xsl:include cant handle conflict well: Any collision causes a processing error and so the transformation fails.
Consider, for example, the case in which a variable defined in the calling stylesheet has the same name as one in the referenced stylesheet. The referenced stylesheet looks like:
<!-- referencesheet.xsl --> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:variable name="state">pondering</xsl:variable> </xsl:stylesheet>
When another stylesheet uses xsl:import to call this stylesheet and has a conflicting variable name, the one in the calling stylesheet wins. So, in the following case, the state variable has the value of probing .
<!-- callingsheet.xsl --> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="referencesheet.xsl"/> <xsl:variable name="state">probing</xsl:variable> </xsl:stylesheet>
However, if xsl:include is used, you get a processing error because the variables are considered duplicates:
<!-- callingsheet.xsl --> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:include href="referencesheet.xsl"/> <xsl:variable name="state">contemplating</xsl:variable> </xsl:stylesheet>
You have to remove one of these variable declarations before continuing.
Remember xsl:include can potentially introduce conflict resolution problems that must be corrected before processing can continue. In contrast, a conflict in xsl:import never causes errors because the calling stylesheet always wins.
Handling identical template rules
Two template rules that have the same match pattern arent considered a conflict per se and dont generate a processing error with xsl:include . I explain in Chapter 4 that XSLT allows this scenario and simply prioritizes template rules based on a system of weighting . So, in the case where a template rule from the calling stylesheet is identical to the template rule of a called stylesheet, the following rules apply: