xsl:with-param


xsl: with-param

The <xsl:with-param> element is used to set the values of parameters when calling a template, either when using <xsl:call-template> , or when using <xsl:apply-templates> . It can also be used with <xsl: apply-imports > and with <xsl: next -match> .

Changes in 2.0

The <xsl:with-param> element can now be used as a child of <xsl:apply-imports> or <xsl:next-match> .

The as and tunnel attributes have been added.

When used with <xsl:call-template> , XSLT 2.0 defines compile-time errors if there is mismatch between the parameters supplied in the call and the parameters declared for the target <xsl:template> element.

Format

 <xsl:with-param   name = qname   select? = expression   as? = sequence-type   tunnel? = "yes"  "no-,>   <!-- Content: sequence-constructor --> </xsl:with-param> 

Position

<xsl:with-param> is always a child of <xsl:apply-templates> , <xsl:call-template> , <xsl:apply-imports> , or <xsl:next-match> .

Attributes

Name

Value

Meaning

name

mandatory

QName

The name of the parameter

select

optional

Expression

The value of the parameter to be supplied to the called template

as

optional

SequenceType

Defines the type of the value

tunnel

optional

«yes » or «no »

Indicates whether this is a tunnel parameter

Content

An optional sequence constructor. If a select attribute is present, the <xsl:with-param> element should be empty.

Effect

The <xsl:with-param> element assigns a value to a parameter. The value of the parameter can be used within the called template.

The value of the parameter is established in exactly the same way as for the <xsl:variable> element. That is, the value is obtained by evaluating the select expression if present, or the contained sequence constructor if not.

If the called template has an <xsl:param> element whose name matches that of the <xsl:with-param> element, then the value assigned to the <xsl:with-param> element is available within the template. If the called template has no such parameter, the value is ignored, except when using <xsl:call-template> , when this is an error. In the case of <xsl:apply-templates> , the parameter value is available in each of the templates that is called (one per selected node). The parameter is effectively evaluated once only-it will have the same value for each of these templates.

The name of the parameter is defined by a lexical QName. Normally this will be a simple name such as «city » or «total-sales » , but it may be a name qualified with a prefix, for example «my:value » . If it has a prefix, the prefix must correspond to a namespace that is in scope at that point in the stylesheet. The true name of the parameter, for the purpose of matching it with an <xsl:param> element in the called template, is determined not by the prefix but by the namespace URI corresponding to the prefix; so the name «my:value » will match a parameter declared as «your:value » if the prefixes «my » and «your » refer to the same namespace URI. If the name has no prefix, it has a null namespace URI-it does not use the default namespace URI.

It is an error for two sibling <xsl:with-param> elements to have the same name, after namespace prefixes are replaced with namespace URIs. In other words, you can't supply two values for the same parameter.

The <xsl:with-param> element does not actually declare a variable, so there is no problem if the name is the same as that of a variable that is currently in scope. In fact it is quite normal to pass a parameter in the form:

  <xsl:with-param name="current-user" select="$current-user"/>  

This is used to ensure that the variable «$current-user » in the called template has the same value as the variable «$current-user » in the calling template.

If the as attribute is present, then the supplied value of the parameter is converted to the specified type using the same rules as for <xsl:variable> . There is no requirement that this type must be identical to the declared type of the corresponding <xsl:param> : For example the <xsl:with-param> might specify «as="xs:byte" » when the <xsl:param> specifies «as="xs:integer" » . This means that potentially two conversions may take place, from the type of the supplied value as calculated by the select expression, to the type declared in the as attribute of <xsl:with-param> , to the type declared in the as attribute of the corresponding <xsl:param> . In each case the standard conversion rules are used, as described in the entry for <xsl:variable> on page 476.

The option «tunnel="yes" » allows the parameter to be set up as a tunnel parameter. Tunnel parameters are described in the entry for <xsl:param> on page 396, with a worked example on page 400.

Usage and Examples

Parameters to templates take on considerable significance in XSLT because variables cannot be updated. This means that many tasks that in conventional programming languages are done by updating variables in a loop are done instead in XSLT using recursive calls and parameters. The consequences of this are explained in Chapter 9, and there are some detailed examples of the technique in Chapters 11 and 12.

Examples of recursive calls are also included in this chapter under <xsl:call-template> on page 000 .

See Also

  • <xsl:apply-imports> on page 184

  • <xsl:apply-templates> on page 187

  • <xsl:call-template> on page 220

  • <xsl:param> on page 392




XSLT 2.0 Programmer's Reference
NetBeansв„ў IDE Field Guide: Developing Desktop, Web, Enterprise, and Mobile Applications (2nd Edition)
ISBN: 764569090
EAN: 2147483647
Year: 2003
Pages: 324

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net