Filters

Liquid Filters

Filters may be used to modify the output of objects before either being stored in a variable or output to the page. Filters should be used as "objectName | filter_name:filterParams" (eg: {{ request.date | date: "MMM dd, YYYY" }}, or {% assign end_date = request.date | add_weeks:1 %}).

Multiple filters may be applied to an object at the same time and are processed in the same order that they appear in the markup. Eg: {% assign my_date = request.date | midnight | add_hours:3 %} will result in a different date than {% assign my_date = request.date | add_hours:3 | midnight %}

Debugging

inspect int maxDepth = 10 true/false forceLoad = false
Returns a json-like representation of the current object up to maxDepth layers deep (max 10). Will not load new information from the server unless forceLoad is set to true. Useful during template development and debugging, but do not rely on the result of the inspect tag for your live site:{{entity.what_is_this | inspect: 5}}{{variable | inspect: 3, true}}

String Filters

Use string filters to manipulate strings.

append: String text
Add text to the end of the current string
capitalize
Capitalize words in a string
classname String separator = "-"
Removes all non-alphanumeric characters other than dashes and underscores from a string and replaces them with the separator (or nothing if the separator is empty).
default: String default_value
If the current value is empty, return the default_value instead. Otherwise return the original value.
downcase
Convert a string to lowercase
escape
Encode a string to be output as HTML. All special HTML characters will be converted to their equivalent HTML character entities (eg: < becomes &lt;)
h
Alias for escape
newline_to_br
Add "<br >" tags in front of all newlines in the current string
plus: string text
Appends the text to the current value. Note that this filter behaves differently if the current value is not a string (eg: {{'Some' | plus:'Thing'}} = 'SomeThing', but {{4 | plus:2}} = 6).
prepend: String text
Add text to the beginning of the current string
remove: String search
Remove all occurrences of search from the current string
remove_first: String search
Remove the first occurrence of search from the current string
replace: String search String replacement = ""
Replace all occurrences of search inside the current string with replacement.
replace_regex: String pattern String replacement = ""
Replace all occurrences of pattern inside the current string with replacement using a regular expression - making it possible to search for more complicated expressions and replace using the resulting matching groups.
replace_first: String search String replacement = "" int numReplacements = 1
Replace the first numReplacements occurrences of search inside the current string with replacement.
replace_regex_first: String pattern String replacement = "" int numReplacements = 1
Replace the first numReplacements occurrences of pattern inside the current string with replacement using a regular expression - similar to the replace_regex filter.
size
Return the size of the current string
slice: int start int len = 0
Return a part of the current string. If start is negative, will return len characters 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.
split: String pattern
Split a string into a list of substrings separated by the given pattern
strip
Removes whitespace from the beginning and end of a string
strip_html
Removes all HTML tags from a string
strip_newlines
Removes all newlines from a string
times: int count
Repeats the current value count times. This filter behaves differently if the current value is a string or if count is not an integer (eg: {{'Bon' | times:2}} = 'BonBon', but {{4 | times:2}} = 8).
truncate: int length = 50 String truncate_string = "..."
Truncates a string down to length characters. If the original string is longer than length characters, appends truncate_string to the end of the truncated string.
truncate_words: int length = 50 String truncate_string = "..."
Truncates a string down to length words. If the original string is longer than length words, appends truncate_string to the end of the truncated string.
upcase
Convert a string to uppercase
url_decode: boolean formData = false
Decode a UrlEncoded string. If formData is true, decodes the string as if it were submitted as part of an html form (eg: decodes the + character to a space character). If formData is false, decodes the string as a normal url_encoded string (eg: leaves the + character alone).
url_encode boolean formData = false
Encode a string to be used in a URL. If formData is true, encodes the string as if it were submitted as part of an html form (eg: encodes the space character to the + character). If formData is false, encodes the string as a normal url string (eg: encodes the space character as %20).

Number Filters

Use number filters to convert, manipulate, and display numbers.

 

