XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (201 page)

Within the stylesheet as a whole, there are potentially several template rules that match the context node. The rules for the

instruction define an ordering of these rules: They are considered first in decreasing order of import precedence, then within each import precedence in decreasing order of priority, and finally within each priority, by the order of the declarations in the stylesheet (it is actually an error to have two rules with the same priority, but the processor is allowed to ignore this error and select whichever comes last in the stylesheet). At the end of the list is the built-in template rule for the particular kind of node. What

does is choose the template rule that comes next in this pecking order, after the current template rule.

It is possible to specify parameters to be supplied to the called template, using

elements contained within the

element. These work in the same way as parameters for

and

; if the name of the supplied parameter matches the name of an

element within the called template, the parameter will take this value; otherwise, it will take the default value supplied in the

element. It is not an error to supply parameters that don't match any

element in the called template rule, they will simply be ignored. However, if the called template specifies a parameter with
required=“yes”
, then a runtime error occurs if no value is supplied for this parameter.

The effect of the

instruction is very similar to

. The main difference is that with

, the only template rules that can be invoked are those in imported stylesheet modules. By contrast,

can invoke other template rules of lower priority in the same stylesheet module and can also invoke template rules that have lower import precedence because they were imported into the parent stylesheet module earlier than the current template rule. Looking at
Figure 6-4
on page 360, if the current template rule is in module C, then

will only consider template rules in module H, whereas

will also consider lower-priority rules in modules C, E, and J, as well as all rules in modules B, D, F, and G.

There is a special rule for the case where a template uses a union pattern and the two branches have different implicit priority, for example

. This is treated as if it were two separate template rules, which means that when you call

, the same template can be invoked more than once.

Usage and Examples

The intended usage pattern for

is illustrated by the following example.

One template rule might contain a general-purpose rule for formatting headings, as follows:

Another set of template rules contains specific rules for particular levels of headings:

These template rules each invoke the first rule using

, which avoids duplicating the common code in the template rule for each level of heading, and makes it easier to define changes later.

In this example I have made the priorities explicit, but in fact the default priorities could have been used. I always prefer to use explicit priorities when several rules match the same nodes, because it makes it clear to someone reading the stylesheet what your intentions were when you wrote it.

On this occasion there are three specialized rules, each invoking one generalized rule. But there are other problems where the structure can be inverted, so that the general rule invokes the special rule. For example, suppose you want to use a special color to render any inline text element that has the attribute
highlight=“yes”
. You might use a set of template rules like this:

and then process the
highlight
attribute in a higher priority template rule:

Unlike

, where invoking multiple template rules is possible only by defining multiple stylesheet modules,

allows several rules to be defined within a single module, which is often preferable because it makes the logic more clear.

Note that both

and

impose the constraint that the two (or more) template rules that match a node in the source tree work on the source node completely independently of each other. Neither rule can see or modify the nodes that the other rule has written to the result tree. This also means that (as the examples above show) the second rule can only create nodes that are children or siblings of the nodes created by the first rule; it cannot create parent nodes.

In some situations, therefore, other solutions might work better. In particular, another design pattern (sometimes called a
micropipeline
) is to use a multipass transformation whereby one template rule creates a temporary tree, which it then processes using a second template rule (perhaps in a different mode). The code tends to look like this:

This design pattern does not require use of

or

. One thing to watch out for when using this pattern is that the template rule for processing the