Default filters
All the filters described here are enabled by default in Python Liquid2.
abs
Return the absolute value of a number. Works on integers, floats and string representations of integers or floats.
Given a value that can't be cast to an integer or float, 0 will be returned.
append
Return the input value concatenated with the argument value.
If either the input value or argument are not a string, they will be coerced to a string before concatenation.
at_least
Return the maximum of the filter's input value and its argument. If either input value or argument are string representations of an integer or float, they will be cast to an integer or float prior to comparison.
If either input value or argument can not be cast to an integer or float, 0 will be used instead.
at_most
Return the minimum of the filter's input value and its argument. If either input value or argument are string representations of an integer or float, they will be cast to an integer or float prior to comparison.
If either input value or argument can not be cast to an integer or float, 0 will be used instead.
capitalize
Return the input string with the first character in upper case and the rest lowercase.
If the input value is not a string, it will be converted to a string.
ceil
Round the input value up to the nearest whole number. The input value will be converted to a number if it is not an integer or float.
If the input is undefined or can't be converted to a number, 0 is returned.
compact
Remove nil/null (or None in Python) values from an array-like object. If given, the argument should be the name of a property that exists on each item (hash, dict etc.) in the array-like sequence.
For example, ff pages is an array of objects, some of which have a category property:
{
"pages": [
{ "category": "business" },
{ "category": "celebrities" },
{},
{ "category": "lifestyle" },
{ "category": "sports" },
{},
{ "category": "technology" }
]
}
Without compact, iterating those categories will include nil/null values.
{% assign categories = pages | map: "category" -%}
{% for category in categories -%}
- {{ category }}
{%- endfor %}
With compact, we can remove those missing categories before the loop.
{% assign categories = pages | map: "category" | compact %}
{% for category in categories %}
- {{ category }}
{% endfor %}
Using the optional argument to compact, we could avoid using map and create an array of pages with a category property, rather than an array of categories.
{% assign pages_with_category = pages | compact: "category" %}
{% for page in pages_with_category %}
- {{ page.category }}
{% endfor %}
concat
Create a new array by joining one array-like object with another.
{% assign fruits = "apples, oranges, peaches" | split: ", " %}
{% assign vegetables = "carrots, turnips, potatoes" | split: ", " %}
{% assign everything = fruits | concat: vegetables %}
{% for item in everything %}
- {{ item }}
{% endfor %}
If the input value is not array-like, it will be converted to an array. No conversion is attempted for the argument value.
{% assign fruits = "apples, oranges, peaches" | split: ", " -%}
{% assign things = "hello" | concat: fruits -%}
{% for item in things -%}
- {{ item }}
{% endfor %}
Warning
Python Liquid2 treats strings as sequences, implicitly converting "hello" to ["h", "e", "l", "l", "o"] in this example. Whereas Shopify/Liquid would convert "hello" to ["hello"].
If the input is a nested array, it will be flattened before concatenation. The argument is not flattened.
currency
Currency (aka money) formatting. Return the input number formatted as currency for the current locale. See also money.
Use the group_separator argument to control the output of the current locale's group separators.
If the input number is a string, it will be parsed to a decimal according to the current input locale.
date
Format a date and/or time according the the given format string. The input can be a string, in which case the string will be parsed as a date/time before formatting.
Warning
Python Liquid uses dateutil for parsing strings to
datetimes, and strftime for formatting. There are likely to be some inconsistencies between this
and Ruby Liquid's Time.parse
equivalent parsing and formatting of dates and times.
In general, Python Liquid will raise an exception if the input value can not be converted to a date and/or time. Whereas Ruby Liquid will usually return something without erroring.
The special 'now' or 'today' input values can be used to get the current timestamp. 'today' is an alias for 'now'. Both include time information.
If the input is undefined, an empty string is returned.
datetime
Date and time formatting. Return the input datetime formatted according to the current locale. If dt is a datetime.datetime object datetime.datetime(2007, 4, 1, 15, 30).
The optional format argument can be one of 'short', 'medium', 'long', 'full' or a custom format string. format defaults to 'medium'.
If the input datetime is a string, it will be parsed to a datetime object.
{% with locale: 'en_GB' %}
{{ "Apr 1, 2007, 3:30:00 PM UTC+4" | datetime: format: 'short' }}
{% endwith %}
decimal
Decimal number formatting. Return the input number formatted as a decimal for the current locale.
Use the group_separator argument to control the output of the current locale's group separators.
If the input number is a string, it will be parsed to a decimal according to the current input locale.
default
Return a default value if the input is undefined, nil/null, false or empty, or return the input unchanged otherwise.
{{ product_price | default: 2.99 }}
{%- assign product_price = "" %}
{{ product_price | default: 2.99 }}
{%- assign product_price = 4.99 %}
{{ product_price | default: 2.99 }}
If the optional allow_false argument is true, an input of false will not return the default. allow_false defaults to false.
If no argument is given, the default value will be an empty string.
Empty strings, arrays and objects all cause the default value to be returned. 0 does not.
divided_by
Divide a number by another number. The result is rounded down to the nearest integer if the divisor is an integer.
If you divide by a float, the result will be a float.
If either the input or argument are not an integer or float, Liquid will try to convert them to an integer or float. If the input can't be converted, 0 will be used instead. If the argument can't be converted, an exception is raised.
downcase
Return the input string with all characters in lowercase.
If the input is not a string, Liquid will convert it to a string before forcing characters to lowercase.
If the input is undefined, an empty string is returned.
escape
Return the input string with characters &, < and > converted to HTML-safe sequences.
escape_once
Return the input string with characters &, < and > converted to HTML-safe sequences while preserving existing HTML escape sequences.
first
Return the first item of the input sequence. The input could be array-like or a mapping, but not a string.
If the input sequence is undefined, empty or not a sequence, nil is returned.
floor
Return the input down to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.
If the input can't be converted to a number, 0 is returned.
gettext
Return the localized translation of the input message without pluralization or message context.
Any keyword arguments are used to populate message variables. If user.name is "Sue":
join
Return the items in the input array as a single string, separated by the argument string. If the input is not an array, Liquid will convert it to one. If input array items are not strings, they will be converted to strings before joining.
If an argument string is not given, it defaults to a single space.
json
Return the input object serialized to a JSON (JavaScript Object Notation) string.
last
Return the last item in the array-like input.
If the input is undefined, empty, string or a number, nil will be returned.
lstrip
Return the input string with all leading whitespace removed. If the input is not a string, it will be converted to a string before stripping whitespace.
map
Extract properties from an array of objects into a new array.
For example, if pages is an array of objects with a category property:
{
"pages": [
{ "category": "business" },
{ "category": "celebrities" },
{ "category": "lifestyle" },
{ "category": "sports" },
{ "category": "technology" }
]
}
{% assign categories = pages | map: "category" -%}
{% for category in categories -%}
- {{ category }}
{%- endfor %}
minus
<number> | minus: <number>
```
Return the result of subtracting one number from another. If either the input or argument are not a number, Liquid will try to convert them to a number. If that conversion fails, `0` is used instead.
```liquid2
{{ 4 | minus: 2 }}
{{ "16" | minus: 4 }}
{{ 183.357 | minus: 12.2 }}
{{ "hello" | minus: 10 }}
modulo
Return the remainder from the division of the input by the argument.
If either the input or argument are not an integer or float, Liquid will try to convert them to an
integer or float. If the input can't be converted, 0 will be used instead. If the argument can't
be converted, an exception is raised.
money
money is an alias for currency.
money_with_currency
money_with_currency is an alias for currency with the default format set to "¤#,##0.00 ¤¤".
money_without_currency
money_without_currency is an alias for currency with the default format set to "#,##0.00¤".
money_without_trailing_zeros
money_without_trailing_zeros is an alias for currency with the default format set to "¤#,###" and currency_digits set to False.
newline_to_br
Return the input string with \n and \r\n replaced with <br />\n.
{% capture string_with_newlines %}
Hello
there
{% endcapture %}
{{ string_with_newlines | newline_to_br }}
ngettext
Return the localized translation of the input message with pluralization. The first positional argument is the plural form of the message. The second is a number used to determine if the singular or plural message should be used.
{% assign count = "Earth,Tatooine" | split: "," | size %}
{{ "Hello, World!" | ngetetxt: "Hello, Worlds!", count }}
Any keyword arguments are used to populate message variables. If user.name is "Sue" and count is 1:
npgettext
<string> | npgettext: <string>, <string>, <number> [, <identifier>: <object> ... ]
``
Return the localized translation of the input message with pluralization and a message context. The first positional argument is the message context string, the second is the plural form of the message, and the third is a number used to determine if the singular or plural message should be used.
```liquid2
{% assign count = "Earth,Tatooine" | split: "," | size %}
{{ "Hello, World!" | ngetetxt: "extra special greeting", "Hello, Worlds!", count }}
Any keyword arguments are used to populate message variables. If user.name is "Sue" and count is 1:
{{ "Hello, %(you)s" | ngetetxt: "extra special greeting", "Hello, everyone!", count, you: user.name }}
pgettext
Return the localized translation of the input message with additional message context. Message context is used to give translators extra information about where the messages is to be used.
Any keyword arguments are used to populate message variables. If user.name is "Sue":
plus
Return the result of adding one number to another. If either the input or argument are not a number, Liquid will try to convert them to a number. If that conversion fails, 0 is used instead.
prepend
Return the argument concatenated with the filter input.
If either the input value or argument are not a string, they will be coerced to a string before concatenation.
remove
Return the input with all occurrences of the argument string removed.
If either the filter input or argument are not a string, they will be coerced to a string before substring removal.
remove_first
Return a copy of the input string with the first occurrence of the argument string removed.
If either the filter input or argument are not a string, they will be coerced to a string before substring removal.
remove_last
Return a copy of the input string with the last occurrence of the argument string removed.
If either the filter input or argument are not a string, they will be coerced to a string before substring removal.
replace
Return the input with all occurrences of the first argument replaced with the second argument. If
the second argument is omitted, it will default to an empty string, making replace behave like
remove.
If either the filter input or argument are not a string, they will be coerced to a string before replacement.
replace_first
Return a copy of the input string with the first occurrence of the first argument replaced with the second argument. If the second argument is omitted, it will default to an empty string, making replace_first behave like remove_first.
If either the filter input or argument are not a string, they will be coerced to a string before replacement.
replace_last
Return a copy of the input string with the last occurrence of the first argument replaced with the second argument.
If either the filter input or argument are not a string, they will be coerced to a string before replacement.
reverse
Return a copy of the input array with the items in reverse order. If the filter input is a string, reverse will return the string unchanged.
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " -%}
{{ my_array | reverse | join: ", " }}
round
Return the input number rounded to the given number of decimal places. The number of digits defaults to 0.
If either the filter input or its optional argument are not an integer or float, they will be converted to an integer or float before rounding.
rstrip
Return the input string with all trailing whitespace removed. If the input is not a string, it will be converted to a string before stripping whitespace.
safe
Return the input string marked as safe to use in an HTML or XML document. If the filter input is not a string, it will be converted to an HTML-safe string.
With auto-escape enabled and the following global variables:
<p></p><script>alert("XSS!");</script>, Sally</p>
<p></p><script>alert('XSS!');</script>, Sally</p>
size
Return the size of the input object. Works on strings, arrays and hashes.
{{ "Ground control to Major Tom." | size }}
{{ "apples, oranges, peaches, plums" | split: ", " | size }}
slice
Return a substring or subsequence of the input string or array. The first argument is the zero-based start index. The second, optional argument is the length of the substring or sequence, which defaults to 1.
{{ "Liquid" | slice: 0 }}
{{ "Liquid" | slice: 2 }}
{{ "Liquid" | slice: 2, 5 }}
{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
{{ beatles | slice: 1, 2 | join: " " }}
If the first argument is negative, the start index is counted from the end of the sequence.
{{ "Liquid" | slice: -3 }}
{{ "Liquid" | slice: -3, 2 }}
{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
{{ beatles | slice: -2, 2 | join: " " }}
sort
<array> | sort[: <string>]
``
Return a copy of the input array with its elements sorted.
```liquid
{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " -%}
{{ my_array | sort | join: ", " }}
The optional argument is a sort key. If given, it should be the name of a property and the filter's input should be an array of objects.
{
"collection": {
"products": [
{ "title": "A Shoe", "price": "9.95" },
{ "title": "A Tie", "price": "0.50" },
{ "title": "A Hat", "price": "2.50" }
]
}
}
{% assign products_by_price = collection.products | sort: "price" -%}
{% for product in products_by_price %}
<h4>{{ product.title }}</h4>
{% endfor %}
sort_natural
Return a copy of the input array with its elements sorted case-insensitively. Array items will be compared by their string representations, forced to lowercase.
{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " -%}
{{ my_array | sort_natural | join: ", " }}
The optional argument is a sort key. If given, it should be the name of a property and the filter's input should be an array of objects. Array elements are compared using the lowercase string representation of that property.
{
"collection": {
"products": [
{ "title": "A Shoe", "company": "Cool Shoes" },
{ "title": "A Tie", "company": "alpha Ties" },
{ "title": "A Hat", "company": "Beta Hats" }
]
}
}
{% assign products_by_company = collection.products | sort_natural: "company" %}
{% for product in products_by_company %}
<h4>{{ product.title }}</h4>
{% endfor %}
sort_numeric
Return a new array/list with items from the input sequence sorted by any integers and/or floats found in the string representation of each item. Note the difference between sort_numeric and sort in this example.
{% assign foo = '1.2.1, v1.10.0, v1.1.0, v1.2.2' | split: ', ' -%}
{{ foo | sort_numeric | join: ', ' }}
{{ foo | sort | join: ', ' }}
{% assign bar = '107, 12, 0001' | split: ', ' -%}
{{ bar | sort_numeric | join: ', ' }}
{{ bar | sort | join: ', ' }}
The optional string argument is the name of a key/property to use as the sort key. In which case each item in the input sequence should be a dict/hash/mapping, each with said key/property.
sort_numeric will work as expected when given arrays/lists/tuples of integers, floats and/or Decimals, but will be slower than using standard sort.
If an input sequence contains strings (or arbitrary objects that get stringified) that do not have numeric characters, they will be pushed to the end of the resulting list, probably in the same order as in the input sequence.
split
Return an array of strings that are the input string split on the filter's argument string.
{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
{% for member in beatles %}
{{- member }}
{% endfor %}
If the argument is undefined or an empty string, the input will be split at every character.
strip
Return the input string with all leading and trailing whitespace removed. If the input is not a string, it will be converted to a string before stripping whitespace.
strip_html
Return the input string with all HTML tags removed.
strip_newlines
Return the input string with \n and \r\n removed.
{% capture string_with_newlines %}
Hello
there
{% endcapture -%}
{{ string_with_newlines | strip_newlines }}
sum
Return the sum of all numeric elements in an array.
If the optional string argument is given, it is assumed that array items are hash/dict/mapping-like, and the argument should be the name of a property/key. The values at array[property] will be summed.
t
Return the localized translation of the input message. For example, if a German Translations object is found in the current render context:
If given, the first and only positional argument is a message context string. It will be used to give translators extra information about where the message is to be used. With the default configuration, keyword arguments plural and count are reserved for specifying a pluralizable message.
The remaining keyword arguments are used to populate translatable message variables. If user.name is "Sue":
times
Return the product of the input number and the argument. If either the input or argument are not a number, Liquid will try to convert them to a number. If that conversion fails, 0 is used instead.
truncate
Return a truncated version of the input string. The first argument, length, defaults to 50. The second argument defaults to an ellipsis (...).
If the length of the input string is less than the given length (first argument), the input string will be truncated to length minus the length of the second argument, with the second argument appended.
{{ "Ground control to Major Tom." | truncate: 20 }}
{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}
{{ "Ground control to Major Tom." | truncate: 20, "" }}
truncatewords
Return the input string truncated to the specified number of words, with the second argument appended. The number of words (first argument) defaults to 15. The second argument defaults to an ellipsis (...).
If the input string already has fewer than the given number of words, it is returned unchanged.
{{ "Ground control to Major Tom." | truncatewords: 3 }}
{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}
{{ "Ground control to Major Tom." | truncatewords: 3, "" }}
uniq
Return a copy of the input array with duplicate elements removed.
{% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " -%}
{{ my_array | uniq | join: ", " }}
If an argument is given, it should be the name of a property and the filter's input should be an array of objects.
{
"collection": {
"products": [
{ "title": "A Shoe", "company": "Cool Shoes" },
{ "title": "A Tie", "company": "alpha Ties" },
{ "title": "Another Tie", "company": "alpha Ties" },
{ "title": "A Hat", "company": "Beta Hats" }
]
}
}
{% assign one_product_from_each_company = collections.products | uniq: "company" -%}
{% for product in one_product_from_each_company -%}
- product.title
{% endfor %}
unit
<number> | unit: <string>
[, denominator: <number>]
[, denominator_unit: <string>]
[, length: <string>]
[, format: <string>]
Return the input number formatted with the given units according to the current locale. The first, required positional argument is a CLDR measurement unit code.
length
length can be one of "short", "long" or "narrow", defaulting to "long".
{{ 12 | unit: 'length-meter' }}
{{ 12 | unit: 'length-meter', length: 'short' }}
{{ 12 | unit: 'length-meter', length: 'long' }}
{{ 12 | unit: 'length-meter', length: 'narrow' }}
Or, if the current locale is set to fr.
{% with locale:"fr" %}
{{ 12 | unit: 'length-meter' }}
{{ 12 | unit: 'length-meter', length: 'short' }}
{{ 12 | unit: 'length-meter', length: 'long' }}
{{ 12 | unit: 'length-meter', length: 'narrow' }}
{% endwith %}
format
format is an optional decimal format string, described in the Locale Data Markup Language specification (LDML).
Compound Units
If a denominator and/or denominator_unit is given, the value will be formatted as a compound unit.
{{ 150 | unit: 'kilowatt', denominator_unit: 'hour' }}
{{ 32.5 | unit: 'ton', denominator: 15, denominator_unit: 'hour' }}
Or, if the current locale is set to fi.
{% with locale:"fi" %}
{{ 150 | unit: 'kilowatt', denominator_unit: 'hour' }}
{{ 32.5 | unit: 'ton', denominator: 15, denominator_unit: 'hour' }}
{% endwith %}
upcase
Return the input string with all characters in uppercase.
url_decode
Return the input string with %xx escapes replaced with their single-character equivalents. Also replaces '+' with ' '.
url_encode
Return the input string with URL reserved characters %-escaped. Also replaces ' ' with '+'.
where
Return a copy of the input array including only those objects that have a property, named with the first argument, equal to a value, given as the second argument. If a second argument is not given, only elements with the named property that are truthy will be included.
{
"products": [
{ "title": "Vacuum", "type": "house", "available": true },
{ "title": "Spatula", "type": "kitchen", "available": false },
{ "title": "Television", "type": "lounge", "available": true },
{ "title": "Garlic press", "type": "kitchen", "available": true }
]
}
All products:
{% for product in products -%}
- {{ product.title }}
{% endfor %}
{%- assign kitchen_products = products | where: "type", "kitchen" -%}
Kitchen products:
{% for product in kitchen_products -%}
- {{ product.title }}
{% endfor %}
{%- assign available_products = products | where: "available" -%}
Available products:
{% for product in available_products -%}
- {{ product.title }}
{% endfor %}