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: "en" }}
{{ valid_until | format_date: format: "%Y-%m-%d", locale: "en" }}
{{ 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: "en" }}
{{ 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

new_array¶

Creates a new array. If arguments are provided, they become the elements of the array.

Liquid

{% assign my_array = "" | new_array: "element1", "element2" %}
{% assign empty_array = "" | new_array %}

Array: {{ my_array | json }}
Empty array: {{ empty_array | json }}

Rendered Liquid

Array: ["element1","element2"]
Empty array: []

append_to_array¶

Appends elements to an existing array.

Liquid

{% assign my_array = "" | new_array %}
{% assign my_array = my_array | append_to_array: "element1", "element2" %}

Array: {{ my_array | json }}

Rendered Liquid

Array: ["element1","element2"]

new_hash¶

Creates a new hash. If a hash is provided as an argument, it returns that hash.

Liquid

{% assign my_hash = "" | new_hash: key: "value", key2: 42 %}
{% assign empty_hash = "" | new_hash %}

Hash: {{ my_hash | json }}
Empty hash: {{ empty_hash | json }}

Rendered Liquid

Hash: {"key":"value","key2":42}
Empty hash: {}

assign_key¶

Assigns a key-value pair to an existing hash. If the key already exists, its value is updated.

Liquid

{% assign my_hash = "" | new_hash: key: "value", key2: 42 %}
{% assign my_hash = my_hash | assign_key: "key2", "value2" %}
{% assign my_hash = my_hash | assign_key: "key3", "value3" %}

Hash: {{ my_hash | json }}

Rendered Liquid

Hash: {"key":"value","key2":"value2","key3":"value3"}

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 }}

Find more details about the integration here: Rybbon

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

Find more details about the integration here: Tremendous