Part 3: Using Liquid Filters

String Filters

Time for completion: 5 mins

The majority of the content/data you’ll likely be working with in WebinOne will come in the form of strings.

If you recall, from Part 2 of this Liquid course about Strings in your data Objects, all that juicy content packaged in double quotes can be further liquified to fit your every need.

Let’s look at a really simple string filter and work up to more complex filtering.

Imagine you have a blog post and you want to use the main body content to produce a preview or simplified description text for the post. Maybe you’re using this in the blog list view or in the code for a social sharing widget so you can control the description text that gets posted.

The first thing you’re going to want to do in this case is reduce the blog post content down to plain text, otherwise any HTML formatting will likely not look right in a description area or cause issues if used in a javascript widget.

The strip_html filter does just that. It strips out the HTML markup leaving behind the clean textual content.

So how do you apply the filter? Well, first you need to get the Liquid Object ({{ … }}) that outputs the blog post content area. And we’ll be working inside the blog post ‘List’ layout so the Object will look like this:

{{this.description}}

Let’s say this renders the following content, as an example:

<h2>Welcome to our blog.</h2>
<p>It’s all about <strong>running blogs and writing blog posts!</strong></p>
<p>To stay up-to-date, <a href=“/subscribe”>SUBSCRIBE NOW!</a></p>

Now, to apply the filter you can simply append a pipe character (|) along with the strip_html keyword:

{{this.description | strip_html }}

This will now render:

Welcome to our blog. It’s all about running blogs and writing blog posts! To stay up-to-date, SUBSCRIBE NOW!

Easy!

Now, your blog post, of course, is going to be a lot more wordy and you’ll probably want to trim it down to a shorter version for use as preview text.

For this task you can apply another filter on top of this filter. Yes! Filters can be combined to produce more complex results.

The filter for this task is called truncate and, like above, you can just append it to your Liquid Object after the first filter:

{{this.description | strip_html | truncate: 50 }}

But there’s something different with this filter. It includes an additional argument after the keyword.

Many Liquid filters include one or more arguments like this which allow you to further define how the filter behaves.

Filter arguments are added following a colon (:) and are either defined as a string ("string") or a number (50). Multiple arguments are separated by a comma (,).

So, the above combined filter will now give you the first 50 characters from the blog post’s plain text content:

Welcome to our blog. It’s all about running blogs...

By default, the truncate filter will add an ellipsis (…) to the end of your preview text to indicate there is more to this content. However, by adding a further argument to this filter you can change the default ellipsis to something else. For example, you might want to add a “Read more” note:

{{this.description | strip_html | truncate: 50, " [READ MORE]" }}

Giving you something like this:

Welcome to our blog. It’s all about ru [READ MORE]

Notice how the text has been cut off at a different position this time? That’s because the number of characters in your replacement ellipsis count towards the truncated characters.

Having an exact number of characters rendered like this provides a good amount of accuracy and control, however, it doesn’t provide good readability. It would be better to truncate per word rather than per character. Well, thankfully there is a filter for that too.

Let’s change our filter to truncatewords and see what happens. It’s a similar set up:

{{this.description | strip_html | truncatewords: 9, " [READ MORE]"}}

Which gives you:

Welcome to our blog. It’s all about running blogs [READ MORE]

Notice, in this case, the word count of your replacement ellipsis is NOT counted in the truncated word count.

Now, let’s make one more adjustment to this filter.

When displaying this preview text in your Blog’s list view you’d like the [READ MORE] text to be a dynamic link to the blog post’s detail view. And you might think, that’s easy, I’ll just include the anchor element and Liquid Object for the URL, like so:

{{this.description | strip_html | truncatewords: 9, " <a href="{{this.url}}">[READ MORE]</a>"}}

And you’d mostly be right. But there are some considerations to account for here.

Firstly, you are using double quotes (for the href value) inside a string that is already wrapped with double quotes. So your inner double quotes will break the string.

Secondly, and similarly to the above issue, you are using a Liquid Object inside a Liquid Object. So the inner pair of double curly brackets will break the Object.

There are a few ways to resolve this, but for this stage of the course we’ll look at perhaps the most straight-forward and compact solution, which is to simply precede each conflicting character with a backslash (\) to “escape” it from the overall string:

{{this.description | strip_html | truncatewords: 9, " <a href=\"\{\{this.url\}\}\">[READ MORE]</a>"}}

The escape character (\) instructs the code to treat the following character as part of the string and not the start/end of the argument or Liquid Object.

Using the strip_html filter here not only removes unwanted styling in the preview text but also avoids possible breaking of your overall page HTML structure as the truncate and truncatewords filters could otherwise cut through the middle of a HTML element in your blog post content, leaving that element without a closing tag and corrupting the rest of your page.

