Liquid Templates
Last updated
Was this helpful?
Last updated
Was this helpful?
Census uses the template language to give you extra control over the data you send.
These are tiny programs that let you change the format of data using a simple snippet of code. For example, you can use Liquid to...
Add prefixes or suffixes
Change to upper or lower case
Format dates
Combine columns together
Conditionally use alternate values
Build JSON objects or arrays
Liquid is easy to learn and also very powerful. We look forward to seeing the templates you build!
Census does not support any Shopify- or Jekyll-specific extensions to Liquid templates, so be sure you're referencing the standard docs at .
Your most basic operation in Liquid is to reference a record column, like this:
You can add text before or after a variable reference by putting it outside the {{
and }}
markers:
By using two variable references in one template, you can combine columns together:
Another very common job for Liquid is transforming text. Liquid filters are activated with the |
(pipe) symbol:
All of the columns on your source record are available using the record['COLUMN_NAME']
syntax. When Census sees this syntax, it knows this column is required from the source.
The exact column name must be used in the record
property accessor.
Convert text to lowercase:
Convert text to uppercase:
Substitute all example text with the provided result text:
Remove space characters from the start and end of the text:
Format a timestamp as a text date:
Census also includes a number of custom filters specifically designed to help you with data transforms...
Encode a value into JSON syntax:
Get a subset of an object with some keys removed:
Get a subset of an object containing just some keys:
Get all of the keys of an object:
Get the SHA-256 hash of a value and return the hex representation:
Encode a value using Base64:
As you write your Liquid templates, it's possible that you may make a typo or don't quite have the right syntax. Census will catch all these errors as you type, and you'll know about them well before your sync starts running.
Here are some invalid template examples that will be caught by Census:
{{ record['ID' }}
→ Liquid syntax error: Expected close_square but found end_of_string in "{{ record['ID' }}"
{{ record['NAMEE'] }}
→ Column being referenced in template can't be found in data source [NAMEE]
{% assign category = record['CAT'] %}{{ categoryy.ratio | times: 100 }}
→ [categoryy.ratio | times: 100] unknown variable `categoryy`
The examples above just scratch the surface of what can be done with Liquid templates. The language exposes enough capabilities to define complex conditions, process structured data, and do some really advanced data manipulation.
Make a new variable from a value:
Make a new variable from captured text:
Construct conditions based on matching values:
Generate text for each item:
If you're using spaces in a complex template and notice your output now includes unwanted spaces, this is a sign that you need to use Liquid whitespace control syntax.
Liquid is basically text building engine. You can think of {{ ... }}
and {% ... %}
as "insertion points" into a text file...
The code inside the brackets will get run by Liquid, and it doesn't make a difference if there's whitespace inside the code, only the code's output will be inserted.
On the other hand, any whitespace outside of those insertion points will be preserved by Liquid, just like any other text.
Preserved whitespace won't be an issue for text formats like HTML and JSON where whitespace is collapsed or ignored, but for many other use cases, whitespace is significant and causes problems.
Here are a few examples of whitespace inside vs. outside Liquid code blocks (using {id: 1}
as the record data)...
"id{{ record['id'] }}"
"id1"
" {{record['id']}} "
" 1 "
"{% if true %}{{ record['id'] }}{% endif %}"
"1"
"{% if true %} {{ record['id'] }} {% endif %}"
" 1 "
"{% if true %} {{- record['id'] -}} {% endif %}"
"1"
"{% if true -%} {{ record['id'] }} {%- endif %}"
"1"
Notes:
Whitespace inside code has no effect
Whitespace outside code is preserved
No whitespace between tags gives no result whitespace
Whitespace between tags is preserved
Whitespace control symbol strips whitespace around variable
Whitespace control symbol strips whitespace inside tags
Two special features get activated when in JSON mode:
JSON strings are escaped by default, which means that you don't need to worry about source data causing JSON syntax errors.
This behavior can be overridden using either the json
filter (to encode a value into valid JSON) or the raw
filter (when your source data is already valid JSON).
Instead of triggering an error, Census allows this syntax and converts it into valid JSON. It does this by parsing the template output as YAML, which is a strict superset of JSON (allows all valid JSON) that accepts these "trailing commas".
If you want, you're free to use any other YAML features, like block-style collections, and the result will still be converted to valid JSON:
For example, if your source column name is COMPANY_ID
, then you must use record['COMPANY_ID']
in your Liquid template. Any other variations such as company_id
, companyid
, or companyID
will be raised as errors.
There are over 40 standard Liquid filters to be found in the left sidebar in the . Here are a few common ones...
Often used together with . Also accepts an array or an object as a single argument.
Often used together with . Also accepts an array or an object as a single argument.
Can be helpful for generating hashed identifiers for advertising destinations like or .
If you're writing advanced expression and want to store an intermediate result, you can create your own Liquid variables to help ().
You can build advanced conditional code with Liquid, for example, to use one variable or another, or to "translate" values for your destination ().
Construct a condition using boolean :
You can also iterate over arrays to build text with repeating elements ().
Commonly used in and with .
To deal with this, Liquid uses the -
(hyphen) symbol for whitespace control, stripping out whitespace at the insertion point where the symbol is used ().
includes single spaces, line breaks, and tabs—any of the blank spaces you see in your template code.
One special use for Liquid templates is to build JSON documents. This can be great for advanced API usage with templated fields or even building custom integrations with the destination.
When generating JSON data using for , this process will often leave a ,
after the last item in an array or object, which is invalid JSON.