PHPTAL comes with some basic expression modifiers (not:, exists:, string:, php:, path:).
These modifiers are defined by ZPT specifications but PHPTALES can be extended with your own modifiers to manipulate strings, date, money numbers, objects, whatever…
The aim of a modifier is to return some PHP code that will be included in the template PHP source.
Modifiers are used at parse time. If you change the behavior of a modifier, you'll have to delete generated PHP files and reparse all templates using it.
Please note that modifiers produce code, and mustn't echo data!
Any PHP function starting with "phptal_tales_" is usable as a modifier.
Modifiers takes two arguments:
$src: the source string after the "modifier:" keyword
$nothrow: a boolean which determines whether exceptions may be thrown or not by phptal_path() resolution. This boolean must be propagated whenever you call another phptal_tales_ modifier from within your own modifier.*
For example, in the following TAL template,
<span tal:replace="some-modifier: my/path/value"/>
The src argument will be "my/path/value", and the $nothrow boolean will be false, because tal:replace requires the path to be fully resolvable.
An expression like:
<span tal:replace="some-modifier: my/path/value | other/path"/>
Will use 2 modifiers:
some-modifier: with "my/path/value" as $src argument and $nothrow set to true because an alternative exists
path: with "other/path" as $src, and $nothrow set to false because in case the alternative is not found, tal:replace will be in trouble.
Remember, path: is the implicit modifier used when no other modifier is specified.
Modifiers can use other modifiers to generate simpler PHP code. The example below shows this.
//
// This modifier will return a money formated string (XXX.XX)
//
// usage:
//
// money: path/to/my/amount
//
// this modifier uses phptal_tales() function to generate the
// PHP code that will return the value of the modifier argument.
//
// in the example:
//
// money: path/to/my/amount
//
// the produced code will be something looking like:
//
// sprintf("%01.2f", phptal_path($ctx->path, "to/my/amount"))
//
// This code will be included right into the template where needed.
//
// @param string $src
// The expression string
// @param string $nothrow
// A boolean indicating if exceptions may be throw by phptal_path if
// the path does not exists.
// @return string
// PHP code to include in the template
//
function phptal_tales_money( $src, $nothrow )
{
// remove spaces we do not require here
$src = trim($src);
return 'sprintf("%01.2f", '.phptal_tales($src, $nothrow).')';
}