{expand-on}
Plugin: Reporting Plugin, from version 1.0 until version 3.0.0
This macro will tell the reporter to expand its list of items to include an item for each value in a sub-item, specified by the 'prefix:key' value.
Description
 | Please Note! As of Reporting 3.0.0, this macro no longer exists. Please update your reports to use the expanding-reporter instead. An example of converting your reports is on that page. |
In database query terms, this is essentially a 'join' operation, and is mostly useful for many-to-many relationships.
For example, a user can be a member of many groups, and each group can have many users as members. If you wish to display a list of all groups and their members in a single table, with only one group and one user listed per row, you need to expand on one or the other. You will end up with both being repeated multiple times, but such is the nature of the relationship. Have a look at the examples below for more details.
Usage
{expand-on:prefix:key|as=something}
{xxx-sort:item:key|order=[ascending, descending]}
{xxx-filter:item:key|extra parameters go here}
{expand-on}
Parameters
| Name | Required | Default | Description |
|---|---|---|---|
| [default]/key |  | The key value to expand on. | |
| as | | The name to set each expanded item as when accessing it in the report. May not be 'item', as this is reserved for the original item being expanded. | |
| matchAll |  | true
| If set to 'false', content matching any of the criteria will be returned. Otherwise, the content must match all criteria. |
Examples
Display a user/group table
Using the user-group-reporter it would look something like this:
{user-group-reporter}
{text-sort:user-group:name}
{expand-on:user-group:members|as=member}
{text-sort:user:name}
{expand-on}
{user-group-reporter}
You would then display your results by doing something like this (inside a report-table of course):
{report-column:title=Group Name}{report-info:expanded:item > name}{report-column}
{report-column:title=Username}{report-info:expanded:member > name}{report-column}
{report-column:title=Email}{report-info:expanded:member > email|link=true}{report-column}
Note the use of 'expanded:item' and 'expanded:member'. 'expanded:item' always refers to the original item being expanded on, in this case the user group. 'expanded:member' is used because the original {expand-on} macro declared that each of the items in 'user-group:members' would be known as 'member'.
Note also that you can specify sort order inside the {expand-on} macro. You can also add any filters you wish to, and they will only apply to the items being expanded on.
Discussions