Filters

Standard liquid filters that are available out of box.

import_font

Inserts the font declaration to the page.

{{ "My Font" | import_font }}

Returns:

@font-face {
   font-family: 'My Font';
   src: url('https://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/174201/original/font.woff') format('woff'), url('https://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/174202/original/font.woff2') format('woff2');
   font-weight: normal;
   font-style: normal;
}

asset_url

Inserts link for an uploaded asset.

{{ "image.jpg" | asset_url }}

Example: http://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/745/original/offer-background.jpg

simple_format

Formats plain text to have HTML formatting. E.g. replace \n with <br/>.

{{ "Hello [[advocate_info.email]]\nHere is your reward." | simple_format | interpolate }}

Returns Hello John<br/>Here is your reward.

encode_query_argument

Encodes a string to be included in a URL.

http://example.com/?utm_campaign={{ "Campaign Name" | encode_query_argument }}

Returns Campaign%20Name, so the URL will be http://example.com/?utm_campaign=Campaign%20Name.

update_query

Updates query parameters in a URL.

{{ "http://example.com/?a=b&utm_source=foo" | update_query: utm_campaign: "Campaign Name", utm_source: "talkable" }}

Returns http://example.com/?a=b&utm_campaign=Campaign%20Name&utm_source=talkable.

probability_by

This filter returns true or false for a dataset based on the probability you request:

{{ 50 | probability_by: "param1", "param2", "param3" }}

50 returns true in 50% cases for requested dataset. This filter provides the same result for a particular dataset.

Note

probability should be always an integer value between 1 and 100.

Here is another example that returns true only in 10% cases for the interpolation variable:

{{ 10 | probability_by: advocate_info.email }}

You can ommit passing any parameters and the result will be based on the Advocate offer. Also you may use probability as an alias which is a little shorter to write:

{{ 50 | probability }}

This example can be used in Email sending condition of Advocate Offer Email template to send email only in 33% cases:

{% assign send_email = 33 | probability %}

{% if send_email %}
  true
{% endif %}

rand_by

Produces a random value which is always the same for specific parameters passed. First parameter is a maximum random number.

Simple example:

{{ "100" | rand_by: "param1", "param2" }}

Always returns 29.

Interpolation as a parameter:

{{ "10" | rand_by: advocate_info.email }}

Always returns the same number for a specific email, between 0 and 9.

regexp_captures

Parses input with a given regexp and returning regular expression captures as an array.

{{ '12345678' | regexp_captures: '(....)(....)' | join: '-' }}
{{ 'bogdan@example.com' | regexp_captures: '^([a-z]+)\@([a-z]+)\.([a-z]+)' | json }}

ab_test

A/B testing static text:

{{ "ab_test_identifier" | ab_test: "Label 1", "Label 2", "Label N" }}

A/B testing text with interpolation:

{{ "share_via_email_subject" | ab_test: "[[site_name]]",
   "Your friend [[advocate_info.email]] shared this deal with you" | interpolate }}

A/B testing an asset:

{{ "offer_background" | ab_test: "background-green.jpg", "background-red.jpg" | asset_url }}

A/B testing style:

<body style="background-color: {{ 'offer_background' | ab_test: '#d3d3d3', '#ff0000' }}">
  ...
</body>

<h1 style="font-size: {{ 'title_size' | ab_test: '24px', '30px' }}">
  Sample Title
</h1>

date_diff

Return absolute difference between two dates in seconds.

Date is compared to current time if no argument is passed.

All dates are interpreted in context of the site time zone unless time zone is specified.

{{ valid_until | date_diff }}
{{ valid_until | date_diff: 'Apr 4, 2019' }}
{{ '2019-09-01 08:30:00' | date_diff: current_time }}

date_greater_than

Return boolean that indicates whether a date is more recent than another date.

All dates are interpreted in context of the site time zone unless time zone is specified.

