List Filters

Use list filters to create, manipulate, and display lists.

compact

Removes all null, empty, and invalid (is_valid == false, empty lists, etc..) objects from the list.

concat

list other

Adds all of the items from the other list onto the end of the current list. If either the current object or other is null, they will be treated as an empty list, and if either of them is not a list, they will be treated as a list with a single object.

{% var ab = "a" | concat:"b" %}

["a", "b"]

first

Returns the first item in the current list.

"a"

group_by

string property

Groups the list by the given property and returns the results as a list of objects. Each object in the result set has a Key property which is the value that they are grouped by and a Value property which is the list of objects that have the matching Key property. Any objects in the list that do not have the given property will be in a result with a null Key.

{% blog_posts posts = limit: 40 start: 1 sort_by: 'date_posted' sort_direction: 'desc' %}
{% var grouped_by_blog = posts | group_by: 'blog' %}
{% for group in grouped_by_blog %}
{{ group.Key.title }}: {{ group.Value | size }}
{% endfor %}

General Blog: 22
Announcements: 10
Events: 8

index

object find number start = -1

Returns the 0-based index of the find object in the current list, or -1 if it cannot be found. If start is greater than 0, the search will begin at the specified index.

{% var ab = "a" | concat: "b" %}
{{ ab | index: "a" }}    0
{{ ab | index: "b" }}    1
{{ ab | index: "c" }}    -1

join

string glue = " "

Returns a string with each element from the list joined together with the glue string between elements.

{{ "The" | concat: "quick" | concat: "brown" | concat: "fox" | join: " " }}

"The quick brown fox"

last

Returns the last item in the current list

"b"

last_index

object find number start = -1 boolean ignorecase = false

Returns the last 0-based index of the find object in the current list, or -1 if it cannot be found. If start is greater than 0, the search will begin at the specified index. If the object is a string and ignorecase is true then capitalization will be ignored (note the same does not apply for lists of strings).

{% var list = "a" | concat: "b" | concat: "a" %}
{{ list | last_index: "a" }}    2
{{ list | last_index: "a", 1 }}    0
{{ list | last_index: "B" }}    -1
{{ list | last_index: "B", -1, true }}    1

map

string property

Return a new list with the given property from every object in the original list.

{% blog_posts posts = limit: 10 sort_by 'post_date' sort_direction:'desc' %}
{{ posts | map: 'title' | join: ' ' }}

reverse

Reverses the order of the list. This may also be used to reverse a string

{% blog_posts posts = limit: 10 sort_by 'post_date' sort_direction:'desc' %}
{% set posts = posts | reverse %}

posts are now in reverse order. It is also now a generic "list" instead of "blog_posts" so the original properties of "blog_posts" are no longer available (eg: total_count).

size

Return the size of the current list

slice

integer start integer len = 0

Return a portion of the current list. If start is negative, will return len items from the end of the list. If len is 0, will return all remaining characters after start. If len is negative, will return up to len items from the end of the list. This filter may also be used on strings to return a portion of the current string.

{{ "alphacentauri" | slice: 5 }}    centauri
{{ "alphacentauri" | slice: 0, 5 }}    alpha
{{ "alphacentauri" | slice: 5, 7 }}    centaur
{{ "alphacentauri" | slice: -8 }}    centauri
{{ "alphacentauri" | slice: -8, 4 }}    cent

sort

string property = null

Sort objects in a list. If theproperty is specified, use it to sort objects in the list by. Use the special string value "random" to sort the list in a random order - which is functionally identicial to using the shuffle filter.

{% var sorted = "a" | concat: "c" | concat: "b" | sort %}

["a", "b", "c"]

{% var sorted = houses | sort: 'number_of_rooms' %}

shuffle

boolean preventCache = true

Sorts the list randomly. Unless preventCache is false, the shuffle filter will prevent the page from being fast-cached.

{% articles items = limit: 10 start: 1 %}
{{ set items = items | shuffle }}

uniq

string property = null

Remove all duplicate objects in the list. If property is specified, objects are considered duplicate if their property value is the same.

{% var arr = "a" | concat: "b" | concat: "b"] | uniq %}

["a", "b"]

{% blog_posts posts = start: 1 limit: 10 %}
{% set posts = posts | uniq: "blog" %}

where

string property string value

Returns a new list which only contains items where the given property has the given string value

{% var arr = existing_list | where: 'position', 'top' %}

where_exp

string name string expression

Returns a new list which only contains items that match the given expression when the item is referenced as name.

{% var with_rooms = houses | where_exp: 'house', 'house.rooms.value >= 2' %}

Additional Examples

Getting and manipulating entity lists

1) Get two lists:
    {% datastore_items var featured_houses = datastore:"houses" query:"is_featured = true" %}
    {% datastore_items var houses_by_folder = datastore:"houses" folder:entity.folder %}
2) Concatenate and uniq the easy way:
    {% datastore_items var houses = featured_houses houses_by_folder unique %}
3) Concatenate manually:
    {% var houses = featured_houses | concat: houses_by_folder %}
4) Unique manually:
    {% var houses = houses | uniq %}
6) Get one random item from the list:
    {% var random_house = houses | rand %}
7) Sort the full list randomly:
    {% set houses = houses | shuffle %}
8) Various ways to query and slice:
    {% var one_rooms = houses | where: "rooms", "1" | sort: "price" %}
    {% var cheapest = one_rooms | first %}
    {% var mid_houses = one_rooms | slice: 1, 6 %}
    {% var expensive_houses = one_rooms | slice: 7 %}
    {% var num_expensive_houses = expensive_houses | size %}
9) Advanced query:
    {% var few_rooms = houses | where_exp: "house", "house.rooms.value < 3" %}
10) Grouping:
    {% var grouped_by_rooms = houses | group_by: "rooms" | sort: "Key" %}
    {% for list in grouped_by_rooms %}
        <p>{{list.Key | default: "Unknown"}} Rooms ({{list.Value | size }} houses)</p>
    {% endfor %}
11) Mapping and Compact:
    {% var mapped_by_rooms = grouped_by_rooms | map: "Value" %}
    {% for list in mapped_by_rooms %}
        <h4>{{list[0].rooms | default: "Unknown"}} Rooms</h4>
        <ul>
            <li>{{list | map: "description" | compact | join: "</li><li>" }}</li>
        </ul>
    {% endfor %}