This is just one of many applications for Liquid Filters, so don’t stop here. Be sure to check out all the other string filters documented here.

Array Filters

Time for completion: 3 mins

Most of the time, when you're working with arrays that come directly from your website's data, you'll be using for loops to go through each item. But sometimes, you need to turn a string into an array, or do something a bit more custom.

For example, you may have a plain text string of words or items listed out, separated by spaces or commas or some other delimiter, and you want to work dynamically with those items within Liquid.

One of the most common tricks is using the split filter to break the string into an array, utilising the delimiters that separate the items.

Let’s say you have a string of friends' names, perhaps collected from a form or entered into a Custom Module field, like this:

Now, you want to loop through each name and do something with each one. So, we can start by converting the string above into a usable array, like so:

{% assign myFriends = this.Friends | split: "," %}

The Liquid output of the myFriends variable will now simply be:

John Paul George Ringo

However, Liquid can now parse these names as individual items, which we can then use with more advanced Liquid tags (like for loops) or use further Array Filters for things like sorting the order of the items, removing duplicates or blank items, or counting how many names we have.

Some examples could be:

Ordering alphabetically:

{{ myFriends | sort_natural }}

George John Paul Ringo

Count the number of names:

{{ myFriends | size }}

4

There are various other Array Filters to explore in the Liquid Filters documentation.

Math Filters

Time for completion: 3 mins

Sometimes, your data isn't just text; it's numbers you need to perform calculations with.

That's where Math Filters come in handy, allowing you to execute a variety of mathematical operations on numbers (both whole numbers and floating-point/decimal numbers) directly within your Liquid code.

Here’s a basic example, adding two numbers together using the plus filter:

{{ 4.8 | plus: 2 }}

6.8

You can use variables in your calculations as well:

{% assign myNumber = 4.8 %}
{{ myNumber | plus: 2 }}

6.8

Keep in mind, when working with math filters, you should always use true numbers to avoid unpredictable results. As sometimes numbers can be disguised as strings.

{% assign not_a_number = "4.8" %}
{% assign actual_number = 4.8 %}

Notice the first variable not_a_number is not actually a true number and is instead a string since it is wrapped in quotation marks.

However, in simple math situations, Liquid will attempt to convert such strings to numbers wherever it can, and most of the time, your math filters will work. But to avoid unpredictable results, it’s always a good idea to convert numbers that may come from strings into true numbers yourself. To do this, we can use a simple trick, such as:

{% assign now_im_an_actual_number = "4.8" | plus: 0 %}

Simply by running a basic math function against the string, Liquid will convert it to a real number, and since we’re adding zero to the original number, it remains true to its original value.

There are various other Math Filters to explore in the Liquid Filters documentation.

Date/Time Filters

Time for completion: 2 mins

When you're dealing with timestamps or dates in your content, you'll often need to format them in a human-readable way, convert them to different date formats, or even perform date/time calculations. Date Filters are your go-to for these tasks.

Date Filters can understand date/time formats from the CMS as well as recognise most well-formatted date/time strings. So, when you have a date string that you want to work with in Liquid, you can easily convert it into the right format.

Here’s an example converting a date string with Liquid:

{{ "March 14, 2016" | date }}

14-Mar-2016

Or you may be getting the date from your module item:

<!-- "ReleaseDate": "2018-09-04T15:30:00" -->
{{ this['ReleaseDate'] | date }}

04-Sep-2018

This is the default output of the date filter when used without any arguments.

We can, however, completely restructure every part of the datetime object in a variety of ways by passing a special syntax to the date filter as an argument:

{{ this['ReleaseDate'] | date: "%Y-%m-%d %l:%M %p" }}

2018-09-04 3:30 PM

There is also the special "now" keyword to get the current datetime object from the server (based on the website’s timezone):

{{ "now" | date }}

27-Feb-2025

There are various other Date Filters to explore in the Liquid Filters documentation.

Currency Filters

Time for completion: 2 mins

When displaying prices or financial figures on your website, it's helpful to format them according to cultural standards, especially across different regions. Currency Filters help you do just that, drawing on the 'Currency and Format' settings configured for your domains in the site admin.

Culture, Language and Price setting are assigned against your domain/s set up for your website, and so these Liquid filters will format numbers either according to the current domain or based on a domain you set (as an argument to the filter).

Let’s assume the current domain is configured for the United States:

<-- Raw number value: 49990.95 -->
{{ myNumberValue | domain_number_format }}

49,990.95

Now, on the same domain, but you want to force a different format from one of your other configured domains:

{{ myNumberValue | set_number_format: "Denmark" }}

49.990,95

And likewise, you can add currency-related formatting based on the domain/culture:

<-- Raw number value: 49990.95 -->
{{ this.Price | domain_money_format }}

$49,990.95

Check out the full details for these Currency Filters in the Liquid Filters documentation.