{{ current_time | date_greater_than: valid_until }}
{{ valid_until | date_greater_than: '2019-09-01 08:30:00' }}

date_greater_than_or_equal

Return boolean that indicates whether a date is the same as or more recent than another date.

All dates are interpreted in context of the site time zone unless time zone is specified.

{{ current_time | date_greater_than_or_equal: valid_until }}
{{ valid_until | date_greater_than_or_equal: '2019-09-01 08:30:00' }}

add_time

Add a specified amount of time to a date and return the result.

Time unit defaults to seconds.

Available time units (can be used in plural form as well):

  • second

  • minute

  • hour

  • day

  • week

  • fortnight

  • month

  • year

{{ valid_until | add_time: 42 }}
{{ valid_until | add_time: 3, 'months' }}

format_date

Format date for current localization.

Default format: Apr 04, 2014

Reference to all available formatting can be found in strftime documentation

Reference to all available locales can be found in rails-i18n documentation

{{ valid_until | format_date }}
{{ valid_until | format_date: format: "%Y-%m-%d" }}
{{ valid_until | format_date: locale: "ru" }}
{{ valid_until | format_date: format: "%Y-%m-%d", locale: "ru" }}
{{ current_time | format_date }}

human_time_ago

Transform given time to time ago in words.

If given time is yesterday, returns 1 day.

Reference to all available locales can be found in rails-i18n documentation

{{ valid_until | human_time_ago }}
{{ valid_until | human_time_ago: locale: "ru" }}
{{ current_time | human_time_ago }}

hours_from_time

Alias hours_from_now

Calculate difference between two dates. By default calculates between specified time and current time.

{{ "Sun, 02 Jan 2000 10:00:00 PST" | hours_from_time: "Sat, 01 Jan 2000 10:00:00 PST" }}
{{ "2015-03-27 17:53" | hours_from_time: "2015-03-27 15:53" }}

Next two examples is equivalent.

{{ friend_offer.valid_until | hours_from_time: current_time }}
{{ friend_offer.valid_until | hours_from_now }}

Pretty useful example for email sending criteria to prevent sending mail when offer is about to expire.

{% if friend_offer.valid_until %}
  {% assign difference = friend_offer.valid_until | hours_from_now %}
  {% if difference > 24 %}
    true
  {% else %}
    false
  {% endif %}
{% else %}
  true
{% endif %}

interpolate

Allows inline string interpolation using [[ ]] syntax.

{{ "Get [[incentives.click.amount | money]] Off" | interpolate }}

md5

Calculates the MD5 hash of the string.

{{ "foo" | md5 }}

Returns acbd18db4cc2f85cedef654fccc4a4d8.

money

Formats number using current currency.

{{ "50" | money }}

Returns $50.00.

Available options:

  • unit

  • separator

  • delimiter

  • format

  • precision (integer)

  • strip_insignificant_zeros (boolean)

Example

Result

{{ "100.11" | money: precision: 0 }}

$100

{{ "100.99" | money: precision: 0 }}

$101

{{ "100.99" | money: strip_insignificant_zeros: true }}

$100.99

{{ "100.90" | money: strip_insignificant_zeros: true }}

$100.9

{{ "100.00" | money: strip_insignificant_zeros: true }}

$100

{{ "100" | money: unit: "€" }}

€100.00

{{ "100" | money: unit: "" }}

100.00

{{ "10049.99" | money: separator: "_" }}

$10,049_99

{{ "10049.99" | money: delimiter: "_" }}

$10_049.99

{{ "100" | money: format: "%n %u", unit: "zł" }}

100.00 zł

points

Formats number using conversion rate for loyalty from site settings.

{{ "50" | points }}

Returns 500.

Available options:

  • delimiter

  • format

  • percentage_discount (boolean)

  • convert (boolean) - It will work like money filter if value false

Example

Result

{{ "10050" | points: delimiter: "_" }}

100_500

{{ "100" | points: format: "%nP" }}

