Liquid Template Guide

Picture crafting an email template that seamlessly adapts with unique, personalized information. That's what Liquid helps you do. It's like a special recipe book for emails. You write some simple adlib like phrases, and boom! Your email can show different things to different people. Want to greet visitors by name? Show special deals? Liquid makes it possible. It's not super fancy, but it's pretty neat. Check out the basic Liquid guide below to learn its tricks.

The Basics

These essential tags will allow you to personalize your email extensively with links, buttons, images, and even audio to kick things off.

{{ "http://example.com" \| hyperlink: "Click here!" }}

{{ "http://example.com" | button: "Click here!", "#999" }}

{{ 'https://app.bentonow.com/sounds/click.mp3' | audio_tag }}

{{ 'https://app.bentonow.com/brand/bento-logo-3d.png' | img_tag: "class name", "id", "alt", 100, 200, false }}

{{ visitor.greeting }}

{{ visitor.pretty_name }}

{{ visitor.email | profile_tag: visitor.pretty_name.first }}

Operators & Conditionals

{% if visitor.tags contains "customer" %}
This visitor has a 'customer' tag.
{% endif %}

{% if visitor.city contains "New York" %}
You are in New York!
{% elsif visitor.city contains "Sydney" %}
You are in Sydney!
{% else %}
You are on earth!
{% endif %}

{% if visitor.order_count >= 10 %}
This visitor has ordered over 10 times!
{% endif %}

Visitors Reference

Liquid Filters

Liquid filters are powerful keywords that instruct Liquid how to manipulate the variables we provide. They are commonly used for tasks such as appending text, rounding numbers, performing basic math operations, formatting data, and sorting lists. These filters go beyond mere inactive template filling; they actively transform and refine the input to produce dynamic, polished outputs. For instance, you can use filters to truncate lengthy descriptions, convert strings to uppercase, or even handle complex date manipulations. By leveraging these versatile tools, developers can create more responsive and interactive web experiences. Ultimately, Liquid filters are essential for anyone looking to maximize the functionality and presentation of their templated content, ensuring that the final output is both accurate and aesthetically pleasing. Below is a list of filters, but you can find the full specification documentation here.

Append

Adds the specified string to the end of another string.

// Liquid Filter
{{ "John" \| append: visitor.last_name }}

John Doe

Capitalize

Makes the first character of a string capitalized and converts the remaining characters to lowercase.

// Liquid Filter
{{ "quick Brown Fox." \| capitalize }}

Quick brown fox.

// Only the first character of a string is capitalized, so later words are not capitalized:
{{ "my GREAT title" | capitalize }}

My great title

Default

Sets a default value for any variable with no assigned value. default will show its value if the input is nil, false, or empty.

// Liquid Filter
// In this example, product_price is not defined, so the default value is used.
{{ product_price | default: 2.99 }}

2.99

// To allow variables to return false instead of the default value,
// you can use the `allow_false` parameter.
{{ display_price | default: true, allow_false: true }}

false

Divide By

Divides a number by another number.
The result is rounded down to the nearest integer (that is, the floor) if the divisor is an integer.

// Liquid Filter
{{ 16 | divided_by: 4 }}
{{ 5 | divided_by: 3 }}

4
1

// divided_by produces a result of the same type as the divisor — that is, if you divide by an integer, the result will be an integer. If you divide by a float (a number with a decimal in it), the result will be a float.
{{ 20 | divided_by: 7.0 }}

2.857142857142857

Downcase

Makes each character in a string lowercase. It has no effect on strings which are already all lowercase.

// Liquid Filter
{{ "Bento Now" | downcase }}

bento now

{{ "apple" | downcase }}

apple

Minus

Subtracts a number from another number.

// Liquid Filter
{{ 4 | minus: 2 }}
{{ 16 | minus: 4 }}
{{ 183.357 | minus: 12 }}

2
12
171.357

New Line Br

Inserts an HTML line break <br /> in front of each newline \n in a string.

// Liquid Filter
{% capture string_with_newlines %}
Hello
there
{% endcapture %}

{{ string_with_newlines | newline_to_br }}

Hello<br />
there<br />

Plus

Adds a number to another number.

// Liquid Filter
{{ 4 | plus: 2 }}
{{ 16 | plus: 4 }}
{{ 183.357 | plus: 12 }}

6
20
195.357

Prepend

Adds the specified string to the beginning of another string.

// Liquid Filter
{% assign first_name = "John" %}
{{ "Doe" | prepend: first_name }}

John doe

Remove

Removes every occurrence of the specified substring from a string.

// Liquid Filter
{{ "The apple fox jumped apple over the apple fence." | remove: "apple" }}

The fox jumped over the fence.

Replace

Replaces every occurrence of the first argument in a string with the second argument.

// Liquid Filter
{{ "The fox jumped over my fence." | replace: "my", "your" }}

The fox jumped over your fence.

Round

Rounds a number to the nearest integer or, if a number is passed as an argument, to that number of decimal places.

// Liquid Filter
{{ 1.2 | round }}
{{ 2.7 | round }}
{{ 183.357 | round: 2 }}

1
3
183.36

Truncate

Shortens a string down to the number of characters passed as an argument. If the specified number of characters is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count.

// Liquid Filter
{{ "The fox jumped over the fence." | truncate: 18 }}

The fox jumped ov…

// truncate takes an optional second argument that specifies the sequence of characters to be appended to the truncated string. By default this is an ellipsis (…), but you can specify a different sequence.
{{ "The fox jumped over the fence." | truncate: 20, ", and so on"  }}

The fox jumped over and so on

Upper

Makes each character in a string uppercase. It has no effect on strings which are already all uppercase.

// Liquid Filter
{{ "Bento" | upcase }}

BENTO

Helpers Reference

Environment Variables

Interact and check the env variables.

Encryption

These helpers offer a convenient way to encrypt string values, enabling you to encrypt something for a user on demand without needing to store it for retrieval.

Time

These tools provide an interface to dynamically work with time, which proves invaluable when managing extensive subscriber lists that necessitate batching. By calculating the precise time for each user when the email is queued for sending, you mitigate concerns about information in the template becoming outdated if a batch is sent several hours later. This ensures that all recipients receive the most current and relevant information. This can also be used for example remind a user that their birthday is coming up in X number of days, or that it's been X number of weeks since they last signed in or made a purchase.

Money

Format money according to the currency assigned to the subscriber or visitor.

Lottery Element

Lottery or randomly pick an element from the provided list. No limitations or weighting applied to elements, ensuring each item has an equal chance of selection.

Broadcasts

These liquid tags are designed to function specifically within the context of your broadcast and will not work anywhere else.

Sequences

These liquid tags are designed to function specifically within the context of your sequences and will not work anywhere else.

{{ sequence.cancel_sequence_url | hyperlink: "No more emails like this!" }}

// Skip only
{{ sequence.fast_forward_url | hyperlink: "Instantly get the next email." }}

// Skip and redirect
{{ sequence.fast_forward_url | append: "&redirect=https://bentonow.com/skip" | hyperlink: "Instantly get the next email with redirect." }}

Ecommerce

{% assign cart = visitor | current_cart %}
{% for item in cart %}
{{ item.product_name }} - {{ item.product_price }} - {{ item.product_quantity }}
{% endfor %}

{% for product in products %}
{{ product.product_name }} - {{ product.product_price }} - {{ product.product_quantity }}
{% endfor %}

Abandoned Cart Checkout URL

A quick and convenient method for generating a personalized URL to seamlessly guide users back into their shopping cart from a reminder email. This makes it easier for users to return to their cart.

Stripe and Spotify

These Liquid tags enable you to seamlessly integrate with the Stripe and Shopify platforms, offering convenient methods to generate on-demand coupon codes.

{{ visitor | shopify_coupon_generator: "100OFF", "-10", "fixed_amount" }}

{{ visitor | stripe_coupon_generator: "TEST", "10", 5 }}

{{ visitor | stripe_billing_portal: "https://bentonow.com" }}

External Data

This feature enables you to seamlessly integrate public data from external sources outside of bento directly into your templates, enhancing the richness and relevance of your content with broader data and context.

{% assign posts = 'https://feedforall.com/sample.xml' | rss %}
{% for post in posts %}
{{ post.title }}
{% endfor %}

Gmail Promo

Add Promo Annotation

{{ "20% OFF" | promotion_annotation: "TEST" }}