11.1 A Simple Key

Following is part of the valid XML document un.xml (found in examples/ch11), which stores information about the 190 member states of the United Nations (UN). Example 11-1 is just a fragment of the document as, at over 700 lines, it's too long to list in its entirety.

Example 11-1. Information about countries that belong to the UN
<?xml version="1.0" encoding="ISO-8859-1"?>     <un>  <state cc="af">   <name>Afghanistan</name>   <admitted>19 Nov. 1946</admitted>  </state>  <state cc="al">   <name>Albania</name>   <admitted>14 Dec. 1955</admitted>  </state>  <state cc="dz">   <name>Algeria</name>   <admitted>8 Oct. 1962</admitted>  </state>  <state cc="ad">   <name>Andorra</name>   <admitted>28 July 1993</admitted>  </state>  <state cc="ao">   <name>Angola</name>   <admitted>1 Dec. 1976</admitted>  </state>  <state cc="ag">   <name>Antigua and Barbuda</name>   <admitted>11 Nov. 1981</admitted>  </state>  <state cc="ar">   <name>Argentina</name>   <admitted>24 Oct. 1945</admitted>  </state>  <state cc="am">   <name>Armenia</name>   <admitted>2 Mar. 1992</admitted>  </state>  <state cc="au">   <name>Australia</name>   <admitted>1 Nov. 1945</admitted>  </state>

This document holds three pieces of information for each member state:

  1. The member state's country code, stored as the value of the cc attribute on the state element.

  2. The name of the member state, stored in the name element.

  3. The date that the member state was admitted to the UN, stored in the admitted element.

The following stylesheet, un.xsl, declares a key on the top level and then uses it in the template to pick up information about Australia (au) from un.xml (note bold):

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="text"/> <xsl:key name="UN" match="state" use="@cc"/> <xsl:template match="/">  <xsl:value-of select="key('UN', 'au')/name"/> </xsl:template>     </xsl:stylesheet>

The following two sections explain the interrelationship between the key element and the key( ) function.

11.1.1 The key Element

The key element is a top-level element, meaning that it must be a child of the stylesheet element and is not allowed inside templates. It has three required attributes. The first is the name attribute, which provides the name by which a key( ) function may refer to the declared key. The name of the key in un.xsl is UN.

The second attribute, match, contains a pattern that the key matches, just as the match attribute on the template element matches a pattern. The pattern that the key declaration matches in un.xsl is the location path state.

The third and final attribute, use, contains an expression that is applied to every node that matches the pattern in match. The value of use in this declaration is @cc, which corresponds to the cc attribute on state elements.

This key declaration won't do you any good unless you use a key( ) function in the stylesheet to find and exploit the key. You can call the key( ) function in an expression, such as in the select attribute of value-of.

11.1.2 The key( ) Function

In order to do its work, the key( ) function depends on a top-level key declaration. This function returns a node-set. Its signature indicates that it has two required arguments:

key(string, object)

The first argument to key( ) is a string enclosed in single quotes that matches the name of a declared key. In the un.xsl stylesheet, the name is UN, also in single quotes. The second argument is an object that will be converted to a string and applied to the key. This value must match the node defined in the expression contained in the use attribute of the key element. So, in un.xsl, the argument au in single quotes matches the state element in un.xml that has a cc attribute with a value of au.

Following the function call to key( ) is the location path /name. This path refers to a child node of the node returned as a result of calling key( ). As with the document( ) function, you can add location paths after the key( ) function call.

To see how it works, apply the stylesheet to the document:

xalan un.xml un.xsl

and you will get this result:

Australia

The expression in the select attribute of value-of calls the key( ) function using the key declaration named UN. The single quotes (') around the function arguments are necessary. During the transformation, the expression found a state node in un.xml that had a cc attribute whose value was au. Then value-of returned the text node in the name child of the matching node, that is, the text Australia.

The interesting thing about keys in XSLT is that they don't rely on context to do their work. Keys establish their own context, based on the value of the match attribute in the key element. (Keys also select only nodes that exist in the same document as the context node.) This makes keys appropriate for use in situations where you don't want to rely on a current context to do processing. This characteristic, likewise, makes keys suitable for cross-referencing nodes in entirely different contexts, as you will see in Section 11.4, later in this chapter.



Learning XSLT
Learning XSLT
ISBN: 0596003277
EAN: 2147483647
Year: 2003
Pages: 164

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