1000P

{{ "100" | points: convert: false }}

$100.00

{{ "1000" | points: convert: false, delimiter: "," }}

$1,000.00

{{ "100" | points: convert: false, unit: "€" }}

€100.00

{{ "100" | points: percentage_discount: true }}

500

strip

Removes leading and trailing blank symbols from the string.

{{ "    strip me " | strip }}

Returns strip me.

squish

Returns the string, first removing all whitespace on both ends of the string, and then changing remaining consecutive whitespace groups into one space each.

{{ "   foo   bar        baz " | squish }}

Returns foo bar baz.

tweet_length

Calculates a tweet length for the string.

{{ "wow this is a tweet http://example.com" | tweet_length }}

Returns 43.

parse_json

Parses the JSON string source into a Liquid data structure.

{% assign var = '{"key": "value"}' | parse_json %}
{{ var.key }}

Returns value.

pluralize

Returns the singular or plural form of a word based on the value of a number. Accepts singular (required) and plural (optional) forms.

Example

Result

{{ 5 | pluralize: "point" }}

5 points

{{ 2 | pluralize: "sheep" }}

2 sheep

{{ 1 | pluralize: "day off" }}

1 day off

{{ 5 | pluralize: "day off" }}

5 day offs

{{ 0 | pluralize: "day off", "days off" }}

0 days off

As shown in the table, simple words can be pluralized without specifying plural form. However, more advanced cases require explicit plural form to work correctly.

claim_url

Returns channel-specific claim URL.

{{ "facebook" | claim_url }}
{{ "linkedin" | claim_url }}
{{ "twitter" | claim_url }}

group_by

Group an array’s items by a given property.

{{ incentives | group_by: "amount" }}

sort

Sort an array. Optional arguments for hashes: 1. property name 2. nils order (first or last).

{{ campaign_tags | sort }}
{{ incentives | sort: "amount" }}
{{ incentives | sort: "amount", "first" }}

where

Select all the objects in an array where the key has the given value.

{{ incentives | where: "amount", 10 }}

localize

Returns a localized version of string from campaign localization. Has optional argument that specifies a default value if campaign has no defined localization yet. Supports nested interpolation with [[ ]]

{{ "welcome_message" | localize }}
{{ "offer_title" | localize: "Get [[incentives.referrer.description]]" }}

Supports fixed variants for localization, user will be able to set localization value only from this list. First value will be a default value, or you can set it using default option.

{{ "campaign_layout" | localize: "left", "right" }}
{{ "header_size" | localize: "h1", "h2", "h3", "h4", default: "h2" }}

There is also boolean localization type. It has a strict requirement: exactly two variants which determines boolean logics. The first variant is associated with true, the last one — false. The first variant is set as default unless you change it to otherwise with a default option (see above for an example). Here is an example of how to use boolean localization:

{% assign responsive_font = 'fonts_size' | localize: 'Responsive', 'Fixed', trait: 'boolean' %}
{% if responsive_font %}
  Responsive
{% else %}
  Fixed
{% endif %}

For more information see Localization page.

scale_color

Returns a new adjusted color with scaled attributes. Available attributes: red, green, blue, saturation, lightness, alpha

{{ "black" | scale_color: lightness: 50 }}
{{ "rgb(256, 128, 0)" | scale_color: saturation: -10 }}

adjust_color

Returns a new adjusted color based on the following attributes:

  • red — changes only the Red color channel saturation. Allowed values: -255-255.

  • green — changes only the Green color channel saturation. Allowed values: -255-255.

  • blue — changes only the Blue color channel saturation. Allowed values: -255-255.

  • hue — changes the hue of a color. Allowed values: 0-360.

  • saturation — changes the saturation of a color. Allowed values: -100-100.

  • lightness — changes the lightness of a color. Allowed values: -100-100.

  • alpha — changes the opacity of a color. Allowed values: -1-1.

