Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

The <xsl:key>element declares a named key for use with the keyfunction in XML Path Language (XPath) expressions for enabling easier access into complex XML documents. Keys are top-level elements, which means they cannot appear within a template.

Syntax 

<xsl:key
  name = 
QName
  match = 
Pattern
  use = 
expression>
</xsl:key>

Attributes

name

Identifies the key within the XSL Transformations (XSLT) document.

match

Specifies the pattern that should be matched. The Extensible Stylesheet Language (XSL) processor effectively preprocesses the source document and identifies all elements within the document that match the given pattern. Because the match is done on a node-by-node basis, it is not necessary to specify global pattern matches in the pattern string.

use

Provides the value to reference an element that satisfies the pattern specified in the matchattribute. Because the context is temporarily set to that element, the value of the useattribute should be an XPath expression that identifies each particular match, such as an idor similar element.

Element Information

Number of occurrences

Unlimited

Parent elements

xsl:stylesheet

Child elements

None

Remarks

The <xsl:key>element provides an alternative mechanism for addressing elements within an XML document. In effect, keys create a directory of specific elements from an XML source document, with the values generated from the useexpressions referring to those elements. The primary difference between a key and an id is that an id must be a fixed qualified name, while a key can be created from either one or several concatenated expressions.

The <xsl:key>element is designed to be used with the XPath keyfunction. The keyfunction takes two arguments — the name of the key and its value — and then either retrieves the node or nodes associated with that key–value pair, or returns an empty node-set if no matching element is found. Unlike id elements, a key() expression may be matched by more than one node.

It is possible, of course, to create an XPath expression that retrieves the same data a key would, but when working with relatively large XML documents, a key is often faster because it essentially indexes the locations of the desired data ahead of time.

While the XSLT parser compiles the search expressions for the key element ahead of time, the current implementation does not explicitly create the index unless a keyfunction is encountered. This guarantees that if a transformation bypasses the keyfunction call then the initial time-intensive indexing is not performed. Note also that, in accordance with the Worldwide Web Consortium (W3C) specifications, parameter or variable references cannot be used as part of a <xsl:key>match, ostensibly to avoid circular references.

Example

The following sample demonstrates use of the <xsl:key> element.

The XML file

Copy Code 
<?xml version="1.0"?>
<?xml-stylesheet href="key_sample.xsl" type="text/xsl"?>
<names>
   <last="Hamilton" first="David"/>
   <last="Hamilton" first="James R"/>
   <last="Hamlin" first="Jay"/>
</titles>

key_sample.xsl

The key_sample.xsl style sheet defines a key named "name-search" that locates name elements that have a last attribute equal to "Hamilton".

Copy Code 
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
  <xsl:key name="name-search" match="name" use="@last"/>
   <xsl:template match="/">
   <HTML>
	<BODY>
		<xsl:for-each select="key(name-search', 'Hamilton')">
		 <div>
		 <xsl:value-of select="@first"/>
		 </div>
	</xsl:for-each>
	</BODY>
	</HTML>
  </xsl:template>
</xsl:stylesheet>

Output

Copy Code 
David
James R

See Also