<xsl:include> or <xsl:import>?

Written by Chriztian Steinmeier.
Got comments? I’m @greystate on Twitter. ← Back to Article Index

I’ve been asked about how to include and reuse XSLT in multiple files a number of times, so I thought it would make a good candidate for a new ‘Pimp My XSLT’ article. Enjoy, and don’t hesitate to ping me on twitter if you like/hate it!

When you’ve got some kind of functionality that’s ripe for reuse, you can choose between two similar ways of bringing that functionality from a separate stylesheet file into any other stylesheet, when needed.

<xsl:include href=”…” />

The first is using the xsl:include instruction, and you simply put it where you’d like the included templates to be, if you were to just copy and paste them right into the new file.

So I have this file — MediaHelper.xslt — with some templates to handle the “GetMedia Dance” of getting the node from the Media section etc. Here’s the basic idea:

File: MediaHelper.xslt

I can use the Media Helper above by including it in my new shiny “Render Page Image” macro:

File: RenderPageImage.xslt

Great - now all my macros can have simple media rendering, just by including that one file. And if I need to support PDF files as well, I can choose to add a simple template to either of those files, depending on whether it’s only for that specific project (in the macro) or more generally (in the helper):

Template: PDF file rendering

Because xsl:include inserts the templates at the point of which the instruction is placed, it’s easy to override a template in the included file, just by placing it after the xsl:include instruction, e.g.:

File: RenderVersionedPageImage.xslt

(If two templates in the same stylesheet end up matching the same element, the last one defined will effectively “win” the precedence battle for that element).

So what’s the need for another option, then? You said there were two ways of doing this…

<xsl:import href="…" />

Okay, right. So - let’s say you’re on this new project and there’s some strict policy that all images and files must be served wrapped in a pair of comments, stating the ‘last updated’ date and the user who saved it (obviously for reasons you are not cleared to know about. “Just do it”, you’re told), e.g. like this:

You could of course just copy the Image and File templates to the main file, and place them after the include instruction, like we did in the example above, and then add the secret comments to both template copies.

You could, however, also try the xsl:import instruction instead, as it lets you do something a little smarter, ridding your precious and modular code from the horror that is duplication. DRY, they say…

Using the xsl:import instruction is just as easy as with xsl:include, though it has to go before any other childnode of the main stylesheet.

File: RenderTimeStampedImages.xslt

As you can see, using the xsl:import instruction lets you override the imported templates, but at the same time, has the ability to execute the original, preserving its context, via the xsl:apply-imports instruction.

So there you have it - two ways to include common functionality from another stylesheet, thus making it easier to reuse some of the code you’ve already written. Hopefully this will help you decide which of the two to choose, from project to project.

Regardless what method you choose, be sure to install XSLTouch if you’re using Umbraco/.NET, to not have to worry about remembering to save the main file when you change something in the includes (!)

Thanks for reading all the way down here, and for putting up with all the LOST references :-)

See you at the 1st annual XSLT Ping Pong Fest in Copenhagen on November 20th!