Template Filters in Perch 3

One requirement we sometimes see with Perch is where some manipulation needs to be performed on a value in a template before it is output.

Perch template tags have options like the format attribute (for formatting common values like numbers, currency, file sizes and letter cases), words and chars for truncation, the replace attribute for substitution and so on. But what about those cases where the transformation you need to perform is completely custom, or simply isn’t covered?

At the moment in Perch 2, the way to tackle those situations is to fetch the data to the page, manipulate it in PHP, and then pass it back into the template. That works, but it’s not very elegant.

Introducing Template Filters

Perch and Perch Runway 3 has a new type of add-on called Template Filters. When a filter is applied to a template tag, the value is passed through the filter and the result is used on the page.

This is best illustrated with an example. Let’s say you wanted to be able to flip the content of a field so that the entered text is displayed in reverse order. If the user enters “Hello” into a field, I want to output “olleH" instead. (We’ll not reason why.)

To do this, we might install a filter called “reverse” and apply it to the tag like this:

<perch:content id=“heading” type=“text” filter=“reverse” />

Now when the heading it output, the letters will be passed through the filter and output in the reverse order.

Creating a filter

So where did this reverse filter come from? Perch doesn’t ship with a ‘reverse’ filter, but that doesn’t matter because if you know any PHP they’re really easy to create. You can either create your own, or download and install filters that other Perchers might share with you.

Here’s the source code for our reverse filter:

class PerchTemplateFilter_reverse extends PerchTemplateFilter 
{
	public function filterAfterProcessing($value, $valueIsMarkup = false)
	{
		return strrev($value);
	}
}

PerchSystem::register_template_filter('reverse', 'PerchTemplateFilter_reverse');

We’re defining a class that extends PerchTemplateFilter, and defining the filterAfterProcessing() method. That’s where the manipulation is applied and the value returned. In this case the flipping is done with the PHP strrev() function.

There are two places filters can be applied. filterBeforeProcessing runs before attributes like format and chars are processed, and filterAfterProcessing runs after. All processing is carried out before the HTML encoding is done, but if the filter results in output that is already encoded there’s a way to declare this so the output isn’t double-encoded.

Filters also have access to all the content fields being templated, as well as access to the template tag and all its attributes. This means that if a filter needs more options setting, those can be done with the use of attributes.

Multiple filters can be applied to a tag, and they’re processed in the order they’re declared

filter=“reverse translate rainbowify”

That’s template filters

There are lots of things you can use filters for, with basic string manipulation being the most straightforward. With access to the template tag and content values, there’s bound to be lots of creative uses far and beyond this. For example, we created a quick filter that sums the values of numbers in other fields and displays the result.

We hope that template filters will prove a useful tool in keeping control of content in your Perch and Runway 3 sites, as well as being a quick and easy add-on you can create and share with your fellow developers.