Pipes - Transform Output with Functions

Pipes allow you to pass output through functions to transform it. Use the pipe symbol | followed by a function name to process data.

Two Ways to Use Pipes

1. Variable Pipes

Apply functions to a variable with {$variable | function} - the field tag runs the sanitize chain on the result - or with {echo $variable | function}, which prints it raw, as the examples on this page do:

PHP
fragments/pipes_1.php 		HTML
fragments/pipes_1.pad 		Result 
<?php

  $name = 'john doe';
  $email = 'ALICE@EXAMPLE.COM';
  $price = 1234.56;

?>
 
<p>Original: {$name}</p>
<p>Uppercase: {echo $name | upper}</p>
<p>Capitalize: {echo $name | ucwords}</p>

<p>Original: {$email}</p>
<p>Lowercase: {echo $email | lower}</p>

<p>Original: {$price}</p>
<p>Formatted: {echo $price | number_format(@, 2)}</p>

Original: john doe

Uppercase: JOHN DOE

Capitalize: John Doe

Original: ALICE@EXAMPLE.COM

Lowercase: alice@example.com

Original: 1234.56

Formatted: 1,234.56

2. Tag Pipes

Apply functions to tag output. Pipes can be placed on the opening tag or closing tag:

PHP
fragments/pipes_2.php 		HTML
fragments/pipes_2.pad 		Result 
<?php

  $items = ['apple', 'banana', 'cherry'];

?>
 
<p>Items separated by commas:</p>
<p>{items print, glue=", "}</p>

<p>Items in uppercase:</p>
<ul>
  {items}
    <li>{$items}</li>
  {/items | upper}
</ul>

Items separated by commas:

apple, banana, cherry

Items in uppercase:

  • APPLE
  • BANANA
  • CHERRY

Pipe Timing: Opening vs Closing Tag

The placement of the pipe determines when the function is applied:

An opening pipe is therefore not a way to reorder or filter what a tag iterates: a field written inside the content would be transformed along with everything else, and then not resolve. Reshaping the data is what the data handling options are for.

PHP
 HTML
fragments/pipes_4.pad 		Result 
{data 'words'}("alpha","beta"){/data}

<p>Closing tag pipe - handed everything the tag rendered: [{words}{$words} {/words | upper}]</p>
<p>Opening tag pipe - handed the content template, which then repeats: [{words | upper}row {/words}]</p>

Closing tag pipe - handed everything the tag rendered: [ALPHA BETA ]

Opening tag pipe - handed the content template, which then repeats: [ROW ROW ]

Chaining Pipes

Chain multiple pipe functions together by separating them with |. Functions are applied left to right:

PHP
fragments/pipes_3.php 		HTML
fragments/pipes_3.pad 		Result 
<?php

  $rawText = '  hello world  ';
  $message = 'the quick brown fox';

?>
 
<p>Chain multiple pipes together:</p>

<p>Original: [{$rawText}]</p>
<p>Trimmed and uppercase: [{echo $rawText | trim | upper}]</p>

<p>Original: {$message}</p>
<p>Uppercase first letter of each word: {echo $message | ucwords}</p>
<p>Replace and capitalize each word: {echo $message | replace('fox', 'dog') | ucwords}</p>

Chain multiple pipes together:

Original: [ hello world ]

Trimmed and uppercase: [HELLO WORLD]

Original: the quick brown fox

Uppercase first letter of each word: The Quick Brown Fox

Replace and capitalize each word: The Quick Brown Dog

Presentation helpers

truncate shortens on a whole word, slug makes a readable URL part, bytes writes a size for people, and escape writes a value for the context it lands in - html, attr, js, css or url:

PHP
fragments/pipes_5.php 		HTML
fragments/pipes_5.pad 		Result 
<?php

  $intro = 'The quick brown fox jumps over the lazy dog, twice before breakfast';
  $title = 'Crème Brûlée & Co.';
  $size  = 3221225472;
  $quote = 'it\'s </script>';

?>
 
<p>{$intro | truncate(30)}</p>
<p>?page={$title | slug}</p>
<p>{$size | bytes}</p>
<p>{$quote | escape('js')}</p>

The quick brown fox jumps…

?page=creme-brulee-co

3 GB

it\x27s\x20\x3C\x2Fscript\x3E

Common Pipe Functions

Function Description Example
upper Convert to uppercase {echo $text | upper}
lower Convert to lowercase {echo $text | lower}
ucwords Capitalize each word {echo $text | ucwords}
trim Remove whitespace {echo $text | trim}
html HTML encode {echo $text | html}
replace(a,b) Replace text {echo $text | replace('old','new')}
+ n Add number {echo $count | + 1}
date(fmt) Format date {echo $timestamp | date('Y-m-d')}

Important Rules

When to Use Opening vs Closing Tag Pipes

Use Case Placement Example
Transform the content template before it repeats Opening tag {items | trim}...{/items}
Reshape the data itself Option, not a pipe {items sort}...{/items}
Transform final output after rendering Closing tag {tag}...{/tag | upper}
Format variable values Variable pipe {echo $price | number_format(@, 2)}

See Also