Filters

Filters are simple Ruby methods you can provide to Liquid templates to transform input data in various ways.

All methods take at least one argument which represents the input of the filter, and you can also support multiple method arguments (and even optional ones). The return value will be the output of the filter.

Example:

class Builders::Filters < SiteBuilder
  def build
    liquid_filter :cache_busting_url do |url|
      "http://www.example.com/#{url}?#{Time.now.to_i}"
    end
  end
end

{{ "mydynamicfile.js" | cache_busting_url }}

outputs:

http://www.example.com/mydynamicfile.js?1586194585

Supporting Arguments #

You can accept multiple arguments to your filter by simply adding them to your block or method, and optional ones are simply specified with a default value (perhaps nil or false). For example:

class Builders::Filters < SiteBuilder
  def build
    liquid_filter :multiply_and_optionally_add do |input, multiply_by, add_by = nil|
      value = input * multiply_by
      add_by ? value + add_by : value
    end
  end
end

Then just use it like this:

5 times 10 equals {{ 5 | multiply_and_optionally_add:10 }}

  output: 5 times 10 equals 50

5 times 10 plus 3 equals {{ 5 | multiply_and_optionally_add:10, 3 }}

  output: 5 times 10 plus 3 equals 53

And of course you can chain any number of built-in and custom filters together:

5 times 10 minus 4 equals {{ 5 | multiply_and_optionally_add:10 | minus:4 }}

  output: 5 times 10 minus 4 equals 46

Using Instance Methods #

As with other parts of the Builder API, you can also use an instance method to register your filter:

class Builders::Filters < SiteBuilder
  def build
    liquid_filter :cache_busting_url, :bust_it
  end

  def bust_it(url)
    "http://www.example.com/#{url}?#{Time.now.to_i}"
  end
end

If your filter name and method name are the same, you can omit the second argument.

Filter Execution Scope #

The code within the filter block or method is executed within the scope of the builder object. This means you will need to use the filters method to call other filters.

class Builders::Filters < SiteBuilder
  def build
    liquid_filter :slugify_and_upcase do |url|
      filters.slugify(url).upcase
    end
  end
end

You also have access to the Liquid context via filters_context, which provides current template objects such as the page (e.g., filters_context.registers[:page]).

When to use a Filter vs. a Tag #

Filters are great when you want to transform input data from one format to another and potentially allow multiple transformations to be chained together. If instead you simply want to insert a customized piece of content/HTML code into a page, then it’s probably better to write a Tag.

Back to Plugins