Liquid filters

Liquid language includes a filters feature, where each filter is used to modify a merge tag’s number, string, or object value.

Ortto supports the use of most Liquid filters, as detailed in the Supported Liquid filters table.

You can also learn more about Liquid syntax filters in the Filters section of the Liquid template language site, which begins with the abs filter.

Some filters can be strung together to further modify your merge tag’s value. In such cases, each filter is separated by a pipe (|) character.

Exceptions for using Liquid syntax

While Ortto supports the use of Liquid template language syntax for merge tags, this section lists filters that are:

  • not readily accessible through the Insert merge tag feature, or

  • are commonly used but have exceptions.

default

When adding a merge tag, many allow you to specify a default value, which is the fallback value used when the merge tag itself returns no value.

Built-in person field example
{{ people.total-spent | decimal: 'two', '$' | default: '0' }}

represents a person’s Total spent dollar amount to two decimal places, which displays $0.00 if this merge key has no value yet.

Non-conventional default filters

When determining the Liquid syntax for some merge tags, the default filter may be different and/or might be combined with the functionality of other filters.

Built-in phone number field example
{{ people.phone-number | hideCountryCodeAndDefault: false, '' }}

In this case, the default is combined with the functionality of another custom filter. With this example, this merge tag ensures that the phone number’s country is displayed, and no default value is specified.

numberWithDelimiter

When adding a merge tag that displays a whole or decimal number, you can add the numberWithDelimiter filter to break up large numbers by 3 digit delimiters with the following syntax:

{{ people.custom.int | numberWithDelimiter: 'en', 'whole'}}

The numberWithDelimiter filter takes two values:

  • The first value specifies the two-letter country identifier that defines the type of delimiter used - e.g. a comma (,) or a period (.). Four-letter locale identifiers are also supported - e.g. en-us, en-gb, etc.
    Learn more about what country and locale identifiers are supported in the JavaScript: Language Tags (BCP 47) post.

  • The second value specifies if the number is a whole (integer) or one- or two-decimal (real) number. For decimal numbers, specify the value one or two accordingly.

In the example above, if people.custom.int's value was 1000000, then this numberWithDelimiter filter would display this value as 1,000,000.

rawPhone

When adding a merge tag that displays a phone number, should you wish to output a person’s (contact’s) actual phone number value, use rawPhone.

{{ people.salesforce_contact.contact-mobile-phone | rawPhone }}

In the example above, rawPhone will output the mobile phone number value for the Salesforce contact. This can be helpful where there is a difference in how Ortto parses phone numbers compared to the integrated data source.

Tags

If you wish to see whether a person matches a tag in your account, you need to identify the tag using Ortto’s custom filters:

  • setContains to see if a person matches at least one of the specified tags, or

  • setContainsAll to see if a person matches all of the specified tags

and the name of the tag/s you wish to filter by. You can add as many parameters (tags) as required.

{{ people.tag | setContains: 'Nurture', 'Opportunity'}}

The filters will output a boolean (true or false) result for your query.

  • Any tags you specify need to match the case they are saved as in your account. For example, a tag named Nurture with an uppercase N, needs to be specified verbatim: {{ people.tag | setContains: 'Nurture' }}.

  • Due to the way Ortto stores tags, you must use the abovelisted syntax, not: {{ people.tag | contains 'TagName' }}.

Supported Liquid filters

The table below lists the Liquid filters that Ortto currently support.

As filters are generally used to modify an output, most need to be contained in double curly braces.

Filters can be used to ensure your message content displays as you intend it to, such as ensuring recipient’s names are capitalized in the message greeting by writing your greeting as Hi, {{ people.first-name | capitalize }} to produce a result like Hi, Jerry.

Some filters will be used with variable tags to achieve the output, such as join, where the variable name you declare will be contained in double curly braces (to determine the output) rather than the filter.

When declaring a variable in Ortto using a Liquid variable tag, you must begin the variable name with var so that Ortto can recognize it as a declared variable. Learn more about variable tags under Variable tags.
Filter Description

abs

Returns the absolute value of a number. For example, {{ -12.68 | abs }} will output 12.68.

append

Adds the specified string or merge tag to the end of another string or merge tag with no spaces. For example, {{ people.first-name | append: "@email.com" }} will output the recipient’s first name and the specified string, such as lauren@email.com.

at_least

Limits a number to the minimum value you specify. For example {{ 4 | at_least: 5 }} will output 5.

at_most

Limits a number to the maximum value you specify. For example {{ 4 | at_most: 3 }} will output 3.

capitalize

Makes only the first character of a string capitalized (the remaining characters are lowercase). You could use this to ensure that your email greetings output the recipient’s first name with a capital letter, in case it has been entered into your CDP as lowercase. For example, where a person’s first name is jerry in the CDP, {{ people.first-name | capitalize }} will output Jerry.

ceil

Rounds an input up to the nearest whole number. For example, {{ 1.8 | ceil }} will output 2.

compact

Removes the nil values from any an array. For example, if you want to output an array of items in your store and map those items by their category attribute, any items without a category attribute (a nil value) will not appear in the output.

date

