XSLT and XPath function reference in alphabetical order
(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z
fn:id
Category:
Association and localisation of nodes and resources at runtime
Origin:
XSLT 1.0 (now also part of XPath 2.0 Core)
Return value:
A node set (a sequence) which consists of elements with those identifiers resulting from the evaluation of the value passed on in the argument of the function call.
Call/Arguments:
fn:id($stringSequence, $node?)
$stringSequence:
Obligatory. A sequence of xs:string strings of which each one is treated as token list consisting of IDREF values separated by space characters. If the empty sequence is passed on to the function, the function returns the empty sequence.
$node:
(new in XSLT 2.0)
Optional. With the second argument any node can be passed on which is part of the document within which the function shall work. If the empty sequence is passed on, the function refers to the context document being current during the call (this corresponds to the call with a single argument). This argument is not available in XSLT 1.0.
Purpose of use:
The fn:id() function shall be applied to type valid documents. The basis for its usage is the existence of a DTD (or a Schema) which can be accessed and in which the attributes of ID type are declared which therefore have an is-id property. In a context document, elements with ID values are looked for which correspond to the IDREF values passed on to the function. The function outputs all found element nodes in document order as sequence, whereby duplicates are removed from the sequence when nodes are caught multiple times.
Behaviour under XSLT 2.0/XPath 2.0:
The list of IDREF values to be tested is generated from the string sequence passed on by regarding each of the strings as a token list of IDREF candidates, which means each string is split up to single tokens, whereby space characters serve as delimiters.
Each one of the tokens generated in this way must lexically correspond to the requirements for the IDREF type (which means corresponding to the xs:NCName type) otherwise it will be rejected or ignored (no error message occurs).
With the help of the list of values generated in this way, the context document is searched for elements with attributes of ID type which include one of the IDREF candidate values. If such an element is found, it will be added to the result sequence.
The equality of ID and IDREF candiate values is determined by the Unicode values (Codepoints) of their characters. No collation (also not the default collation) is used. As a consequence, the implicit identity is required in connection with the character values.
With the help of the optional second function argument, an alternative document can be determined to which the function shall refer. For this purpose, the document node of this document or any other node which is part of the document can be passed on. However, it is an error if a node is passed on whose tree has no document node as root element (»No context document«, err:FODC0001).
If no second argument is passed on and there is no context node at the moment of the function call, the context document is non-determinable which results in a runtime error (err:XPDY0002). If a context item exists but this item is not, as required, a node, the type error message err:XPTY0004 occurs.
Exceptions:
If the argument passed on is empty or not transformable into a string which corresponds to a permitted identifier (e.g. a string consisting of digits), an empty sequence (an empty node set) is returned. Accordingly, tokens consisting of digits which appear in a token list are ignored (because they lexically do not meet the requirements).
If the DTD or the Schema for the document is non-accessible or the document is read in by a non-validating XML parser, the function returns an empty sequence (as a precaution) since the ID type cannot be assigned reliably to the current attributes.
If there is a DTD or a Schema and the document is not type valid because of a double assignment of an identifier value, the first element in document order with the ID value searched for is adopted into the result node set.
ID attributes and attributes with the name »id«
In case the identifier attribute has in addition to the ID type also the identifier »id«, the function call fn:id('value') in the result corresponds to the XPath expression //*[@id='value']. However, the application of fn:id() will usually be faster in processing. The function, though, can only be applied to »real« identifiers declared in the DTD as attributes of ID type – then, however, independently of the actual identifier of the attribute (it is not necessary that the actual identifier of the attribute is known!). The function looks at all attributes having an is-id property.
Behaviour under XSLT 1.0/XPath 1.0:
In XSLT 1.0 the value passed on can be of any type, for example, it may represent a single string as well as a node set. If the value passed on is not a node set but any atomic value, it is transformed into a string according to the string() function.
If the argument passed on is a node set, each single node contained in the node set is converted into a string. This does not correspond to the usual conversion of a node set by string() because in that case only the first node of the set would be converted.
Apart from that, the behaviour is analogous to the behaviour described above. However, in this case the return value is formally a node set of elements with the ID values searched for. In contrast to the XPath 2.0 version, id() only accepts one argument at the maximum. Therefore, it is not possible to directly pass on another document to the function. This situation can be avoided by using the following XPath construction:
$external-document/id($comparativeValue)
Passing on an IDREFS token list:
The passing on of a token list can be realised by passing on an IDREFS attribute value to the function:
fn:id(@IDREFS-attribute)
If in the tested document no elements matching the identifiers passed on are found, the result node set is empty. This is not an error.
Possible compatibility problems XPath 2.0 to XPath 1.0:
In XPath 2.0 the expression fn:id(fn:true()) results in a type error since the function expects a xs:string string. XPath 1.0, however, transforms the Boolean input value into a string and searches afterwards for an element with the ID value "true". Similarly in XPath 2.0 also the passing on of a number is a type error. In XPath 1.0, in contrast, an expression like id(17) only results in an empty node set.
Example – resolving a relation of IDREFS to ID
With the help of fn:id(), input values of IDREF type are processed and the elements with the corresponding ID attribute are searched.
A book may have several authors which are referenced by the <book> element via an IDREFS attribute authors.
<book authors="author1 author2 author3">Example title</book>Each author element has an attribute of ID type whose value corresponds to a token of the IDREFS list of a book. The attribute, however, does not necessarily also need the id identifier:
<author id="author1">
<firstName>Berhard</firstName>
<lastName>ExampleAuthor</lastName>
</author>
The Current Node is a <book> element. During the processing, the value of its IDREFS attribute authors can be used as an argument of the fn:id() function in order to find all <author> elements having an ID which is pointed at by one of the references:
<xsl:template match="book">...written by
<xsl:for-each select="fn:id(@authors)">
<!-- sequence of all authors involved in the book -->
<xsl:value-of select="firstName">
<xsl:text> </xsl:text>
<xsl:value-of select="lastName">
<xsl:if test="fn:position() != fn:last()">, </xsl:if>
<xsl:if test="fn:position() = fn:last()"> and </xsl:if>
</xsl:for-each>
</xsl:template>
As a result, the list of all authors is outputted involved in the book and whose ID identifier is referenced in the IDREFS attribute authors of the <book> element.
Function definition:
XSLT 1.0:
id(object) => node set
XPath 2.0/XSLT 2.0:
fn:id($arg as xs:string*) as element()*
fn:id($arg as xs:string*, $node as node()) as element()*
| << back | next >> |
Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.
Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany