Mobile Commons: Liquid Templates

Mobile Commons

Provided Information on the Liquid Templates and how they work.

Liquid is an amazing template engine developed and open sourced by the good folks at Shopify. Please read our Liquid Basics article before you get started and be sure to check out our attached webinar deck, as well as our recording from our Liquid Webinar. 

Article Index:

• Liquid Markup
• Output
• Filters
• Tags
• If/Else Templates

Please note, you must replace any spaces in your field name with underscores when using that name in liquid or mail merge. For example, you might have a custom field named Birth Date but you would denote this as birth_date in liquid or mail merge. 

For example, let's say you want to ask users for their email address if you don't have it. But you don't want to bother users whose email you already have. The below template will generate 2 different text messages depending on the recipient. (here we've put in Jane as a first name). Users whose email address you already have will receive: Hi Jane! We will be contacting you shortly. While users who have never provided their email will receive: Hi Jane! Please reply with your email.

Hi {{first_name}}!
{% if email %}
  We will be contacting you shortly.
{% else %}
  Please reply with your email.
{% endif %}

Liquid Markup

There are two types of markup in Liquid: Output and Tag.

Output Markup (often resolves to, or displays as text) is surrounded by: {{…}} matched pairs of curly brackets

Tag Markup (does not resolve or display as text) is surrounded by: {%...%} matched pairs of a curly bracket and percent sign

Output

Here is a simple example of Output:

Hello {{name}}
Hello {{first_name}}
Hello {{'ben'}}

All Mobile Commons profile attributes, including custom columns, are available out of the box to use in in your Liquid templates in a "mail merge" fashion. You can insert any of the standard Mobile Commons Mail Merging Fields as well as any of your custom fields.

• custom_field- include the name of any custom field in your account (e.g. "favorite_pet”)
• last_message- the full text of the last message this user texted in, if any
• repeating_question- will be true if this is the second time we have asked the same multiple choice question. Allows for you to change your message the second time you ask it.
• ab- randomly switches between true or false. Useful for quick-and-dirty A/B testing of message copy.

Here is an example:

{% if ab %}

Do you like ice cream?

{% else %}

Do you like cookies?

{% endif %}

Filters

Filters allow you to perform commands or equations within tags, they can also help you format your output.

Hello {{ first_name | default: 'friend' }}!The time in California is {{'now' | timezone: 'Pacific' | date: "%H:%m" }}

Here are some basic Filters. For the full list of filters please see our Advanced Liquid page

• default - use a default value e.g. Dear {{ first_name | default: 'Customer' }}, #=> 'Dear Customer,'
• date - format a date. See all supported date formats here.
• timezone - convert a date to a different timezone. Expects a timezone name parameter, eg ('Eastern' or 'Pacific'). Useful for converting UTC to a local time.
• capitalize - capitalize words in the input sentence
• downcase - convert an input string to lowercase
• upcase - convert an input string to uppercase
• timezone - convert timezone e.g. {{'2014-09-01 09:00:00 EDT' | timezone:'pacific'}}
• minus - subtraction e.g. {{ 4 | minus:2 }} #=> 2
• plus - addition e.g. {{ '1' | plus:'1' }} #=> '11', {{ 1 | plus:1 }} #=> 2
• times - multiplication e.g {{ 5 | times:4 }} #=> 20
• divided_by - division e.g. {{ 10 | divided_by:2 }} #=> 5

Tags

Tags are used for the logic in your template. For most simple Liquid templates you’ll be using if and assign most frequently.

Here is a list of currently supported tags:

• if - Standard if/else block
• assign - Assigns some value to a variable
• capture - Block tag that captures text into a variable
• case - Block tag, its the standard case...when block
• comment - Block tag, comments out the text in the block
• cycle - Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
• for - For loop
• include - Includes another template; useful for partials
• raw - temporarily disable tag processing to avoid syntax conflicts.
• unless - Mirror of if statement

If / Else

If/Else statements are the most popular way to build out variable messages with Liquid. if / else should be well-known from any other programming language.

Liquid allows you to write simple expressions in the if or unless (and optionally, elsif and else) clause.

Send a message to someone whose name is John, and a different one to someone whose name is Jane.

{% if first_name == 'John' %} 

Hello John

{% elsif first_name == 'Jane' %} 

Hello Jane

{% endif %} 

Send the same message to someone whose name is John or Jane.

{% if first_name == 'John' or first_name == 'Jane' %} 

Hello John or Jane

{% endif %} 

Send a message to someone whose first name is John and whose age_field is above 45. Based on having an age type custom field.

{% if first_name == 'John' and age_field > 45 %} 

Hello old John

{% endif %} 

Send a message to someone whose first_name is not John.

{% if first_name != 'John' %}

Hello non-John

{% endif %} 

The below template will produce the same result as the above.

{% unless first_name == ‘John’ %}

Hello non-John

{% endunless %} 

Send a message to someone who has any value in the first_name field

{% if first_name != null %}

You got a name

{% endif %} 

The below template will produce the same result as the above.

{% if first_name %}

You got a name

{% endif %} 

Send one message to subscribers over the age of 18 and a different one to those under the age of 18. Based on having an age type custom field.

{% if age_field > 18 %}

You can enter the contest.

{% else %}

Sorry, you are too young

{% endif %} 

Send one message to subscribers whose last message has ‘yes’ in it and another to those whose last message does not. Last_message is case insensitive.

{% if last_message has 'yes' %}

Awesome!

{% else %}

Bummer.

{% endif %} 

Send a message to a subscriber whose date is before a specified date. 

{% if custom_date_field is_before '2016-07-04' %}

Your date is before!

{% endif %} 

Send a message to a subscriber whose date is after a specified date.

{% if custom_date_field is_after '2016-07-04' %}

Your date is after!

{% endif %} 

Send a message to a subscriber whose date is the same day as a specified date.

{% if custom_date_field is_same_day_as '2016-07-04' %}

Your date is the same day!

{% endif %} 

Have users with an address make an mConnect call (where reply "CALL" is your mConnect keyword-replace with YOUR mConnect keyword); have users WITHOUT an address first provide their address. You may also use this for senate-asking simply for a postal_code instead of the entire address. 

{% if street1 == null %}

Reply with your full address to be connected to your local representative

{% elsif street1 != null %}

Reply CALL to be connected to your Representative.

{% endif %}

Please see the below screenshots for this template in-action:

For information on building more complex Liquid templates, including a counter to score quizzes, and more please visit our Advanced Liquid Page.

Liquid Webinar PDF