Overview
You may use this modifier to group items (a simple array, a collection of entries, etc) into groups
based on some common value.
By Key
The most basic usage example would be to take a simple array and output the groups using the key.
sponsors: - sport: basketball team: Jazz - sport: baseball team: Yankees - sport: basketball team: Bulls
{{ sponsors | group_by('sport') }} <h1>Basketball</h2> {{ basketball }} {{ team }} {{ /basketball }} <h1>Baseball</h2> {{ baseball }} {{ team }} {{ /baseball }}{{ /sponsors }}
<h1>Basketball</h1>JazzBulls <h1>Baseball</h1>Yankees
Looping Over Groups
In the previous example, you had to know that there was going to be basketball
and baseball
keys ahead of time.
If you don't know the groups, you can loop over the groups
variable.
It will be an array containing the name of the group
and its items
.
{{ sponsors group_by="sport" }} {{ groups }} <h1>{{ group | upper }}</h1> {{ items }} {{ team }} {{ /items }} {{ /groups }}{{ /sponsors }}
Nested Values
If you need to get a nested value for the groups, you can use the familiar colon syntax.
For example, you may have an entries
field where you've selected entries from multiple collections, and you want to group by the collection's title.
menu_items: - burger - fries - coke - pepsi
{{ menu_items group_by="collection:title" }} {{ groups }} <h2>{{ group }}</h2> {{ items }} {{ title }} {{ /items }} {{ /groups }}{{ /menu_items }}
<h2>Food</h2>BurgerFries <h2>Drinks</h2>CokePepsi
Dates
You may group entries by a date field.
For example, you might want to output articles and group them by month.
Here we'll group them by the date
field using the F Y
PHP date format which
would output as "Month Year".
{{ collection:articles as="entries" }} {{ entries group_by="date|F Y" }} {{ groups }} <h1>{{ group }}</h1> {{ items }} {{ title }} {{ /items }} {{ /groups }} {{ /entries }}{{ /collection:articles }}
<h1>September 2021</h1>Entry from SeptemberAnother entry from September <h1>October 2021</h1>Entry from October
The date field in this example is named date
, but you can use any date field.
{{ entries group_by="custom_date_field|F Y" }}
If you need the key to differ from how it's displayed (perhaps you want to use an additional modifier after), you can pass another date format as the
third argument. (Argument 2 creates the key, argument 3 creates the {{ group }}
text).
{{ entries group_by="date|Y-m|F Y" }}