Skip to content

Liquid Filters

Jump to bottom
Peter Johnson edited this page Feb 13, 2023 · 38 revisions

Liquid Filters 💧

⚠️⚠️ THIS WIKI IS BEING USED TO JOT DOWN IDEAS AT PRESENT. DON'T ASSUME ANYTHING IS FIXED. ⚠️⚠️

⚒️ MORE TO COME: Check back later

The filters listed on this page are based on, and have similar syntax and purpose to, Liquid filters. They are not guaranteed to work in exactly the same way as the Liquid versions, but they emulate the behaviour as closely as is practical.

🗒️ Not all liquid filters will necessarily be implemented.

🗒️ Those filters listed here that are not yet implemented are marked with a ⛔ symbol.

The examples included with many of the filters are copied or adapted from the Liquid documentation and so use the Liquid | pipe and : parameter symbols instead of the > and < symbols normally used by rpt.

A link to the original Liquid documentation is included with each filter.

abs

⛔ Returns the absolute value of a numberish value provided on its input. If the input is not numberish then an error is reported.

Parameters: none

Input type: numberish

Output type: Number (Int if input was, or was converted to, Int or Float if input was, or was converted to, Float)

Example:

{{ -17 | abs }}
{{ -56.42 }}
{{ 4 | abs }}
{{ "42" | abs }}

Outputs

17
56.42
4
42

append

⛔ Appends the text given as a parameter to the input and returns the result.

Parameter: text to be appended, type textish.

Input type: textish

Output type: text

Example:

{{ "/my/fancy/url" | append: ".html" }}

Outputs

/my/fancy/url.html

at_least

⛔ Limits a number to a minimum value. This filter outputs the larger of the input number and the parameter.

Parameter: minimum number to be output, Numeric

Input type: Numeric

Output type: Numeric (Int if both the input and parameter have type Int, otherwise Float.)

Example:

{{ 4 | at_least: 5 }}
{{ 4 | at_least: 3 }}
{{ 5.2 | at_least: 5.1 }}
{{ 5.2 | at_least: 5.9 }}
{{ 5.2 | at_least: 6 }}
{{ 7 | at_least: 6.5 }}

Outputs

5
4
5.2
5.9
6.0
7.0

at_most

⛔ Limits a number to a maximum value. This filter outputs the smaller of the input number and the parameter.

Parameter: maximum number to be output, Numeric

Input type: Numeric

Output type: Numeric (Int if both the input and parameter have type Int, otherwise Float.)

Example:

{{ 4 | at_most: 5 }}
{{ 4 | at_most: 3 }}
{{ 5.2 | at_most: 4.8 }}
{{ 5.2 | at_most: 5.9 }}
{{ 5 | at_most: 6.8 }}
{{ 7.9 | at_most: 6 }}

Outputs

4
3
4.8
5.2
5.0
6.0

capitalize

⛔ Makes the first character of a string capitalized and converts the remaining characters to lowercase.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "title" | capitalize }}
{{ "my GREAT title" | capitalize }}

Outputs

Title
My great title

ceil

⛔ Rounds an input Float up to the nearest whole number.

Parameter: none.

Input type: Floatish

Output type: Int

Example:

{{ 1.2 | ceil }}
{{ 2.0 | ceil }}
{{ 183.357 | ceil }}

Outputs:

2
2
184

date

⛔ Formats a DateTime as a Text value according to the format string passed as a parameter. The format string has the same syntax as strftime.

Parameter: date formatting string, type Text.

Input type: DateTime

Output type: Text

Example (assuming @now is returning 2015-07-17):

{{ @now | date: "%a, %b %d, %y" }}
{{ @now | date: "%Y" }}

Outputs:

Fri, Jul 17, 15
2015

default

⛔ Provides a default value for any input with no assigned value. The filter's parameter is output if the input is Null, false, or is the empty string.

To allow the input to be false, and have that value not replaced with the default value, set the optional second parameter to true.

Parameters:

  1. The default value to use, type Any.
  2. Flag indicating whether to pass Boolean false values on input to output without replacement with the default value. Type Boolean. Optional: default is @false.

Input type: Any

Output type: Any

⚠️ In Liquid (from v5.0.0) the optional 2nd parameter has to be named allow_false. Since Treacle does not support named parameters, the Boolean parameter must be specified without naming it.

Examples

In this first example product_price starts off undefined, so the default value is used. product_price is then given a value so that value is used. Finally product_price is set to the empty string the default value is again used.

