XSLT for Dummies

XSLT offers two closely related top-level elements for incorporating one stylesheet into another. These are:

• xsl:include is used to draw the top-level elements of the specified stylesheet into the calling stylesheet. The XSLT processor treats the incoming contents as if you literally inserted them at the point of the xsl:include element. Its required attribute is href , which specifies the file to be included:

<xsl:include href="util.xsl"/>

• xsl:import loads the specified stylesheet, but makes it something like an auxiliary resource, extending the top-level elements of the current stylesheet. It has the following syntax:

<xsl:import href="util.xsl"/>

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.

Resolving conflicts

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:

• For xsl:import , the template rule in the calling stylesheet always wins.

• For xsl:include , the template rule that appears last wins. So if the xsl:include element comes before the template rule definition in the calling stylesheet, the calling stylesheet template rule is used. However, if the xsl:include line comes after the calling stylesheets template rule, the template rule from the called stylesheet wins.