Prev |  | Next

## Creating custom expression modifiers

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).')';
    }

Prev | Up | Next
Working with gettext | Home | Appendix A. Note for system administrators