The current-grouping-key() function returns the value of the grouping key that defines the group currently being processed using the <xsl:for-each-group> instruction. The grouping key is the value of the expression in the group-by or group-adjacent attribute. When grouping is done using patterns, there is no current grouping key.
This function is new in XSLT 2.0.
There are no arguments.
Data type | Meaning | |
---|---|---|
Result | xdt:anyAtomicType? | This is the value of the group-by or group-adjacent expression that is shared by all the items in the current group. The return type indicates that the grouping key can be of any atomic type, for example xs:string , xs:decimal , or xs:date . When there is no current group, the function returns an empty sequence. |
When the stylesheet starts executing, there is no current grouping key; the current-grouping-key() function then returns an empty sequence.
The <xsl:for-each-group> instruction, described in Chapter 5, page 281, takes as input a sequence of items called the population and a grouping expression or pattern. If the grouping criteria are defined using the group-by or group-adjacent attributes, then while each group is being processed, the current-grouping-key() function returns the grouping key value that characterizes that group.
If the grouping criteria are defined using the group-starting-with or group-ending-with attributes of <xsl:for-each-group> , the current grouping key is an empty sequence.
The current-grouping-key() function does not need to be called textually within the <xsl:for-each-group> instruction. Its scope is dynamic, and the current grouping key remains available in called templates unless another nested <xsl:for-each-group> instruction is evaluated. On completion of an <xsl:for-each-group> instruction, it reverts to its previous value.
The current-grouping-key() function can also be called while evaluating the sort key in an <xsl:sort> element contained within the <xsl:for-each-group> instruction. This affects the order in which groups are processed. In this context, current-grouping-key() refers to the group whose sort key is being calculated. For example, to sort groups in descending order of their grouping key, write <xsl:sort select="current-grouping-key()" order="descending"/> .
On entry to a stylesheet function, the current grouping key is an empty sequence.
The following example groups a set of books by the name of the author. For each author, a section heading is displayed giving the name of the author, followed by a list of the books written by this author. The authors are sorted by name . A book that has several authors will be listed more than once.
<xsl:for-each-group select="//book" group-by="author"> <xsl:sort select="current-grouping-key()"/> <h2><xsl:value-of select="current-grouping-key()"/></h2> <xsl:apply-templates select="current-group()"/> </xsl:for-each-group>
<xsl:for-each-group> , page 281 in Chapter 5.