{{ product_price | default: 2.99 }}
{{ product_price := 4.99; }}
{{ product_price | default: 2.99 }}
{{ product_price := ""; }}
{{ product_price | default: 2.99 }}

Outputs

2.99
4.99
2.99

The following shows how to allow false to be passed through from input to output. In the 1st placeholder the input of @false causes the default value to be used. The 2nd placeholder passes @false through to output. The third placeholder once again outputs the default because the empty string is input: the 2nd parameter has no effect in this case.

{{ @false | default: true }}
{{ @false | default: true, true }}
{{ "" | default: true, true }}

Outputs

1
0
1

🗒️ Treacle renders Boolean true and false as 1 and 0 respectively while Liquid renders the values as true and false.

divided_by

⛔ Divides the number on the input by the number passed as a parameter.

The result is of the same type as the divisor (i.e. the parameter). So if the divisor is an integer then the result will be rounded down to the nearest integer. In the case where the divisor is floating point then the result will also be floating point, with no rounding.

Parameter: the divisor (must not be 0), type Int or Float

Input type: Int or Float

Output type: Int or Float (same as parameter)

Example:

{{ 20 | divided_by: 7 }}
{{ 20 | divided_by: 7.0 }}
{{ 25.5 | divided_by: 8 }}
{{ 25.5 | divided_by: 8.7 }}

Outputs

2
2.8571428571
3
2.9310344828

Notes:

  1. To force floating point division when the parameter is an integer use an embedded placeholder with the rpt int-to-float filter, as follows:

     {{ 20 | divided_by: {{ 7 | int-to-float }} }}

  2. Dividing a floating point value by an integer is equivalent to doing a floating point division and taking the floor of the result. So the following two placeholders will return the same result:

     {{ 42.5 | divided_by: 7 }}
 {{ 42.5 | divided_by: 7.0 | floor }}

  3. 👀 See also the less complicated rpt div (integer division) and divide (floating point division) filters.

downcase

⛔ Converts each character of text from the input into lower case.

Any type other than text is first converted to text and then processed.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "Parker Moore" | downcase }}
{{ "apple" | downcase }}

Outputs

parker moore
apple

escape

⛔ Escapes input text by replacing characters with HTML entities (so that the text is valid for use in HTML). It doesn’t change input that doesn't have anything to escape.

⚠️ Passing already escaped text through escape will escape the introductory & characters of HTML entities. To avoid this use escape_once instead.

🗒️ rpt implementation notes:

  1. Only those characters that have special meaning in HTML and XHTML are converted. Other characters that may have equivalent HTML entities are passed through unchanged.
  2. Like Liquid, &#39 is used for single quotes to avoid a potential problem using the symbolic entity &apos; with Internet Explorer 🙁.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "Have you read 'James & the Giant Peach'?" | escape }}
{{ "Tetsuro Takara" | escape }}
{{ "A &amp; B" | escape }}

Outputs

Have you read &#39;James &amp; the Giant Peach&#39;?
Tetsuro Takara
A &amp;amp; B

💡 INFO TO HELP IMPLEMENT: see escape_once below.

escape_once

⛔ Escapes input text by replacing characters with HTML entities (so that the text is valid for use in HTML) without changing existing escaped entities. It doesn’t change input that doesn't have anything to escape.

🗒️ rpt implementation notes:

  1. Only those characters that have special meaning in HTML and XHTML are converted. Other characters that may have equivalent HTML entities are passed through unchanged.
  2. Like Liquid, &#39 is used for single quotes to avoid a potential problem using the symbolic entity &apos; with Internet Explorer 🙁.
  3. Only those symbolic entities defined by W3C are preserved.
  4. Symbolic entities that omit the terminal ; character are not preserved.
  5. All decimal and hexadecimal numeric entities are preserved.

Parameters: none

Input type: Textish

Output type: Text

Examples:

{{ "1 < 2 & 3" | escape_once }}
{{ "1 &lt; 2 &amp; 3" | escape_once }}

Outputs

1 &lt; 2 &amp; 3
1 &lt; 2 &amp; 3

💡 INFO TO HELP IMPLEMENT:

floor

⛔ Rounds an input Float down to the nearest whole number.

Parameter: none.

Input type: Floatish

Output type: Int

Example:

{{ 1.2 | floor }}
{{ 2.0 | floor }}
{{ 183.357 | floor }}

Outputs:

1
2
183

lstrip