abs
Returns the absolute value of a number.
at_least number
Limits a number to a minimum value
at_most number
Limits a number to a maximum value
ceil: integer
Returns the next integer value greater than or equal to the current value.
divided_by: object operand
Divide the current value by operand.
floor: integer
Returns the next integer value less than or equal to the current value.
minus: object operand
Subtracts the operand from the current value.
modulo: object operand
Return the remainder of the current value when divided by the operand.
plus: object operand
Adds the operand to the current value. Note that this filter behaves differently if the current value is a string (eg: {{4 | plus:2}} = 6, but {{'Some' | plus:'Thing'}} = 'SomeThing').
rand
Returns a random integer between 0 and the current integer.
round: integer places  = 0
Rounds a decimal value to the specified number of places.
times: object operand
Multiply the current value by the operand. Note that this filter behaves differently if the current value is a string and the operand is an integer (eg: {{4 | times:2}} = 8, but {{'Bon' | times:2}} = 'BonBon').
to_int
Converts the input into an integer. Useful when grabbing query parameters or other string inputs.
to_number
Converts the input into a number, which could be an integer or a fractional number.

 

Date Filters

Use date filters to convert, manipulate, and display dates.

 

add_days: int operand
Return a date object operand days in the future. If operand is negative, return a date that many days in the past.
add_hours: int operand
Return a date object operand hours in the future. If operand is negative, return a date that many hours in the past.
add_minutes: int operand
Return a date object operand minutes in the future. If operand is negative, return a date that many minutes in the past.
add_months: int operand
Return a date object operand months in the future. If operand is negative, return a date that many months in the past.
add_weeks: int operand
Return a date object operand weeks in the future. If operand is negative, return a date that many weeks in the past.
add_years: int operand
Return a date object operand years in the future. If operand is negative, return a date that many years in the past.
date: String format (optional)
Returns the current value as a date. If format is specified, converts the date to a string before returning it using the given format. format must be a valid .NET date format.
midnight
Return the date representing midnight for the current value
time_diff: date other String format (optional)
If format is unspecified, returns a time_diff object describing the difference between the current date and the other date. If format is specified, converts the time difference to a string before returning it using the given format. format must be a valid .NET TimeSpan format.
timezone: bool full = false
Returns the timezone that the date is in. If full is true, returns the full timezone identifier (eg: "Europe/Rome"). If full is false (default) or not specified, returns the abbreviated timezone name (eg: "CET").
to_timezone: String timezone
Converts the current date to the specified timezone (eg: "America/Indianapolis")

 

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: 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.
first
Returns the first item in the current list.
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.
join: string glue = " "
Join the elements of a list into a single string with the glue string between each element.
last
Returns the last item in the current list
map: String property
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: int start int len = 0
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: String property (optional)
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.
uniq: String property
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.
where: string property string value
Returns a new list which only contains items where the given property has the given value
where_exp: string name string condition
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 %}

 

Security Filters

Use security filters to encrypt and decrypt strings.

 

decrypt_aes: String secret String salt (optional)
Returns the unencrypted value of the input using a shared secret and optional salt. If no salt is provided, a default salt value is used.
encrypt_aes: String secret String salt (optional)
Returns an encrypted value of the input using a shared secret and optional salt. If no salt is provided, a default salt value is used.

Note: Particularly for code that may be re-used across multiple sites, it is recommended to store your secrets in a site setting where it can quickly and easily be updated.

Examples

{% var some_secret_string = entity.secret.value | encrypt_aes: site.shared_secret.value %}
{% var shouldEqualOriginalValue = some_secret_string | decrypt_aes: site.shared_secret.value %}
{% capture salt %}{{ entity.guid }}{{ entity.name.value }}{% endcapture %}
{% set salt = salt | url_encode %}
{% assign some_secret_string = entity.secret.value | encrypt_aes: site.shared_secret.value, salt %}
{% assign some_decoded_string = request.query_params.encrypted_data | decrypt_aes: site.shared_secret.value, salt %}