group

A logic command that takes a Collection and constructs a specific kind of data structure in which the Collection's items are grouped based on some property of the items. The produced structure is well-suited for certain document layout purposes in which it is desired to present items in this kind of categorized manner, like in separate tables for example.

Specifically, what this command produces is a Collection of Maps, of which each represents a group and holds some of the original Collection's items that share some property, resolved through an EL-expression defined through the groupBy attribute. Each group Map also contains the value each of the group's items share. Optionally each group Map may also contain a sum of some numerical value within the group's items, specified through the sum attribute. The group Map therefore contains the following keys and values:

name - A String that is the name of the group, which is some particular value shared by all the items within the group.
items - A Collection that contains the items of the group.
sum - A Number that is the sum of specified values found within the items. This entry only exists if the sum attribute is defined.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the produced Collection of Maps.

value
Required	Value type	EL-evaluated
Yes	Collection	Yes
Defines the Collection whose items this command will be categorizing into smaller groups.

groupBy

Required

Value type

EL-evaluated

Yes

String

No

Specifies the expression that is used to find a value from each item in the Collection, by which the item is then grouped by. The expression is to be formed as if it was evaluated within a loop iterating through the Collection, with "x" being the variable name for the item itself.

Make sure that this expression resolves into a non-null value with each of the Collection's items. If the expression resolves into null at any point, the grouping cannot be done and an error is produced.

orderBy

Required

Value type

EL-evaluated

No

String

No

Specifies an expression that is used to find a value from each item in the Collection. The items are then sorted based on how these values get sorted. The expression is to be formed as if it was evaluated within a loop iterating through the Collection, with "x" being the variable name for the item itself.

By default the items are sorted in ascending order. Use the orderDescending attribute to reverse this if needed.

If not defined, the items will not be sorted in any particular way.

orderDescending

Required

Value type

EL-evaluated

No

Boolean

Yes

Defines the sorting order of the Collection items if the orderBy attribute is defined. If the resolved value is true, the items will be in descending order, ascending otherwise.

If undefined, the items are sorted in ascending order.

sum
Required	Value type	EL-evaluated
No	String	No
Specifies an expression that is used to find a Number or Currency value from each item in the Collection. Each group Map then contains the entry "sum" with the sum of all the resolved numerical values of the items of that group. The expression is to be formed as if it was evaluated within a loop iterating through the Collection, with "x" being the variable name for the item itself.

Examples

A typical target for the group command would be Salesforce query results. For example, group could be used with a Collection of Opportunity query results and they could be grouped by their Stage, sorted by their Names, and with total Amount included for each group:

CODE

<group var="oppsGrouped" value="${opportunities}" groupBy="${x.StageName}" orderBy="${x.Name}" sum="${x.Amount}">

The result of this command could then be used on the document to display the Opportunities in separate tables based on their Stage. Here's how that would work on a HTML document:

CODE

<table dyn-repeat="grouped" dyn-repeat-var="group"><thead><tr><th colspan="2">Stage: <span dyn-content="group.name">stage</span></th><th>Total: <span dyn-content="group.sum">total</span></th></tr></thead><tbody><tr dyn-repeat="group.items" dyn-repeat-var="item"><td><span dyn-content="item.Name">name</span></td><td><span dyn-content="item.Probability">prob</span></td><td><span dyn-content="item.Amount">amount</span></td></tr></tbody></table>