Converts a timestamp into another date format. Use the strftime syntax, e.g. {{ article.published_at | date: "%Y" }} to output 2022, but %y for 22.

default

Sets a default value for any variable with no assigned value. Learn more about default under Default.

divided_by

Divides a number by another number. The result is rounded down to the nearest integer if the divisor is an integer. Or, if you divide by a float (a number with a decimal in it), the result will be a float. For example, {{ 50 | divided_by: 1.5 }} will output 33.333333333333336.

downcase

Makes each character in a string lowercase (with no change to strings that are already all lowercase). For example, where a person’s first name is Jerry in the CDP, {{ people.first-name | downcase }} will output, jerry.

escape

Escapes a string by replacing characters with escape sequences (such as replacing & with &).

escape_once

Escapes a string without changing existing escaped entities (e.g. & will remain as &).

first

Returns the first item of an array. For example, {{ "Hello from Ortto" | split: " " | first }} will output Hello.

floor

Rounds an input down to the nearest whole number. For example, {{ 1.2 | floor }} will output 1.

join

Combines the items in an array into a single string using the argument as a separator. For example {% assign varcities = "London, New York" | split: ", " %} {{ varcities | join: " and " }} will output London and New York.

last

Returns the last item of an array. For example {{ "Hello from Ortto" | split: " " | last }} will output Ortto.

lstrip

Removes all whitespace (tabs, spaces, and newlines) from the left side of a string without affecting the spaces between words.

minus

Subtracts a number from another number. For example, {{ 4 | minus: 2 }} will output 2.

modulo

Returns the result of a division operation. For example, {{ 24 | modulo: 7 }} will output 3.

newline_to_br

Inserts an HTML line break (<br />) in front of each newline

plus

Adds a number to another number. For example, {{ 16 | plus: 4}} will output 20.

prepend

Adds a string you specify to the beginning of another string. For example {{ "London, New York, and Milan" | prepend: "City destinations on sale now: " }} will output 'City destinations on sale now: London, New York, and Milan'

remove

Removes every occurrence of the specified substring (part of a string) from a string. For example {{ "Customer journeys made remarkable" | remove: "ma" }} will output Customer journeys de rerkable.

remove_first

Removes only the first occurrence of the specified substring (part of a string) from a string. For example {{ "Customer journeys made remarkable" | remove_first: "ma" }} will output Customer journeys de remarkable.

replace

Replaces every occurrence of the first argument in a string with the second argument. For example, {{ "An update on my order" | replace: "my", "your" }} will output An update on your order.

replace_first

Replaces only the first occurrence of the first argument in a string with the second argument. For example {{ "My order and my total" | replace: "my", "your" }} will output My order and your total.

reverse

Reverses the order of the items in an array (or a string by splitting the string into an array). For example, {{ ".ottrO morf olleH" | split: "" | reverse | join: "" }} will output Hello from Ortto.

round

Rounds a number to the nearest integer or, if a number is passed as an argument, to that number of decimal places. For example, {{ 1.2 | round }} will output 1.

rstrip

Removes all whitespace (tabs, spaces, and newlines) from the right side of a string without affecting the spaces between words.

size

Returns the number of characters in a string or the number of items in an array. For example, {{ "Hello from Ortto" | size }} will output 16.

slice

Returns a substring of one character or series of array items beginning at the index specified by the first argument. For example {{ "Ortto" | slice: 0 }} will output O.

split

Divides a string into an array using the argument (such as a comma) you specify as a separator. For example, {% assign varcities = "London, New York, Milan" | split: ", " %} {% for item in varcities %} {{ item }} {% endfor %} will output London New York Milan

strip

Removes all whitespace (tabs, spaces, and newlines) from both the left and right sides of a string without affecting the spaces between words

strip_html

Removes any HTML tags from a string. For example {{ "Have <em>you</em> signed up for our <strong>newsletter</strong>?" | strip_html }} will output Have you signed up for our newsletter?.

times

Multiplies a number by another number. For example, {{ 3 | times: 2 }} will output 6.

truncate

Shortens a string to the number of characters you specify, and appends an ellipsis if the specified number of characters is less than the length of the string. For example {{ "Hello from Ortto!" | truncate: 9 }} will output Hello …​.

truncatewords

Shortens a string down to the number of words you specify, and appends an ellipsis if the specified number of words is less than the length of the string. For example {{ "Hello from Ortto!" | truncatewords: 1 }} will output Hello…​

uniq

Removes any duplicate items in an array. For example, {% assign varmy_products = "hats, scarves, scarves, shoes" | split: ", " %} {{ varmy_array | uniq | join: ", " }} will output hats, scarves, shoes

upcase

Makes each character in a string uppercase (with no change to strings that are already all uppercase). For example, where a person’s first name is Jerry in the CDP, {{ people.first-name | upcase }} will output, JERRY.

url_decode

Decodes a string that has been encoded as a URL or by url_encode. For example {{ "%27Hello%21%27+from+Ortto" | url_decode }} will output 'Hello!' from Ortto.

url_encode

Converts any URL-unsafe characters in a string into percent-encoded characters. For example {{ "lauren@email.com" | url_encode }} will output lauren%40email.com.