Filters#
Standard liquid filters are available out of box.
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>
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):
secondminutehourdayweekfortnightmonthyear
{{ valid_until | add_time: 42 }}
{{ valid_until | add_time: 3, 'months' }}
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 }}
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"]
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
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"}
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
}
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_decode#
Decodes given base64 encoded string.
{{ "c29tZSBzdHJpbmc=" | base64_decode }}
Returns some string
base64_encode#
Converts given string into a base64 encoded string.
{{ "some string" | base64_encode }}
Returns c29tZSBzdHJpbmc=
claim_url#
Returns channel-specific claim URL.
{{ "facebook" | claim_url }}
{{ "linkedin" | claim_url }}
{{ "twitter" | claim_url }}
class_names#
Helps conditionally add CSS classes. Returns string of class names built from arguments.
Example |
Result |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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' }}
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.
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
}
]
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 }}
group_by#
Group an array’s items by a given property.
{{ incentives | group_by: "amount" }}
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 %}
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 }}
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;
}
interpolate#
Allows inline string interpolation using [[ ]] syntax.
{{ "Get [[incentives.click.amount | money]] Off" | interpolate }}
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 rankleaderboard_count- Number of approved referrals for specified periodleaderboard_subtotal- Sum of advocate purchase subtotals for specified periodalso 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 }}
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.
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:
unitseparatordelimiterformatprecision (integer)strip_insignificant_zeros (boolean)
Example |
Result |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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: []
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: {}
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
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.
points#
Formats number using conversion rate for loyalty from site settings.
{{ "50" | points }}
Returns 500.
Available options:
delimiterformatpercentage_discount (boolean)convert (boolean)- It will work like money filter if value false
Example |
Result |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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 }}
rybbon#
Takes a campaign key of a BHN Rewards (formerly Rybbon) Talkable campaign. Makes a claim request within the scope of the given campaign and returns a gift claim link. Requires BHN Rewards (formerly 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 BHN Rewards (formerly 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: BHN Rewards (formerly Rybbon)
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 }}
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.
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" }}
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.
strip#
Removes leading and trailing blank symbols from the string.
{{ " strip me " | strip }}
Returns strip me.
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
tweet_length#
Calculates a tweet length for the string.
{{ "wow this is a tweet http://example.com" | tweet_length }}
Returns 43.
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.
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 }}" />
values#
Takes a hash and returns the array of its values.
{% assign incentive_configs = incentives | values %}
Returns [{ad incentive config}, {fr incentive config}]
where#
Select all the objects in an array where the key has the given value.
{{ incentives | where: "amount", 10 }}