Outlast

Custom tags and filters

You can extend the functionality of the template system by creating your own tags and filters. Below is a quick overview of your options.

However, before you begin it’s a good idea to review the documentation and ensure the tag or filter is already not available.

Quick start (if you know what you’re doing)

Custom tags and filters can be loaded at runtime using the following code:

$this->zajlib->compile->register_tags('name_of_tags_file');
$this->zajlib->compile->register_filters('name_of_filters_file');

The tag and filter files can be placed in any plugin folder under /tags/name_of_tags_file.tags.php (or filters/name_of_filters_file.filters.php). The contents of the tag and filter files should be exactly the same as the system default files which can be found under /system/plugins/tags/*.tags.php (or /system/plugins/filters/*.filters.php). Just rename the class, create your custom methods, and you’re good to go! Each file can contain as many tags or filters as you wish to add – one tag/filter is represented by each class method.

The basics of custom tags and filters

Tags and filters can be used in Outlast Framework template files to perform certain built-in functions. With custom tags and filters, you can essentially import any functionality into the template system – though careful consideration should be given so as to preserve the separation of program logic and display output fundamental to the MVC design pattern.

The difference between tags and filters?

Tags are functions that control the flow of execution and/or produce output. A good example would be the {% foreach %} tag which replicates the functionality of the similarly named PHP loop.

Filters on the other hand are tiny functions that change the value of a variable just before output. A good example of this is the truncate filter: {{a_very_long_title|truncate:30}} – this will modify the value of a_very_long_title by truncating it to 30 characters just before output. Unlike functions, you can chain filters, like so: {{a_very_long_title|striptags|truncate:30}} – here the actions will be performed in order from left to right.

The basics of creating your own tags and filters

Outlast Framework compiles template files by converting everything into PHP code. This is done once per file change and the result is cached to speed up execution. When a template tag or filter is encountered, Outlast Framework searches for the implementation object, retrieves the code from the proper function and writes the result to the cache files where it is needed.

As such, whether you are creating tags or filters, the general idea is that you must write code that generates valid PHP code. This has a number of safety and security implications that we shall discuss below in the examples.

A filter example

Filters are most often used for sanitizing or humanizing content, creating automatic links, formatting items, or any number of other such tasks where existing template variable values are modified just before output.

Let’s take the |truncate example from above. Both filters and tags are defined in special files that can be located in the system folder or any plugins folder. Here’s an example implementation from /plugins/_project/filters/myown.filters.php.

As can be seen from the full example, you must do the following to create your own filter collection:

Create a file in your /plugins/_project/filters/myown.filters.php
In the file, create a class based on the file name zajlib_filter_myown in this case. It must extend zajElementCollection.
Each function you create by the name of filter_filtername will represent a single filter that you will be able to use in your templates.
You will need to generate PHP code that modifies the original value ($filter_var) as needed by the filter
You can use $parameter in your generated code which is either a variable, a string (with quotes around it), or a numeric value.
In the end write the whole code segment to the cache file using $this->zajlib->compile->write(); and return true.
You’ll need to register the filter collection at runtime before you use it in a template. To register a filter collection use $this->zajlib->compile->register_filters('myown');

So how do we generate PHP code in PHP? Here’s a line-by-line explanation of the mentioned simple filter function:

// First, name your function filter_NAME_OF_FILTER
public function filter_truncate($parameter, &$source){
	// If your filter requires a param, you can throw a warning (or error)!
	if(!$parameter) return $source->warning('truncate filter parameter required!');
	// let's generate the code! Take note, that you need valid PHP code within the quotes.
	$code = 'if(strlen($filter_var) > '.$parameter.') $filter_var=mb_substr($filter_var, 0, '.$parameter.')."...";';
	// Now write to the cache file
	$this->zajlib->compile->write($code);
	return true;
}

IMPORTANT! Take extra care when generating PHP code. Improperly escaping user input can result in unsafe PHP code being generated. $parameter is safe to use in the code, but you must assume that all other user input is unsafe for direct use and should be sanitized first.

A tag example

Tags are most often used for displaying output or controlling the flow (such as loops or ifs) of the template.

Creating tags is very similar to filters. Let’s take the {% unique %} example which does nothing more than generates a unique id using PHP’s uniqid() function. Here’s an example implementation from /plugins/_project/tags/myown.tags.php.

As can be seen from the full example, you must do the following to create your own tag collection:

Create a file in your /plugins/_project/tags/myown.tags.php
In the file, create a class based on the file name zajlib_tag_myown in this case. It must extend zajElementCollection.
Each function you create by the name of tag_tagname will represent a single filter that you will be able to use in your templates.
You will need to generate PHP code that outputs something or controls the execution flow.
You can use {$param_array[0]->variable} in your generated code which is either a variable, a string (with quotes around it), or a numeric value.
Naturally, additional parameters will be available using {$param_array[1]->variable}, {$param_array[2]->variable}, etc.
In the end write the whole code segment to the cache file using $this->zajlib->compile->write(); and return true.
You’ll need to register the tag collection at runtime before you use it in a template. To register a tag collection use $this->zajlib->compile->register_tags('myown');

To review, here’s a line-by-line explanation of a filter function. In this implementation the ‘unique’ tag has two acceptable formats {% unique %} (this outputs a unique id generated at runtime) or {% unique some_variable_name %} (this sets a unique id generated at runtime to {{some_variable_name}}.

So let’s see the implementation, line-by-line…

// First, name your function tag_NAME_OF_FILTER
public function tag_unique($param_array, &$source){
	// Does it not have a second parameter? (remember, param_array is 0 indexed)
	if(empty($param_array[1])) $contents = "";
	// If it does have a second parameter, set to that variable
	else $contents = "variable} = uniqid(''); ?>";
	// write to file
	$this->zajlib->compile->write($contents);
	// return true
	return true;
}

IMPORTANT! As with filters, take extra care when generating PHP code. Not properly escaping user input can result in unsafe PHP code being generated. {$param_array[0]->variable} and its peers are safe to use in the code, but you must assume that all other user input is unsafe for direct use and should be sanitized first.

Review

With Outlast Framework you can easily create your own custom tag and filter collections. Each collection is created by adding a specifically named file and object with a function for each tag/filter.

Both tag and filter functions generate PHP code where you must pay special attention to escaping and sanitizing any user input (aside from the built-in variables which are safe to use).

Don’t forget to register your tags as well at runtime!

Finally, if you’re stuck, you can always refer to the base and mozajik tag and filter declaration files in the Outlast Framework system folder.

Template syntax