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

The
mode
attribute may also contain a list of modes to which the template is applicable. Each mode is written either as a lexical QName (the actual mode name) or as the token
#default
to indicate that the template is applicable to the default mode.

Mode names are compared using the usual rules for QNames—they match if the local name and namespace URI both match.

The mode specified on the

template is
not
automatically propagated to any

elements within its body. Although it is common practice to process an entire subtree in a single mode, and therefore for a template to continue using the mode it was called in, this is not the default behavior except in the case of built-in templates. However, the current mode can be propagated by explicitly calling

.

If you have a
mode
attribute on a template and there is no

element with a matching mode anywhere in the stylesheet, this is not an error, though it means the template will never be selected by any

call (it could however be invoked from the calling application if an initial mode is specified). This can be a handy way of commenting out a template rule.

Evaluating a Template

Once an

element is selected for processing, the following occurs:

• If it was called using
  
  , the context node, context position, and context size are set up as required.
  
• A new stack frame is allocated, to hold a new instance of each local variable defined within the template.
  
• All parameters listed in
  
  elements contained within the
  
  element are evaluated. These
  
  elements must come before any instructions in the content of the template. For each parameter, if a value was supplied by the caller (using an
  
  element with matching name), this value is assigned to the parameter. If necessary, the supplied values are converted to the required type specified in the
  as
  attribute, using the standard conversion rules described on page 505. If the supplied value has the wrong type, an error is reported. If no value was supplied by the caller, then if the
  
  element specifies
  required=“yes”
  an error is reported; otherwise, the default value of the parameter is evaluated. This process is explained in more detail under
  
  on page 425.
  
• The sequence constructor is evaluated. This means that the child instructions of the
  
  element are evaluated to produce a result sequence. XSLT instructions and extension elements are processed using their individual rules; literal result elements and text nodes are written to the result sequence.
  
• The result of evaluating the sequence constructor is checked against the type given in the
  as
  attribute of the
  
  element, if any. If necessary, the value is converted to the required type using the standard conversion rules given on page 505. If the value has the wrong type, a fatal error is reported.
  

When processing of the sequence constructor is complete, the stack frame containing its local variables is discarded, control returns to the calling template, and the context item, position, and size revert to their previous values. The value produced by evaluating the sequence constructor becomes the return value of the calling

,

,

, or

instruction. (If the calling instruction was

, the value is combined with the values delivered by the template rules for other selected nodes.)

Usage and Examples

We will look first at using template rules, and then I will give some advice on the use of modes. For examples of the use of named templates, see

on page 271.

Using Template Rules

A
template rule
is an

element with a
match
attribute, which can therefore be invoked using the

instruction.

This rule-based approach to processing is the characteristic way of writing XSLT stylesheets, though it is by no means the only way. Its biggest advantage is that the output for each element type can be defined independently of the context that the element appears in, which makes it very easy to reuse element types in different contexts or to add new element types to an existing document definition without rewriting the stylesheet templates for all the possible containing elements. A classic example of this approach to processing arises when converting semantic markup in a document to rendition markup, as the following example demonstrates.

Example: Template Rules

This example shows a typical use of template rules to handle narrative text with a free-form structure.

Source

The source file is
review.xml
.

This text contains the review of a concert performance, using both structured (data) and narrative (document) markup. Omitting some of the detail, it reads:

  Wigmore Hall

  London

  2007-03-27

  Carducci String Quartet

  Back at the Wigmore Hall on 

“2007-03-27”>27 March another fine group, the Carducci

Quartet, was joined by pianist Nicola Eimer

for a programme of Mozart, Ravel

 and Schumann. Following the current

fashion for the chamber versions of Mozart

concertos, the players opened with a lively and shapely performance of his

A major Concerto K414. ….

  

  Tim Homfray

  The Strad

  June 2007

Stylesheet

The stylesheet file is
review.xsl
.

This stylesheet resists the temptation to use varied fonts for the names of composers and artists, but merely uses italics for names of musical works:

     xmlns:xsl=“http://www.w3.org/1999/XSL/Transform”>

  

  

    

    

  

  

    

  

  

                separator=“ - ”/>

 

   

   

   

   

     

   

Note the use of CSS to achieve the styling, and the use of a
priority
attribute on the template for
match=“para/work”
to ensure that it is selected in preference to the template for
match=“para/*”
. In fact, the template for
match=“para/*”
(which handles all children of

other than

) does exactly what the built-in template would do—it outputs the text without any markup—but it does no harm to make it explicit.

Output

If the generated HTML is displayed in a browser, it will look like
Figure 6-14
.

Figure 6-14