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

generate-id

Category:

Node names, identifiers and URI information

Origin:

XSLT 1.0

Return value:

A xs:string string in the lexical form of a xs:NCName. The function is stable which means it returns at runtime for the same input a constant output.

Call/Arguments:

generate-id($nodeSequence)

$nodeSequence:

Optional. As argument a node sequence (in XPath 1.0 a node set) can be passed on whose first node receives the identifier. If no argument is passed on, the function is applied on the Current Node. If the argument is the empty sequence or the sequence does not contain any nodes, the empty string is returned. If the first item of the sequence passed on is not a node, an error is reported.

Purpose of use:

The generate-id() function is used in order to add an identifier to a node (normally to an element) at runtime of the stylesheet. This identifier remains connected with »its« element during the runtime. So, a renewed call of the function at runtime with the same node as argument returns the same identification string (which means the function is »stable« within the meaning of the specification). At the same time it is ensured that for all nodes (also document spanning) on which the function is applied an individual identifier is used.

The identification string consists of any alpha-numeric ASCII characters. The string has the syntactical form of a valid XML identifier (xs:NCName) which means it begins with a letter. In addition, the composition of the string is not determined, so it may vary from parser to parser. It is expressly not guaranteed that an ID value generated by generate-id() differs from ID values already statically allocated in the document! (However, the probability of such a conformance is really low.)

At runtime of the stylesheet, generated identifiers allow the reliable distinction of nodes. A further possibility of application is the automated generation of IDREF relations or jump labels in an outputted XHTML document by means of href="#genID" fragment identifiers which point at elements with the generated id attribute id="genID" (see example).

On the part of the processor there is no need that assigned identifiers again receive the same value for the same document at each runtime of the stylesheet. As long as the source document remains unchanged, however, this is mostly the case since the generation of the identifier is usually made on the basis of the position of the node in the document.

Generated identifiers are not addressable via fn:id()
It is not possible to read out the identifiers generated with generate-id() during the processing via the fn:id() function. The generated idenfiers are, so to speak, only »virtually« contained in the document tree during the processing, but they can be read out and copied into the output document. The fn:id() function, in contrast, only searches for identifiers »actually« located in the XML document – and declared as such – and requires the DTD (or a Schema) for their verification.

Example - generating corresponding id anchors:

<xsl:template match="song">
  <!-- generating id anchor point with generate-id() -->
  <h3 id="{generate-id()}"/><xsl:value-of select="title"/></h3>
  <p><b>Artist: </b><br/>
  <xsl:for-each select="artist">
  <xsl:value-of select="."/>
  (also: 
     <xsl:for-each select="//song[artist/text()=current()/text()][current()/parent::song != .]">
     <!-- generating link to the id anchor with generate-id() -->
     <a href="#{generate-id()}"><xsl:value-of select="title"/></a>
     <xsl:if test="fn:position() != fn:last()">
     <xsl:text>, </xsl:text>
     </xsl:if>
     </xsl:for-each>
   )<br/>
  </xsl:for-each>
  </p><hr/>
</xsl:template>

The template introduced for the explanation of the current() function is supplemented to the main entry of a song by generating a link from the context list of the songs of an artist. When calling the template, an identifier is bound to a <song> element with generate-id(). The function is again called in the inner xsl:for-each loop and generates for each song appearing in the context list of an artist a link to the accordingly corresponding main entry.

It does not matter when the IDs are generated to a node, meaning whether this occurs for the Current Node of the template in this example or in the course of the working through of the songs of the context list within the loop. In each case the result will be clear – so, there is basically no difference between the generation and the readout of an ID generated per function.

Function definition:

XSLT 1.0:

generate-id(node()?) => string

XSLT 2.0:

generate-id(node()?) as xs:string

Possible compatibility problems XSLT 2.0 to XSLT 1.0:

A possible deviation in the behaviour in XSLT 2.0 is due to the fact that the first item of a sequence may not be a node but an atomic value. In this case an error message should occur.

In contrast, the behaviour towards pure node sequences or empty sequences corresponds to the behaviour under XPath 1.0 towards non-empty and emtpy node sets. If an empty node set or in XSLT 2.0 an empty sequence is passed on, the function returns the empty string.

   

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