XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (168 page)

Changing the Context Item

Another use of

is simply to change the context item. The need for this is reduced in XSLT 2.0, but it is still convenient on occasions. In XSLT 1.0, if you wanted to use the
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:

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

on page 240

on page 455

document()
function in Chapter 13, page 754

key()
function in Chapter 13, page 812

xsl:for-each-group

The

instruction selects a set of items, arranges the items into groups based on common values or other criteria, and then processes each group in turn.

Changes in 2.0

This instruction is new in XSLT 2.0.

Format

Position

is an instruction, which is always used within a sequence constructor.

Attributes

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

elements, followed by a sequence constructor.

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

instruction is summarized as follows:

• The expression in the
  select
  attribute is evaluated. This can return any sequence (of nodes or atomic values). This sequence is known as the
  population
  , and the order of the items in the sequence is called
  population order
  .
  
• Each item in the population is allocated to zero or more groups. The way this is done depends on which of the four attributes
  group-by
  ,
  group-adjacent
  ,
  group-starting-with
  , and
  group-ending-with
  is specified and is described in detail below. When
  group-by
  is used, an item may have more than one grouping key and may therefore be allocated to any number of groups (zero or more). In all other cases, each item in the population is allocated to exactly one group. (For the benefit of mathematicians, the groups are then said to
  partition
  the population.)
  
• The initial item of each group is identified. This is the item in the group that is first in
  population order
  , as defined above. If one or more sort keys have been defined using
  
  elements within the
  
  element, these sort keys are used to determine the processing order of the groups. Otherwise, the groups are processed in
  order of first appearance
  , that is, based on the position of their initial items in population order.
  
• There is a special rule covering what happens if an item is allocated to two groups and is the initial item in both of them. This can only happen if the item had several values for its grouping key, and the order of first appearance then relates to the order of these grouping keys in the result of the group-by expression. If the expression was
  group-by=“author”
  , and the value of this expression for the node in question was the sequence
  (“Gilbert”, “Sullivan”)
  , then the group for author Gilbert would be processed before the group for author Sullivan.
  
• The sequence constructor contained in the
  
  element is evaluated once for each group. Within the sequence constructor, the function
  current-group()
  may be called to obtain the items that are members of this group (in population order), and if the groups were defined using
  group-by
  or
  group-adjacent
  , then the function
  current-grouping-key()
  may be called to obtain the value of the grouping key that characterizes this group of items.
  
• The sequences that result from evaluating the sequence constructor once for each group are concatenated (in processing order) to form the final result of the
  
  instruction.
  

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

is to group items based on common values for a grouping key, which is achieved using the
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.