I write a lot of XSLT for a variety of reasons, but somehow the “key” function has always baffled me. Every time I need to use it, I scour Google, and re-read my own XSLT code, trying to find examples that will help me, once again, understand how it works.

Recently I needed a simple string lookup function, and used document(“”) and key() to build it, but it was again a process of head-scratching trial and error. I got it to work, and I finally understand it. Here are the results, offered in the hope that they will aid some future fellow craftsman.

I’ll present a simplified example of using a lookup table embedded in the stylesheet itself. I’ll describe each hunk of code as we go along, and then show the whole thing put together.

My lookup table is going to be embedded in the stylesheet. So that it won’t be interpreted by the XSLT engine, we’ll put the table in a different namespace. The stylesheet element defines the namespace (“lookup:”), and declares it as an extension namespace so that it won’t appear in the output. You should use a different URL than “yourdomain”, and remember, it doesn’t have to actually resolve to something:

<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:lookup="http://yourdomain.com/lookup"
    extension-element-prefixes="lookup"
    version="1.0">

Then I create the lookup table. It’s an ad-hoc XML structure, at the top level of the stylesheet. Here I’m going to look up strings by an id, and I’ll use an id= attribute, with the string in the text of the element:

<lookup:strings>
    <string id='foo'>Fooey</string>
    <string id='bar'>Barbie</string>
</lookup:strings>

I use a <key> element to declare the key. This is where it starts becoming non-intuitive. The only way to understand the key feature of XSLT is to look at two parts at once: the key is declared with a <key> element, and then accessed with the key() function. The part that always throws me is that I expect the key definition to specify some source data: it does not. The key definition specifies what I think of as a hypothetical set of nodes, and a way to index into them. Later, when you use the key() function, you apply this definition to a real chunk of data.

The parts of a <key> element are:

• The name attribute: simply a name for the key definition, choose anything you want. You’ll use this later in the key() function to refer to the definition.
• The match attribute: this selects a set of nodes from the data to be named later.
• The use attribute: this specifies, for each node matched by the match attribute, the lookup value to use.

Here’s my key definition:

<xsl:key name='string' match='lookup:strings/string' use='@id' />

The name is “string”, the “match” attribute says to consider any <string> element that is a child of a <lookup:strings> element, and the “use” attribute says that for each such <string> element, we’ll use its “id” attribute as its tag. Think of the nodes selected by the “match” attribute as the records in the table, and the value on each selected by the “use” attribute as the indexed value in the record.

Now the key is defined, and we can actually use it with the key() function. It takes two arguments: the name of the key (from the name attribute of the <key> definitions), and the value to actually look up in the table. Remember we were going to specify the actual table data with the key() function, right? Well, not really. The table data is actually the current context node. That is, the records in the table are found by applying the <key>’s “match” attribute as a pattern against the current node. Here’s where the match attribute on the <key> element becomes so important. You have to carefully consider what your current context is, and design the key declaration to work within it.

In this case, we’ll use the document(“”) function to read the current stylesheet, finding the <lookup:strings> element in it. A <for-each> element changes the current context to the table. Normally, <for-each> is used to apply a template to a number of nodes. Here, we know there is only one, but <for-each> has the handy property of setting the current node. Then the key() function can apply the <key> match pattern to find the candidate records, using our supplied value (“foo”) to find a record with an id attribute of “foo”:

<xsl:template match='blah'>
    <!-- Look up the string "foo" and use it. -->
    <xsl:for-each select='document("")//lookup:strings'>
        <xsl:value-of select='key("string", "foo")'/>
    </xsl:for-each>
</xsl:template>

For repetitive use, you can define a variable to hold the table, and then use it from the variable each time:

<xsl:variable name='strings' select='document("")//lookup:strings' />

<xsl:template match='blah'>
    <xsl:for-each select='$strings'>
        <xsl:value-of select='key("string", "foo")'/>
    </xsl:for-each>
</xsl:template>

Finally, here’s a complete example:

<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:lookup="http://yourdomain.com/lookup"
    extension-element-prefixes="lookup"
    version="1.0">

<lookup:strings>
    <string id='foo'>Fooey</string>
    <string id='bar'>Barbie</string>
</lookup:strings>

<xsl:key name='string' match='lookup:strings/string' use='@id' />

<xsl:variable name='strings' select='document("")//lookup:strings' />

<xsl:template match='/'>
    <xsl:for-each select='$strings'>
        <xsl:value-of select='key("string", "foo")'/>
    </xsl:for-each>
</xsl:template>

</xsl:stylesheet>

When run on any input, this produces:

Fooey

Whew! No one ever claimed XSLT was succinct!

You might also want to look at:

• The <xsl:key>s to Happiness provides another walk-through of a similar problem.
• XSLT 2.0 adds a lot of features that should make this easier. It does away with the need for document(“”) and <for-each> by letting you declare the table as a variable, and then using the variable as a third argument to the key() function directly.