Docs

Platform

Templates

Liquid helpers reference

Liquid helpers

A reference to help you work with the Liquid templating language in Knock.

The Knock template editor uses Liquid syntax for control flow and variable declaration. Here are a few of the most common Liquid keywords our customers use within Knock. We recommend referencing the Liquid documentation for comprehensive syntax and usage information.

Keyword	Description
`{{ }}`	Denotes rendering output of an object or variable.
`{% %}`	Denotes logic and control flow.
`if/else/elsif`	Conditional branching.
`case/when`	Creates a switch statement to execute a particular block of code when a variable has a specified value.
`and/or`	Add additional conditions to a tag.
`for`	Repeatedly executes a block of code.
`assign`	Creates a new named variable.
`capture`	Captures the string inside of the opening and closing tags and assigns it to a variable.
`render`	Renders a partial with the given key and attributes.

Knock-specific Liquid helpers

Knock extends Liquid with helpers that format, transform, and evaluate data when rendering notification templates.

Date and time

Takes an ISO 8601 timestamp and returns it in the IANA tz database timezone provided. You can use the built-in timestamp template variable to reference the current datetime. When formatting with the date filter, we recommend using the timezone option on the date filter instead.

Example	Output
`{{ timestamp \| timezone: "America/New_York"}}`	2023-12-31T19:30:00-05:00

This filter has been extended to take an additional timezone option. It accepts strftime-style format strings, but Knock's Liquid implementation does not support the full strftime specification. Notably, %e and %l are not fully supported.

Example	Output
`{{ startDate \| date: "%-I:%M %p %Z" , "America/New_York" }}`	2:30 PM EST

Converts an ISO 8601 timestamp to a localized date string. Requires a locale parameter and accepts an optional date_format: "short" (default), "medium", "long", or "full". See the date format options table below for examples.

Example	Output
`{{ timestamp \| format_date_in_locale: "en-GB", "long" }}`	31 December 2023

Converts an ISO 8601 timestamp to a localized date and time string. Requires locale, date_format, and time_format parameters. Date and time formats can be: "short" (default), "medium", "long", or "full". See the date format options and time format options tables below for examples.

Example	Output
`{{ timestamp \| format_datetime_in_locale: "en-GB", "medium", "short" }}`	31 Dec 2023, 14:30

Numbers and currency

Takes an integer and formats it to the local number format of the provided locale.

Example	Output
`{{ 10000 \| format_number: "en" }}`	10,000

Takes an integer and returns a USD formatted value with two decimal points. You can pass a currency type and a locale through to the currency helper to tell it which currency to use.

Example	Output
`{{ 10 \| currency: "GBP", "en" }}`	£10.00

Takes an integer and returns a USD formatted value rounded to nearest whole number. You can pass a currency type and a locale through to the currency helper to tell it which currency to use.

Example	Output
`{{ 10.99 \| rounded_currency: "GBP", "en" }}`	£11

Text and data

Takes a value and returns as a formatted JSON string.

Example	Output
`{{ recipient \| json }}`	`{"id": "user_123", "name": "John Hammond"}`

Takes a JSON string and returns a parsed object whose properties can be referenced via their keys.

Example
`{% assign recipient = input \| from_json %}`

Takes an integer and a pluralize helper with two strings. If the integer is one, the helper returns the first string. If the helper is greater than one, it returns the second string.

Example	Output
`{{ total_actors \| pluralize: "user", "users" }}`	users

Takes a string and reformats it into Title case.

Example	Output
`{{ project_name \| titlecase }}`	My Project Name

Takes a string of markdown and converts it to HTML.

Example	Output
`{{ data.comment_body \| from_markdown }}`	`<h1>Hello</h1>`

Returns the intersection of two arrays (the elements common to both).

Example	Output
`{{ arr1 \| intersect: arr2 }}`	`["Acme Corp", "InGen"]`

For a given semantic version string, compares it to a second version string provided as an argument. Returns an integer indicating the order of the versions; -1 if the first version is less than the second, 0 if they are equal, and 1 if the first version is greater than the second.

Example	Output
`{{ "1.0.0" \| compare_versions: "2.0.0" }}`	`-1`

Hashing

Takes a string and returns an md5 hash.

Example
`{{ recipient.id \| md5 }}`

Takes a string and returns an sha256 hash.

Example
`{{ recipient.id \| sha256 }}`

Takes a string and returns an hmac hash given a key provided to hmac_sha256 helper.

Example
`{{ recipient.id \| hmac_sha256: "some-key" }}`

Localization and formatting

Date format options

The format_date_in_locale and format_datetime_in_locale helpers accept date format options that control how the date portion is displayed.

Value	Description	Example (en-US)	Example (en-GB)
`short`	Abbreviated date format.	12/31/23	31/12/2023
`medium`	Standard date format.	Dec 31, 2023	31 Dec 2023
`long`	Full date format.	December 31, 2023	31 December 2023
`full`	Complete date format.	Sunday, December 31, 2023	Sunday, 31 December 2023

Time format options

The format_datetime_in_locale helper accepts time format options that control how the time portion is displayed.

Value	Description	Example (en-US)	Example (en-GB)
`short`	Abbreviated time format.	2:30 PM	14:30
`medium`	Standard time format.	2:30:45 PM	14:30:45
`long`	Full time format.	2:30:45 PM EST	14:30:45 GMT
`full`	Complete time format.	2:30:45 PM Eastern Standard Time	14:30:45 Greenwich Mean Time

Localization parameters

The format_date_in_locale, format_datetime_in_locale, format_number, currency, and rounded_currency helpers take an optional locale parameter to format the output into a localized format. If we're missing a locale that you'd like us to support, please reach out.

Supported locales. af, ar, az, be, bg, bn, bs, ca, cs, cy, da, de, de-DE, el, en, en-US, en-GB, eo, es, es-419, et, eu, fa, fi, fr, fr-CA, fr-FR, gl, he, hi, hr, hu, id, is, it, ja, ja-JP, ka, km, kn, ko, lb, lo, lt, lv, mk, ml, mn, mr, ms, nb, ne, nl, nn, no, or, pa, pl, pl-PL, pt, pt-BR, rm, ro, ru, sk, sl, sq, sr, sv, sw, ta, te, th, tr, tt, ug, uk, ur, uz, vi, wo, zh, zh-CN, zh-Hans, zh-Hant

Dynamic data filters

Knock provides a set of Liquid filters that dynamically load data from your Knock environment at template render time. These filters enable you to reference entities like users, objects, tenants, and subscriptions in your templates without passing all of the data in your workflow trigger call. For more details and examples, see referencing data in templates.

Filter	Description	Example
`user`	Loads a user by their identifier. Returns a serialized User with all custom properties, as well as id, name, email, phone_number, created_at, and updated_at.	`{% assign user = "chris" \| user %}`
`object`	Loads an object by its identifier and collection. Returns a serialized Object with all custom properties, as well as id, collection, created_at, and updated_at. Requires a collection parameter.	`{% assign project = "proj_1" \| object: "projects" %}`
`tenant`	Loads a tenant by its identifier. Returns a serialized Tenant with all custom properties, as well as id, created_at, and updated_at.	`{% assign tenant = "acme" \| tenant %}`
`subscriptions`	Loads up to 25 active subscriptions for a user by their identifier. Returns a list of subscription objects, each containing the subscribed Object and any custom properties set on the subscription.	`{% assign subs = recipient.id \| subscriptions %}`