{{ "red" | adjust_color: blue: 255 }}
{{ "#000000" | adjust_color: alpha: -0.5 }}

leaderboard

Returns array of top advocates for Leaderboard campaigns. Parameter can be number from 1 to 100 or ‘advocate’.

If parameter is ‘advocate’ it will return rank info for current advocate.

It returns objects with next fields:

  • leaderboard_rank - Advocate rank

  • leaderboard_count - Number of approved referrals for specified period

  • leaderboard_subtotal - Sum of advocate purchase subtotals for specified period

  • also all fields from advocate_info variable

{% assign leaders = "3" | leaderboard %}
{% for leader in leaders %}
   <td>{{ leader.leaderboard_rank }}</td>
   <td>{{ leader.leaderboard_count }}</td>
{% endfor %}

{% assign leader = "advocate" | leaderboard %}
{{ leader.email }} - {{ leader.leaderboard_count }} - {{ leader.leaderboard_rank }}

url2png

Captures a snapshot of a website URL you pass to it. In case you need to embed a snapshot of your website into Talkable campaign it is way better to use this liquid filter instead of embedding an iframe since an image is always lighter in size and takes less CPU performance to render on a screen. Also, some websites restrict themselves from embedding through an iframe so you can take url2png as a bulletproof solution for a website snapshot.

Available options:

  • ttl - “time to live” period for a screenshot before it gets refreshed, in seconds. Value example: 86400.

  • viewport - Viewport dimensions. Value example: "640x480".

  • custom_css_url - Custom CSS file that will be injected into a website in case you need to change a screenshot. Value example: "http://url2png.com/tests/css/test.css".

  • fullpage - Attempts to capture entire document canvas. Value example: true.

Here is how you can embed a screenshot of your website into a campaign view (site_url returns your website URL that you set inside Site Settings):

<img src="{{ site_url | url2png }}" class="campaign-site-on-the-back" />

Refresh the screenshot every week:

<img src="{{ 'www.example.com' | url2png: ttl: 604800 }}" />

barcode

Represents any string as an array of boolean values: [true, false] in order to convert it into a barcode. This filter strictly follows GS1-128 specification: https://en.wikipedia.org/wiki/GS1-128.

{% assign barcode = "X" | barcode %}

Here is an example how to convert a coupon code into a barcode:

HTML:

<table cellspacing="0" cellpadding="0" border="0">
  {% assign barcode = coupon_code | barcode %}
    <tr>
      {% for bar in barcode %}
        <!-- bar suppose to be true or false -->
        <td class="barcode-line is-{{ bar }}"></td>
      {% endfor %}
    </tr>
</table>

SCSS:

.barcode-line {
  height: 50px;
  width: 2px;
  &.is-true {
    background-color: black;
  }
}

barcode_image

Represents any string as barcode image in png. This filter strictly follows GS1-128 specification: https://en.wikipedia.org/wiki/GS1-128.

It may take the following arguments: height, xdim (thickness of the thinnest line), margin and bg_transparent.

Default values are 100 for height, 1 for xdim, 0 for margin and false for bg_transparent.

The values are in pixels.

{{ coupon.code | barcode_image }}
{{ coupon.code | barcode_image: height: 200 }}
{{ coupon.code | barcode_image: xdim: 3 }}
{{ coupon.code | barcode_image: height: 200, xdim: 3 }}
{{ coupon.code | barcode_image: height: 200, xdim: 3, margin: 5 }}
{{ coupon.code | barcode_image: height: 200, xdim: 3, margin: 5, bg_transparent: true }}

Returns a URL string.

base64_encode

Converts given string into a base64 encoded string.

{{ "some string" | base64_encode }}

Returns c29tZSBzdHJpbmc=

base64_decode

Decodes given base64 encoded string.

{{ "c29tZSBzdHJpbmc=" | base64_decode }}

Returns some string

values

Takes a hash and returns the array of its values.