⛔ Removes all whitespace (tabs, spaces, and newlines) from the left side of input text. It does not affect spaces between words.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "          So much room for activities          " | lstrip }}!

Output

So much room for activities          !

minus

⛔ Subtracts the number given as a parameter from the input number and outputs the result.

Parameter: number to be subtracted from input, type Numeric.

Input type: Numeric

Output type: Int if both the input and parameter are Int, otherwise Float.

Example:

{{ 4 | minus: 2 }}
{{ 16.9 | minus: 4.2 }}
{{ 183.357 | minus: 12 }}

Outputs

2
12.7
171.357

modulo

⛔ Returns the remainder of a division operation. The number input to the filter is divided by the number passed as a parameter.

If the input is an integer then the output is also an integer, otherwise the output is floating point.

Parameter: the divisor (must no be zero), type Int.

Input type: Int or Float

Output type: Int or Float (same type as input)

Example:

{{ 3 | modulo: 2 }}
{{ 24 | modulo: 7 }}
{{ 183.357 | modulo: 12 }}

Outputs

1
3
3.357

⚠️ The Liquid documentation for this filter does not state whether the divisor must be an integer. However all the given examples use an integer divisor, implying this may be required. This is the approach taken by the rpt implementation.

👀 See also the similar rpt mod filter.

newline_to_br

⛔ Inserts an HTML line break (<br />) in front of each newline in a string.

🗒 The Liquid documentation states that a newline is a \n character, but the rpt implementation supports \n, \r & \r\n newline sequences, providing they are consistent throughout the text.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "Lorem\r\nIpsum\r\nDelor" | newline_to_br }}

Outputs

Lorem<br />
Ipsum<br />
Delor

⚠️ As noted, this filter only works when the newline characters are consistent throughout the text. If this is not the case then the rpt replace-newlines filter can be used to ensure newlines are consistent. For example the following placeholder replaces both the \n and \r\n newlines with <br />\r\n:

{{ "Lorem\nIpsum\r\nDelor" | replace-newlines: "\r\n" | newline_to_br }}

🗒 newline_to_br always uses the XHTML compliant <br /> tag. If you want to use the HTML 4 & HTML 5 <br> tag instead then replace-newlines can help once again. Use:

{{ "Lorem\nIpsum\r\nDelor" | replace-newlines: "<br>\r\n" }}

plus

⛔ Adds the number given as a parameter to the input number and outputs the result.

Parameter: number to be added to input, type Numeric.

Input type: Numeric

Output type: Int if both the input and parameter are Int, otherwise Float.

Example:

{{ 4 | plus: 2 }}
{{ 16.0 | plus: 4.2 }}
{{ 183.357 | plus: 12 }}

Outputs

6
20.2
195.357

prepend

⛔ Prepends the text given as a parameter to the input and returns the result.

Parameter: text to be prepended, type textish.

Input type: textish

Output type: Text

Example:

{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}

Outputs

Some fruit: apples, oranges, and bananas

remove

⛔ Removes every occurrence of the substring specfied in the parameter from the input string.

Parameter: text to be removed, type Textish

Input type: Textish

Output type: Text

Example:

{{ "I strained to see the train through the rain!" | remove: "rain" }}

Outputs

I sted to see the t through the !

🗒 The Liquid documentation has nothing to say about whether the text to be removed is searched for case sensitively. The rpt implementation assumes case is significant.

remove_first

⛔ Removes only the first occurrence of the substring specfied in the parameter from the input string.

Parameter: text to be removed, type Textish

Input type: Textish

Output type: Text

Example:

{{ "I strained to see the train through the rain!" | remove_first: "rain" }}

Outputs

I sted to see the train through the rain!

🗒 The Liquid documentation has nothing to say about whether the text to be removed is searched for case sensitively. The rpt implementation assumes case is significant.

replace

⛔ Replaces every occurrence in input of the text in the first argument with the text in the second argument.

Parameters:

  1. Text to be replaced, type Textish
  2. Text to be used as replacement, type Textish

Input type: Textish

Output type: Text

Example

{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}

Outputs

Take your protein pills and put your helmet on

🗒 The Liquid documentation has nothing to say about whether the text to be replaced is searched for case sensitively. The rpt implementation assumes case is significant.

replace_first

⛔ Replaces only the first occurrence in input of the text in the first argument with the text in the second argument.

Parameters:

  1. Text to be replaced, type Textish
  2. Text to be used as replacement, type Textish

Input type: Textish

Output type: Text

Example

