Filters let you modify the value of a variable in place before it is rendered. A pipe | passes the value of a variable as input to a filter. Multiple filters can be chained, so that the output of one filter is used as the input for the next one. Besides filters, basic mathematical operations can be used in the same way.
@{ variable | filter }
@{ variable | filter (parameter) | anotherFilter }Parameters
Some filters accept optional parameters, which are wrapped in parentheses and separated by commas. Parameters can be numbers, strings, booleans or even other variables.
@{ text | markdown (true) }
@{ text | shorten (100, ' ...') }Filters can also be applied to variables that are themselves used as parameters:
@{ date | dateFormat (@{ format | def ('Y') }) }Strings can be wrapped in single quotes as well as in double quotes. Both examples below produce the same output:
<# Output: This is a "Test String" #>
@{ text | def ('This is a "@{ variable }"') }
@{ text | def ("This is a \"@{ variable }\"") }Variables that are used as parameters only need to be quoted when they are combined with other strings. When using a variable on its own, quotes can be omitted:
@{ text | def (@{ variable }) }Shortening Text
There is a special shorthand syntax for the shorten filter. Passing a number as filter name shortens the value of a variable to that maximum number of characters without cutting words.
@{ text | 100 }Mathematical Operations
Mathematical operations are limited to elementary arithmetic — addition +, subtraction -, multiplication * and division /. Operations can be chained like any other filter.
@{ variable | +1 }
@{ variable | /2 | -5 | *2 }Other variables can be used as operands as well. The following example first falls back to the value of x in case variable is not defined. In a second step, the value of y or a default of 5 is added:
@{ variable | def (@{ x }) | +@{ y | def (5) } }Examples
The following example first strips all HTML tags from the first paragraph of the +main blocks and then shortens the text to 150 characters:
@{ +main | findFirstParagraph | stripTags | 150 }Filters are also useful to build values for attributes. Here, the template name is converted into a valid class name:
<div class="layout layout--@{ template | sanitize }">Available Filters
The following filters are available out of the box. Follow the links for a detailed description of their parameters.
| Filter | Description |
|---|---|
| ceil | Rounds a number up to the next highest integer. |
| dateFormat | Formats and optionally translates a date. |
| def | Defines a default value for empty variables. |
| escape | Escapes a value to be used in JSON strings. |
| findFirstImage | Finds the first image in a block or HTML value. |
| findFirstParagraph | Finds the first paragraph in a block or HTML value. |
| floor | Rounds a number down to the next lowest integer. |
| markdown | Converts Markdown to HTML. |
| match | Tests a value against a regular expression. |
| replace | Replaces matches of a regular expression. |
| round | Rounds a number. |
| sanitize | Converts a value into a URL and class name safe string. |
| shorten | Shortens a text to a maximum number of characters. |
| stripEnd | Removes a string from the end of a value. |
| stripStart | Removes a string from the start of a value. |
| stripTags | Removes all HTML tags. |
| strlen | Returns the length of a value. |
| strtolower | Converts a value to lowercase. |
| strtoupper | Converts a value to uppercase. |
| ucwords | Capitalizes the first character of each word. |
Custom Filters
In case the built-in filters are not enough, you can develop your own custom filters as extensions using PHP. Custom filters are used just like any other filter by passing the namespace and the name of the extension:
@{ variable | Vendor/Filter (parameter) }