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

BOOK: XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition
9.69Mb size Format: txt, pdf, ePub

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:

       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


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

  select = expression

  group-by? = expression

  group-adjacent? = expression

  group-starting-with? = pattern

  group-ending-with? = pattern

  collation? = { uri } >

  


Position


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

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

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.

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.

Other books

Times and Seasons by Beverly LaHaye
Solaris by Stanislaw Lem
Conquest by Frost, S. J.
Tea by Laura Martin
Stolen Souls by Andrea Cremer
Emily's Dream by Holly Webb
Airframe by Michael Crichton
La sombra by John Katzenbach
The Nothing Job by Nick Oldham