Custom filters

In addition to the filters available by the standard implementation of the Liquid syntax, we provide you a few more.

You can use filters in this way: {{ [expression] | [filter_name]:[parameters] }}.

Filters apply a transformation over the expression and return the transformed value. For example {{ "abc" | upcase }} would return ABC.

group_by

Can only be used with arrays. It groups the elements of the array by the given property. It returns a new array of objects where each object has the following attributes: name, items and size

Example

Having the following HTML:

{% assign locations_by_country = locations | group_by:"country_code" %}
{% for country in locations_by_country %}
<h1>{{ country.name }}</h1>
<ul>
  {% for loc in country.items %}
  <li>{{ loc.name }}</li>
  {% endfor %}
</ul>
{% endfor %}

And the following locations:

• Barcelona (country_code ES)
• Madrid (country_code ES)
• Munich (country_code DE)

It would produce the following output:

<h1>ES</h1>
<ul>
  <li>Barcelona</li>
  <li>Madrid</li>
</ul>
<h1>DE</h1>
<ul>
  <li>Munich</li>
</ul>

where

Can only be used with arrays. It filters the elements of the array by the given property and value.

Example

{% assign locations_from_spain = locations | where:"country_code","ES" %}

where_exp

Can only be used with arrays. It filters the elements of the array by the given expression.

Example

{% assign locations_from_spain = locations | where_exp:"location","location.country_code == ES" %}

sort

Can only be used with arrays. It sorts the elements of the array by the given property. If no property is given it performs a default sort, for example if the array contains only numbers or strings.

Example

{% assign nearby_locations = locations | sort:"distance" %}

json

Converts the input provided to JSON format.

Example

{% location | json %}

distance_to_human

Converts a number to a human readable distance.

Example

{% location.distance | distance_to_human %}

parse_json

Converts a JSON string to JSON object

{% capture json_string %}
  [
    {"id":"12345","email":"foo@bar.baz"},
    {"id":"67890","email":"bar@baz.qux"}
  ]
{% endcapture %}
{% assign json_objects = json_string | parse_json %}
{{ json_objects | map: "email" | join: ", " }}

parse_csv

Converts a CSV string to an Array object.

The parse_csv filter accepts a “headers” option; when set to true, this filter will interpret the first line of input as containing headers for the CSV table, and will return an array of hashes whose keys map to items in that header row.

Example

{% capture csv_string %}
  Name, ID, Date
  #1234, 1234567890, 2021/03/23
  #1235, 1234567891, 2021/03/24
{% endcapture %}
{% assign csv_rows = csv_string | parse_csv %}
{% for row in csv_rows %}
  {{ row[0] }} -- {{ row[1] }} -- {{ row[2] }}
{% endfor %}

When is executed with headers: true

{% capture csv_string %}
  Name, ID, Date
  #1234, 1234567890, 2021/03/23
  #1235, 1234567891, 2021/03/24
{% endcapture %}
{% assign csv_rows = csv_string | parse_csv: headers: true %}
{{ csv_rows | json }}

Returns:

[{"Order Name":"#1234","Order ID":"1234567890","Order Date":"2021/03/23"},{"Order Name":"#1235","Order ID":"1234567891","Order Date":"2021/03/24"}]

t

In general, a translation key has the form of 1st-level.2nd-level.3rd-level, where each level of the key is associated with the following levels of locale JSON file hierarchy:

<h1>{{ 'general.404.title' | t }}</h1>
<p>{{ 'general.404.subtitle' | t }}</p>

The following is how those same keys appear in a locale JSON file:

{
  "general": {
    "404": {
      "title": "Page not found",
      "subtitle": "Sorry, we couldn't find this page."
    }
  }
}

We can use this filter with interpolations to each available variable in the page, for example:

<h1>{{ 'layout.header.business' | t: name: business.name, twitter_page: business.twitter_page }}</h1>

On the locale json files, we should use these keys:

{
  "layout": {
    "header": {
      "business": "Business {{ name }} twitter_page: {{ twitter_page }}!"
    }
  }
}