Template matching is the mechanism that drives every XSLT transformation. Understanding how the processor selects templates — and what happens when multiple templates could match — is the difference between a stylesheet that works reliably and one that produces surprising output. This post covers everything you need to know.
How match patterns work
When the processor visits a node, it evaluates every template's match attribute as an XPath pattern. A pattern is a restricted form of XPath that tests properties of a node rather than selecting nodes from a starting point. If the pattern is satisfied, that template is a candidate.
Priority and conflict resolution
More than one template can match the same node. The processor resolves the conflict using priority. Each pattern has a default priority calculated by the spec:
| Pattern type | Default priority |
|---|---|
node() or *
|
-0.5 |
element-name |
0 |
prefix:element-name |
0 |
a/b (path) |
0.5 |
a[predicate] |
0.5 |
@attr |
0 |
More specific patterns automatically get higher priority. You can override this with the priority attribute:
If two templates have equal computed priority, the processor signals an error (or picks the last one, depending on implementation — Saxon issues an error by default). Always assign explicit priorities when you have competing templates.
The built-in templates
XSLT has default templates for every node type. If no explicit template matches a node, the built-in fires. For elements and the document root, the built-in calls apply-templates on all children. For text and attribute nodes, it outputs the string value.
This means that without any templates at all, the processor will walk the entire tree and output all text content. Understanding this explains why simple stylesheets can produce unexpected extra text — a text node matched nothing explicit, and the built-in output it.
To suppress text output globally, add:
This overrides the built-in with an empty template, producing no output for text nodes that are not handled elsewhere.
Modes
Modes let you have multiple templates for the same node that serve different purposes. A mode is a named context for a set of templates.
##
Call with mode:
Modes are especially useful when you need to process the same nodes in multiple places in the output with different logic each time.
apply-templates vs for-each
Both iterate over a set of nodes. The difference is that apply-templates dispatches to the best matching template for each node, while for-each stays in the current context and does not do template lookup.
Use apply-templates when you want polymorphism — different node types handled differently. Use for-each when you are doing a simple iteration over a homogeneous set and do not need dispatch.
-
Testing patterns in XSLT Playground
XSLT Playground is a fast way to experiment with matching rules. Paste a stylesheet with multiple competing templates and check which one fires. Add `` in each template to trace which one the processor picks. The trace panel shows all messages in order so you can follow the dispatch chain.
Solid understanding of template matching pays off every time you work on a complex stylesheet. Once you know how priorities and built-ins interact, most "unexpected output" bugs become obvious.
Top comments (0)