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:idref

Category:

Association and localisation of nodes and resources at runtime

Origin:

XPath 2.0

Return value:

A sequence in document order consisting of those nodes of the context document having an IDREF or IDREFS value corresponding to one of the ID values passed on.

Call/Arguments:

fn:idref($stringSequence, $node)

$stringSequence:

Obligatory. A sequence of xs:string strings of which each one is treated as ID value. If the empty sequence is passed on to the function, the function returns the empty output sequence.

$node:

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 is equivalent to the call with a single argument).

Purpose of use:

The fn:idref() 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 IDREF type are declared which therefore have an is-id property.

The function is used in order to generate a sequence sorted in document order of all those nodes having an IDREF attribute whose value equals an ID value passed on to the function (or an IDREFS attribute for which this is the case for one of its fraction values).

So, its functionality is exactly the opposite of the functionality of the fn:id() function. It allows to relate ID values to IDREF or IDREFS values which reference these.

The list of ID values to be tested is generated from the string sequence passed on by regarding each of the strings as ID candidate. Each string must lexically correspond to the requirements for the ID type (which means corresponding to the xs:NCName type) otherwise it will be rejected or ignored. If there are duplicates in the range of the remaining ID values, the first is maintained and the rest of the ID values is rejected.

With the help of the list of values generated in this way, the context document is searched for elements with attributes of IDREF or IDREFS type which include one of the ID candidate values. If such an element is found, it will be added exactly once to the result sequence. This means that it appears even only once in the result sequence if it has, for example, an IDREFS attribute which contains various values of the ID candiate 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. This is analogous to fn:id().

The testing of the document is done in document order. As a consequence, the result sequence of nodes with the IDREF values searched for is also sorted in document order and does not contain duplicates.

The equality of IDREF and ID 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.

Example – resolving a relation of IDREFS to ID:

With the help of fn:idref(), input values of ID type are processed and the elements with the corresponding IDREF or IDREFS attribute are searched.

The example of the fn:id() function is reversed:

Each author element has an attribute of ID type (here also with id identifier) whose value corresponds to a token of the IDREFS list of a book:

<author id="author1">
   <firstName>Bernhard</firstName>
   <lastName>ExampleAuthor</lastName>
</author>

This time, you can find the books on which the author is involved and whose IDREFS attribute contains the value of the ID attribute of the <author> element as token. A book may have several authors who are referenced by the <book> element via an IDREFS attribute authors.

<book authors="author1 author2 author3">Example title</book>

The Current Node is an <author> element. During the processing, the value of its id attribute can be used as an argument of the fn:idref() function in order to find all <book> elements whose IDREFS attributes include the value passed on:

<xsl:template match="author">... has (co)written 
   <xsl:for-each select="fn:idref(@id)">
      <!-- sequence of all books written by the author -->
      <xsl:value-of select="title">
      <xsl:if test="position() != last()">, </xsl:if>
      <xsl:if test="position() = last()"> and </xsl:if>
   </xsl:for-each>
</xsl:template>

As a result, the list of all book titles is outputted in which the author has been involved and from which therefore an IDREF relation to the <author> element exists.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:idref($arg as xs:string*) as node()*

fn:idref($arg as xs:string*, $node as node()) as node()*

   

<< 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