{% assign incentive_configs = incentives | values %}

Returns [{ad incentive config}, {fr incentive config}]

async_rendering

Stores Liquid partial that can be later rendered via Talkable.loadLiquid function.

Example 1

Liquid

{{ "async_advocate_info" | async_rendering: 'template for rendering with data [[ advocate_info.email ]]' }}

JavaScript API call

Talkable.loadLiquid("async_advocate_info", function(rendered_template) {
  console.log(rendered_template);
});

Rendered Liquid

"template for rendering with data advocate@example.com"

Example 2

Liquid

{{ 'async_dashboard_data' | async_rendering: some_key: "[[ dashboard.possible_rewards | money: strip_insignificant_zeros: true ]]", other_key: "[[ friend_info.purchases_count ]]" }}

JavaScript API call

Talkable.loadLiquid("async_dashboard_data", function(rendered_data) {
  console.log(rendered_data.some_key);
});

Rendered Liquid

"$420"

Example 3

Liquid

{% capture some_liquid_block %}
{% raw %}
Whatever Liquid you would like to have
{% endraw %}
{% endcapture %}
{{ 'async_liquid_reference' | async_rendering: some_liquid_block }}

JavaScript API call

Talkable.loadLiquid("async_liquid_reference", function(rendered_template) {
  console.log(rendered_template);
});

Rendered Liquid

"Whatever Liquid you would like to have"

Example 4

Use json Liquid filter to transform deeply nested object structure into a valid JSON.

Liquid

{{ 'async_advocate_info' | async_rendering: '[[ advocate_info | json ]]' }}

JavaScript API call

Talkable.loadLiquid("async_advocate_info", function(rendered_template) {
  console.log(JSON.parse(rendered_template));
});

Rendered Liquid

{
  "first_name": null,
  "last_name": null,
  "email": "advocate@example.com",
  "username": null,
  "external_customer_id": null,
  "opted_in_at": null,
  "sub_choice": false,
  "purchases_sum": 0.0,
  "purchases_count": 0,
  "events_count": 0,
  "events_count_by_category": {
    "friend_signup": 0,
    "purchase": 0
  },
  "referrals_count": 0,
  "referred_by": null,
  "custom_properties": {},
  "unsubscribed": false
}

events_collection

Collection of person’s events from the certain date (or for all time when from_time is not set).

{{ "purchase" | events_collection: from_time: "10/14/2018" }}

Returns

[
  {
    "coupon_codes": ["OFF5"],
    "created_at": "2019-05-22T15:53:41-07:00",
    "email": "ad@site.com",
    "order_number": 98237519,
    "refunded": false,
    "subtotal": 100.0
  },
  {
    "coupon_codes": ["OFF5"],
    "created_at": "2019-05-22T15:53:41-07:00",
    "email": "ad@site.com",
    "order_number": 98237520,
    "refunded": true,
    "subtotal": 200.0
  }
]

rybbon

Takes a campaign key of a Rybbon Talkable campaign. Makes a claim request within the scope of the given campaign and returns a gift claim link. Requires Rybbon app to be installed and enabled in order to work.

{{ "a9a3472f4ea858758e0cd686de8408e2" | rybbon }}

Returns https://www.rybbon.net/redeem.php?claimcode=ee645de47765bdbede751c8c6f08a619

Accepts custom amount of reward for Rybbon campaigns with variable denomination. The minimum amount conforms to each specific Rybbon gift card restrictions. The maximum amount is 50.

{{ "a9a3472f4ea858758e0cd686de8408e2" | rybbon: amount: 13.5 }}

tremendous

Takes a campaign key of a Tremendous campaign. Makes a claim request within the scope of the given campaign and returns a gift claim link. Requires Tremendous app to be installed and enabled in order to work. Implies that there is only one funding source in the Tremendous account.

{{ "DEM8ULSSATK0" | tremendous }}

Returns https://www.tremendous.com/rewards/payout/reward123