{{ "Take my protein pills and put my helmet on" | replace_first: "my", "your" }}

Outputs

Take your protein pills and put my helmet on

🗒 The Liquid documentation has nothing to say about whether the text to be replaced is searched for case sensitively. The rpt implementation assumes case is significant

rstrip

⛔ Removes all whitespace (tabs, spaces, and newlines) from the right side of input text. It does not affect spaces between words.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "          So much room for activities          " | rstrip }}!

Output

          So much room for activities!

round

⛔ Rounds an input Float off to the nearest whole number or, if an argument is provided, to the specified number of decimal places.

Parameter: number of decimal places to round to (optional: default is 0), Type Int.

Input type: Floatish

Output type: Int

Example:

{{ 1.2 | round }}
{{ 2.7 | round }}
{{ 183.357 | round: 2 }}

Output:

1
3
183.36

strip

⛔ Removes all whitespace (tabs, spaces, and newlines) from both the left and right sides of input text. It does not affect spaces between words.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "          So much room for activities          " | strip }}!

Output

So much room for activities!

strip_newlines

Removes any newline characters (line breaks) from the input string.

🗒 In the rpt implementation any of the newline sequences \n, \r & \r\n are removed.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "Alice\r\nand\nBob"|}}

Outputs

AliceandBob

times

⛔ Multiplies the number given as a parameter by the input number and outputs the result.

Parameter: number to be multiplied by input, type Numeric.

Input type: Numeric

Output type: Int if both the input and parameter are Int, otherwise Float.

Example:

{{ 3 | times: 2 }}
{{ 24.7 | times: 7.3 }}
{{ 183.357 | times: 12 }}

Outputs

6
180.31
2200.284

truncate

Shortens a string down to the number of characters passed as the first parameter. If the specified number of characters is less than the length of the string, the text specified in the second parameter is appended to the string and is included in the character count.

The second parameter can be omitted, in which case an ellipsis is appended.

The display of any trailing characters can be avoided by passing an empty string as the second parameter.

🗒 The Liquid documentation describes the default appendix as the ellipsis character (…), but the related example shows the default ellipsis as being composed of 3 dots (...). The rpt implementation follows that example and uses 3 dot characters by default. The 4th line of the example below shows the true ellipsis character being used.

Example:

{{ "Ground control to Major Tom." | truncate: 20 }}
{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}
{{ "Ground control to Major Tom." | truncate: 20, "" }}
{{ "Ground control to Major Tom." | truncate: 20, "…" }}

Outputs

Ground control to...
Ground control, and so on
Ground control to Ma
Ground control to M…

truncatewords

Shortens a string down to the number of words passed as the first parameter. If the specified number of words is less than the number of words in the string, the text specified in the second parameter is appended to the string.

The second parameter can be omitted, in which case an ellipsis is appended.

The display of any trailing characters can be avoided by passing an empty string as the second parameter.

🗒 The Liquid documentation describes the default appendix as the ellipsis character (…), but the related example shows the default ellipsis as being composed of 3 dots (...). The rpt implementation follows that example and uses 3 dot characters by default. The 4th line of the example below shows the true ellipsis character being used.

Example:

{{ "Ground control to Major Tom." | truncatewords: 3 }}
{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}
{{ "Ground control to Major Tom." | truncatewords: 3, "" }}
{{ "Ground control to Major Tom." | truncatewords: 3, " …" }}

Outputs

Ground control to...
Ground control to--
Ground control to
Ground control to …

upcase

⛔ Converts each character of text from the input into upper case.

Any type other than text is first converted to text and then processed.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "Parker Moore" | upcase }}
{{ "APPLE" | upcase }}

Outputs

PARKER MOORE
APPLE

url_decode

⛔ Decodes a string that has been encoded as a URL.

Spaces are decoded correctly regardless of whether they were encoded as + or %20.

Parameters: none

Input type: Textish

Output type: Text

Example:

{{ "%27Go%21%27+said+Alice" | url_decode }}
{{ "%27Stop%21%27%20said%20Bob" | url_decode }}

Outputs

'Go!' said Alice
'Stop!' said Bob

url_encode

⛔ Converts any URL-unsafe characters in a string into percent-encoded characters, except that spaces are encoded into + signs instead of being percent-encoded.

Parameters: none

Input type: Textish

Output type: Text

{{ "[email protected]" | url_encode }}
{{ "Tetsuro Takara" | url_encode }}

john%40example.com
Tetsuro+Takara
Clone this wiki locally