Pipe functions let you modify the value of a variable in place before it is rendered. The pipe | passes the value of a variable as input to a pipe function. Multiple pipe functions can be chained, so that the output of one function is used as the input for the next one. Besides pipe functions, basic mathematical operations can be used in the same way.
@{ variable | function }
@{ variable | function (parameter) | anotherFunction }Parameters
Some pipe functions 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, ' ...') }Pipe functions 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 pipe function. Passing a number instead of a function 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 pipe function.
@{ 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 }Pipe functions 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 Pipe Functions
The following pipe functions are available out of the box. Follow the links for a detailed description of their parameters.
| Function | 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 Pipe Functions
In case the built-in pipe functions are not enough, you can develop your own custom pipe functions as extensions using PHP. Custom pipe functions are used just like any other pipe function by passing the namespace and the name of the extension:
@{ variable | Vendor/Name (parameter) }