List Filters

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.

Example: make a list of two strings

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

first

Returns the first item in the current list.

Example: get the first item from a list

{{ "a" | concat:"b" | first }}
"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.

Example: group blog posts by blog

{% 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 %}
    <p>{{ group.Key.title }}: {{ group.Value | size }}</p>
{% endfor %}

<p>General Blog: 22</p>
<p>Announcements: 10</p>
<p>Events: 8</p>

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.

Example: find something in a list

{% 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.

Example: join strings together

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

last

Returns the last item in the current list

Example: get the last item in a list

{{ "a" | concat: "b" | last }}
"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).

Example: find the last occurence of an item in a list

{% 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.

Example: output blog post titles

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

reverse

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

Example: reverse the order of blog posts

{% 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

Example: get the size of a generic list

{{ "a" | concat:"b" | size }}
2

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.

Example: Get a portion of a 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.

Example: Sort strings

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

Example: Sort list by custom property

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

shuffle

Sorts the list randomly.

Example: reorder articles randomly

{% 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.

Example: Unique array of strings

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

Example: Limit blog posts to 1 per blog

{% 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

Example: Get list of items with 'position': 'top'

{% 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.

Example: Reduce list of houses to houses with 2 or more rooms

{% 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 %}