Part 3: Using Liquid Filters

In this part of the course we’ll explore using Liquid Filters to transform and manipulate the display of your Treepl CMS website data.

Total time for completion: ?? mins

Quenched with the knowledge and know-how to draw Liquid data from Treepl CMS and flood it onto your page, you can now freeze, melt and/or steam that Liquid to your heart's content with the use of Filters.

...yeah, that was too much wasn’t it? But some things are worth going a little overboard with.

Filters allow you to manipulate all kinds of content in a variety of ways, which fall into the following categories:

String Filters

Time for completion: 5 mins

The majority of the content/data you’ll likely be working with in Treepl CMS 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: ? mins

Most of the Arrays you’ll come across in Treepl CMS will be directly from your component tags outputting module items or for properties with multiple values (like categories and tags), in which you’ll likely use for loops to process.

However, when working with more custom Liquid coding you may come across the need to manipulate existing arrays or to create your own arrays from parts of your data.

If you recall, from Part 2 of this Liquid course about Arrays in your data Objects.

... work in progress

Math Filters

Time for completion: ? mins

Date/Time Filters

Time for completion: ? mins

Currency Filters

Time for completion: ? mins

<<< Part 2: Liquid in Treepl CMS Part 4: Advanced Liquid Tags >>>



Related Articles

  • Working with Liquid
    Treepl has implemented the full standard Shopify Liquid library. See the External Resources below for...
  • Liquid Filters
    Liquid Filters allow you to modify the output of a Liquid object, whether that's adding something to it, removing something from it, executing a calculation, creating an array, or a wide variety of other powerful functions.
  • {{ this }} object
    This Liquid object is globally accessible in every liquid template or layout and outputs specific...
  • {{ request }} object
    This Liquid object is globally accessible in every liquid template or layout and outputs various...
  • {{ liquidContext }} object
    This Liquid object is globally accessible in every liquid template or layout and outputs a...
  • {{ member }} object
    This liquid object will output the Member's details of whom submitted a Form. You can...
  • {{ workflow }} object
    This liquid object will output the Workflow details of a submitted Form. You can use...
  • Part 1: Introduction to Liquid
    This free online course covers every aspect of using the Liquid templating language in Treepl CMS - from the very basics right through to advanced implementations.

    You’re welcome.
  • Part 2: Liquid in Treepl CMS
    In this part of the course we’ll explore how Liquid is implemented in treepl CMS and the overall concepts on using it to harness your website data.
  • Part 4: Advanced Liquid Tags
  • domain_settings
    This module component retrieves settings associated with the current domain, or optionally from another specified domain configured in the site instance.
  • Migrating from Liquid 1.0 to 2.0
    This article describes differences and possible required actions for migrating from the Liquid rendering engine v1.0 to v2.0.

External Resources

There are currently no external resources available.

Please let us know if you have any other contributions or know of any helpful resources you'd like to see added here.


Questions?

We are always happy to help with any questions you may have.
Send us a message at support@treepl.co and we will consult you as soon as possible.