xsl:mode

Allows properties of a mode to be defined.

Category: declaration
Content: ( xsl:template* )
Permitted parent elements: xsl:package ; xsl:stylesheet ; xsl:transform

Attributes

name?

eqname

Identifies the name of this mode; if omitted, the element describes the properties of the unnamed mode.

as?

sequence-type

New in XSLT 4.0. Declares the return type of all template rules in the mode.

streamable?

boolean

The value yes indicates that template rules using this mode must be capable of being evaluated in a streaming manner. This imposes restrictions on the content of the template rules. For details, see Streaming XML documents. Requires Saxon-EE.

use-accumulators?

tokens

Relevant only when this mode is the initial mode of the transformation. Defines the set of accumulators that are applicable to documents containing nodes in the initial match selection. Available since Saxon 9.7.0.10.

on-no-match?

"deep-copy" | "shallow-copy" | "shallow-copy-all" | "deep-skip" | "shallow-skip" | "text-only-copy" | "fail"

Indicates what action is taken when a node being processed by xsl:apply-templates in this mode matches no template rule. The default value is text-only-copy. The permitted values are:

  • text-only-copy: the XSLT 2.0 behaviour (for elements: apply-templates to the children; for text nodes: copy the text node to the output)

  • shallow-copy: invoke the "identity template", which copies an element node and does apply-templates to its attributes and children

  • shallow-copy-all: new in XSLT 4.0, this is a variant of shallow-copy which enables recursive descent processing of trees involving maps and arrays

  • deep-copy: invoke xsl:copy-of

  • shallow-skip: ignores this node, does apply-templates to its attributes and children

  • deep-skip: ignores this node and all its descendants

  • fail: reports a dynamic error

on-multiple-match?

"use-last" | "fail"

Indicates what action is taken when a node being processed by xsl:apply-templates in this mode matches more than one template rule (with the same precedence and priority). The values are fail indicating that a dynamic error is reported, or use-last (the default) indicating that the template rule appearing last in document order is chosen.

warning-on-no-match?

boolean

The value yes causes a run-time warning when a node is matched by no template rules. The default for Saxon is no.

warning-on-multiple-match?

boolean

The value yes causes a run-time warning when a node is matched by multiple template rules. The default for Saxon is yes.

typed?

boolean | "strict" | "lax" | "unspecified"

Informs the processor whether the nodes to be processed by template rules in this mode are to be typed or untyped. The default is unspecified, which places no constraints on the nodes.

copy-namespaces?

boolean

New in XSLT 4.0. If on-no-match is shallow-copy, shallow-copy-all, or deep-copy, then this attribute determines whether or not the built-in template rule copies unused namespace bindings. The default is yes.

visibility?

"public" | "private" | "final"

Determines the potential visibility of the component corresponding to this mode; the default is private.

saxon:trace?

boolean

Causes tracing of all template rules executed in the mode, showing the nodes selected by xsl:apply-templates and the rules used to process them. For details see saxon:trace.

Saxon availability

Available in XSLT 3.0 and later versions. From Saxon 9.8, available in all editions. Implemented in Saxon-PE and Saxon-EE since Saxon 9.6. Available for all platforms.

Details

The xsl:mode declaration is new in XSLT 3.0. Previously, modes were declared implicitly by referring to them in the mode attribute of xsl:template or xsl:apply-templates.

The element always appears as a child of xsl:stylesheet (or xsl:transform) or xsl:package, and in XSLT 3.0 it is empty (has no children).

In XSLT 4.0, an xsl:mode declaration for a named mode can contain template rules within the body of the xsl:mode declaration. This is known as an enclosing mode. Template rules within the enclosing mode cannot have a mode attribute (they automatically belong to the enclosing mode), and any xsl:apply-templates instructions within these template rules default their mode attribute to the enclosing mode. Template rules within an enclosing mode cannot be overridden by template rules outside it (in fact, template rules outside the enclosing mode cannot name that mode in their mode attribute). Specifying mode="#all" on a template rule has no effect on enclosing modes.

The purpose of enclosing modes is to make it easier to see at a glance what all the rules for a mode are, and thus to make it easier to work out which rules will match which nodes in an input document.

Template rules in an enclosing mode can in principle be overridden in another stylesheet package (using xsl:override) but this has not yet been tested.

The changes in XSLT 4.0 for the typed attribute, to handle items other than XNodes, are not yet implemented in Saxon.

Links to W3C specifications

XSLT 3.0 Specification

XSLT 4.0 Specification

See also

xsl:template

xsl:apply-templates