List Filters

List Filters

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

compact

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

concat

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.

concat: list other

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

first

Returns the first item in the current list.

first

{{ ["a", "b"] | first }}
"a"

group_by

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.

index

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.

join

Join the elements of a list into a single string with the glue string between each element.

join: string glue = " "

{{ "The", "quick", "brown", "fox" | " " }}
"The quick brown fox"

last

Returns the last item in the current list

last

{{ ["a", "b"] | last }}
"b"

last_index

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.

map

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

rand

Returns a random item from the current list.

reverse

Reverses the order of the list

size

Return the size of the current list

slice

Return a portion of the current list. If start is negative, will return len items from the end of the string. If len is 0, will return all remaining characters after start. If len is negative, will return up to len characters from the end of the string.

sort

Sort objects in a list. If the property parameter is included, use it to sort objects in the list by. Use the special string value "random" to sort the list in a random order.

sort: String property (optional)

{{ ["a", "c", "b"] | sort }}
["a", "b", "c"]

uniq

Remove all duplicate objects in the list. If the property parameter is included, objects are considered duplicate if their property value is the same. Note: two objects may be identical but not be duplicates - such as the same article referenced from two different locations. If you want to ensure that objects pulled from Marketpath CMS are unique you need to uniq it by the guid property.

uniq: String property

{{ ["a", "b", "b"] | uniq }}
["a", "b"]

where

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

where_exp

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

Examples

2 methods to use strings as lists to generate a random string

Note 1: the rand and random functions should NOT be considered cryptographically secure - do not use if you are considering them for cases where this is a requirement.

Note 2: generating a random string will prevent the page from being fast-cached. You should only rely on random strings if other methods will not work.

1) Pseudo-random string with no duplicate characters
    {% var stringLength = 12 %}
    {% var sourceChars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890' %}
    {% var randomstring = sourceChars | sort:'random' | slice:0, stringLength | join: '' %}
2) Pseudo-random string with duplicate characters
    {% capture randomString -%}
        {%- for i in (1..stringLength) -%}
            {{- sourceChars | rand -}}
        {%- endfor -%}
    {%- endcapture -%}

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) This will NOT remove duplicates:
    {% var houses = houses | uniq %}
5) This WILL remove duplicates:
    {% var houses = houses | uniq:'guid' %}
6) Get one random item from the list:
    {% var random_house = houses | rand %}
7) Sort the full list randomly:
    {% set houses = houses | sort:'random' %}
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 %}