xsl:apply-imports

xsl: apply-imports

The <xsl:apply-imports> instruction is used in conjunction with imported stylesheets. A template rule in one stylesheet module can override a template rule in an imported stylesheet module. Sometimes, you want to supplement the functionality of the rule in the imported module, not to replace it entirely. <xsl:apply-imports> is provided so that the overriding template rule can invoke the overridden template rule in the imported module.

There is a clear analogy here with object-oriented programming. Writing a stylesheet module that imports another is like writing a subclass, whose methods override the methods of the superclass. <xsl:apply-imports> behaves analogously to the super() function in object-oriented programming languages, allowing the functionality of the superclass to be incorporated in the functionality of the subclass.

Changes in 2.0

In XSLT 2.0, the instruction is extended to allow parameters to be passed using enclosed <xsl: with-param > elements.

XSLT 2.0 also introduces a new <xsl: next -match> instruction, which will often be a more suitable solution in situations where <xsl:apply-imports> might have previously been used.

Format

  <xsl:apply-imports>   <!-- Content: xsl:with-param* -->   </xsl:apply-imports>

Position

<xsl:apply-imports> is an instruction, and is always used within a sequence constructor.

Attributes

None.

Content

The element may be empty, or it may contain one or more <xsl:with-param> elements.

Effect

<xsl:apply-imports> relies on the concept of a current template rule. A template rule becomes the current template rule when it is invoked using <xsl:apply-templates> , <xsl:apply-imports> , or <xsl:next-match> . Using <xsl:call-template> does not change the current template rule. However, using <xsl:for-each> makes the current template rule null, until such time as the <xsl:for-each> terminates, when the previous value is reinstated. The current template rule is also null while global variables and attribute sets are being evaluated.

<xsl:apply-imports> searches for a template rule that matches the current node, using the same search rules as <xsl:apply-templates> , but considering only those template rules that (a) have the same mode as the current template rule and (b) are defined in a stylesheet module that was imported into the stylesheet module containing the current template rule. For details of import precedence, see <xsl:import> on page 312.

The specification defines what this means in terms of the import tree. If a stylesheet module A includes another module B using <xsl:include> , then A and B are part of the same stylesheet level. If any module in stylesheet level L imports a module in stylesheet level M, then M is a child of L in the import tree. The template rules that are considered are those that are defined in a stylesheet level that is a descendent of the stylesheet level containing the current template rule.

It is possible to specify parameters to be supplied to the called template, using <xsl:with-param> elements contained within the <xsl:apply-imports> element. These work in the same way as parameters for <xsl:call-template> and <xsl:apply-templates> ; if the name of the supplied parameter matches the name of an <xsl:param> element within the called template, the parameter will take that value, otherwise it will take the default value supplied in the <xsl:param> element. It is not an error to supply parameters that don't match any <xsl:param> element in the called template rule, they will simply be ignored. However, if the called template specifies any parameters with «required= "yes" » , then a runtime error occurs if no value is supplied for that parameter.

Usage and Examples

The intended usage pattern behind <xsl:apply-imports> is illustrated by the following example.

One stylesheet, a.xsl , contains general-purpose rules for rendering elements. For example, it might contain a general-purpose template rule for displaying dates, given as follows :

  <xsl:template match="date">   <xsl:value-of select="day"/>   <xsl:text>/</xsl:text>   <xsl:value-of select="month"/>   <xsl:text>/</xsl:text>   <xsl:value-of select="year"/>   </xsl:template>

A second stylesheet, b.xsl , contains special-purpose rules for rendering elements. For example, you might want it to display dates that occur in a particular context in the same way, but in bold face. It could be written as:

  <xsl:template match="timeline/date">   <b>   <xsl:value-of select="day"/>   <xsl:text>/</xsl:text>   <xsl:value-of select="month"/>   <xsl:text>/</xsl:text>   <xsl:value-of select="year"/>   </b>   </xsl:template>

However, this involves duplicating most of the original template rule, which is a bad idea from a maintenance point of view. So, in b.xsl we could import a.xsl , and write instead:

  <xsl:import href="a.xsl"/>   <xsl:template match="timeline/date">   <b>   <xsl:apply-imports/>   </b>   </xsl:template>

Note that the facility only allows a template rule to invoke one of lower import precedence, not one of lower priority. The import precedence depends on how the stylesheet module was loaded, as explained under <xsl:import> on page 312. The priority can be specified individually for each template rule, as explained under <xsl:template> on page 450. The code above will work only if the «timeline/date » template rule is in a stylesheet that directly or indirectly imports the «date » template rule. It will not work, for example, if they are in the same stylesheet but defined with different priority. In this respect, <xsl:apply-imports> differs from <xsl:next-match>4 .

In many situations the same effect can be achieved equally well by giving the general-purpose template rule a name, and invoking it from the special-purpose template rule by using <xsl:call-template> (see page 220). But this approach doesn't work if you want one rule that overrides or supplements many others. One example I encountered was a developer who had a working stylesheet, but wanted to add the rule "output an HTML <a> tag for any source element that has an anchor attribute." Rather than modifying every rule in the existing stylesheet, this can be achieved by defining a new stylesheet module that imports the original one, and contains the single rule:

  <xsl:template rnatch="*[@anchor]">   <a name="{@anchor)"/>   <xsl:apply-imports/>   </xsl:template>

There is a more complete example of the use of <xsl:apply-imports> in the section for <xsl:import> .