Using the <xsl:key> Element

The <xsl:key> element is a top-level element—that is, a child of the <xsl:stylesheet> element. The purpose of <xsl:key> is to declare the name of a key. The node corresponding to the key can then be retrieved using the key() function (see Using the key() Function). You can include as many <xsl:key> elements in your style sheets as needed.

The syntax for the <xsl:key> element is as follows:

<xsl:key name="name" match="node" use="expression" />

Note that <xsl:key> is always an empty element.

All the three attributes are required. Their values are as follows:

• name: This is a text string that assigns a name to the key. This name will be used by the key() function to retrieve the corresponding node from the source tree.
• node: This is the name of the node to which to assign the key. The value cannot contain a reference to a variable name.
• expression: Here, use an XPath expression that will be the value of the key. Note that this can be a string instead of one of the more common XPath expressions, which consist of one or more location steps. It can also be a call to the XSLT generate-id Function, which will assign a unique value to the key for this node even if no other unique value is available. The expression attribute, like the node attribute, cannot contain a reference to a variable name.

There are no constraints on the number of keys that can be assigned to a given node. Likewise, any number of nodes can be assigned keys with the same name and/or value.

Note   The XSLT standard sets few limits on the use of keys. However, a given XSLT application using keys might be limited by the hardware environment (particularly memory) in which the application is running. Also, the performance gains made possible by the use of keys require a trade-off: the time and memory resources required to build the index of keys when the style sheet is first processed, before the first transformation occurs. Therefore, using keys is not always efficient.

An example of the <xsl:key> element is:

<xsl:key name="isbn_key" match="book" use="@isbn" />

This declares a key named isbn_key. This key will be assigned to each <book> element, and will have as its value the value of that <book> element's isbn attribute. For example, the book Jambing on the Trixels will be assigned an isbn_key whose value is "991100-001"; For Love of a Toothpick will have isbn_key="991100-002"; and so on.

Here is another example:

<xsl:key name="categ_key" match="book" use="category" />

This tells the XSLT processor to build a key for the <category> child of each <book> element.

Though a key is most commonly assigned to an element based on the value of a child text node or element, or on the value of an attribute, the use attribute can readily take any other XPath expression relative to the element. For example, you could assign a key as follows:

<xsl:key name="book_for_categ" match="category" 
   use="../title" />

This assigns a key to each <category> element. The value of this key is the corresponding <book> element's <title> child.

Files Used for This Topic

• Sample XML Data File for XSLT Keys
• Sample XSLT File for XSLT Keys