Read XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition Online
Authors: Michael Kay
Changing the Context Item
Another use of
key()
function (described in Chapter 13, page 812) to locate nodes in some ancillary document, it was necessary first to establish some node in that document (typically the root) as the context node, because the
key()
function will only find nodes in the same document as the context node.
For example, you might write:
The effect is to assign to the variable the value of the
name
attribute of the first element whose county-code key matches the value of the
$code
variable.
In XSLT 2.0 this particular example becomes simpler, because the
key()
function now accepts a third argument identifying the document to be searched. You can now write:
select=“key(‘county-code’, $code, document(‘county-code.xml’))/@name”/>
But there are other cases where the technique is still useful; for example, if you need to call a named template that is designed to operate on the context node.
In a stylesheet that handles multiple input documents, it is always a good idea to declare a global variable:
Then you can always return to the original source document by writing:
…
See Also
document()
function in Chapter 13, page 754
key()
function in Chapter 13, page 812
xsl:for-each-group
The
Changes in 2.0
This instruction is new in XSLT 2.0.
Format
select = expression
group-by? = expression
group-adjacent? = expression
group-starting-with? = pattern
group-ending-with? = pattern
collation? = { uri } >
Position
Attributes
Name | Value | Meaning |
select mandatory | XPath Expression | The sequence of items to be grouped, known as the population. |
group-by optional | XPath Expression | Grouping key. Items with common values for the grouping key are to be allocated to the same group. |
group-adjacent optional | XPath Expression | Grouping key. Items with common values for the grouping key are to be allocated to the same group if they are adjacent in the population. |
group-starting-with optional | Pattern | A new group will be started for each item in the population that matches this pattern. |
group-ending-with optional | Pattern | A new group will be started following an item that matches this pattern. |
collation optional | Collation URI | Identifies a collation used to compare strings for equality when comparing group key values. |
The attributes
group-by
,
group-adjacent
,
group-starting-with
, and
group-ending-with
are mutually exclusive. Exactly one of these four attributes must be present.
Content
Zero or more
Effect
Grouping takes as input a sequence of items (usually nodes) and organizes these items into groups. It then processes each of the groups in turn.
The effect of the
If the population is empty, then the number of groups will be zero. No group is ever empty. Whether the population contains nodes or atomic values, no attempt is made to remove duplicates. This means that if the same node appears twice in the population, it will generally appear twice in each group that it is allocated to.
The following sections describe the effect of each of the four attributes
group-by
,
group-adjacent
,
group-starting-with
, and
group-ending-with
in turn.
group-by
The most common way of using
group-by
attribute.
The
group-by
attribute is an XPath expression, which is evaluated once for each item in the population. It is evaluated with this item as the context item, with the position of this item in the population as the context position, and with the size of the population as the context size.
The value of the
group-by
expression is in general a sequence. This sequence is first atomized (as described in Chapter 2, page 81), and duplicate values are then removed from the atomic sequence that results. For each distinct value that remains in the sequence, the item is allocated to a group identified by this value. The total number of groups is equal to the number of distinct values present in the grouping keys for all items in the population.
Duplicate nodes are not removed from the population, but duplicate grouping keys calculated for a single node are removed. So if the authors of a book are J. Smith and P. Smith, and your grouping key is
author/surname
, then when you process the group for Smith, this book will be processed once, not twice.