-
Notifications
You must be signed in to change notification settings - Fork 0
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.
⛔ 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
⛔ 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
⛔ 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
⛔ 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
⛔ 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
⛔ 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
⛔ 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
⛔ 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:
- The default value to use, type Any.
- 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
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. is not defined, so the default value is used. product_price
is then given a value so that value. 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
.
⛔ 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:
-
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 }} }}
-
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 }}
-
👀 See also the less complicated rpt
div
(integer division) anddivide
(floating point division) filters.
⛔ 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
⛔ 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.
escape
will escape the introductory &
characters of HTML entities. To avoid this use escape_once
instead.
🗒️ rpt implementation notes:
- 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.
- Like Liquid,
'
is used for single quotes to avoid a potential problem using the symbolic entity'
with Internet Explorer 🙁.
Parameters: none
Input type: Textish
Output type: Text
Example:
{{ "Have you read 'James & the Giant Peach'?" | escape }}
{{ "Tetsuro Takara" | escape }}
{{ "A & B" | escape }}
Outputs
Have you read 'James & the Giant Peach'?
Tetsuro Takara
A &amp; B
⛔ 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:
- 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.
- Like Liquid,
'
is used for single quotes to avoid a potential problem using the symbolic entity'
with Internet Explorer 🙁. - Only those symbolic entities defined by W3C are preserved.
- Symbolic entities that omit the terminal
;
character are not preserved. - All decimal and hexadecimal numeric entities are preserved.
Parameters: none
Input type: Textish
Output type: Text
Examples:
{{ "1 < 2 & 3" | escape_once }}
{{ "1 < 2 & 3" | escape_once }}
Outputs
1 < 2 & 3
1 < 2 & 3
⛔ 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
⛔ 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 !
⛔ 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
⛔ 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
👀 See also the similar rpt mod
filter.
⛔ 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
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" }}
⛔ 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
⛔ 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
⛔ 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.
⛔ 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.
⛔ Replaces every occurrence in input of the text in the first argument with the text in the second argument.
Parameters:
- Text to be replaced, type Textish
- 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.
⛔ Replaces only the first occurrence in input of the text in the first argument with the text in the second argument.
Parameters:
- Text to be replaced, type Textish
- 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
⛔ 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!
⛔ 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
⛔ 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!
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
⛔ 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
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…
⛔ 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