API

The open API allows you to extend the functionality of the template processor by plugging in your own modules.

The `Dynamic::View` Interface#

Call From Templates#

Plug-Ins in the namespace Dynamic::View are accessible as template instructions. If your plug-in is called smellovision::steam, you can use it like this in a template:

{% ##smellovision::steam(arg1, arg2, ...) %}
{% #smellovision::steam(arg1, arg2, ...) %}
Arbitrary template code...
{% #end %}

The first call is without a body, the second with a body.

Your plug-in must implement the following methods:#

new#

The constructor must return a reference to your object. It is called without arguments.

render(VIEW, ARGS)#

The method render will be called at least with one argument, followed by an optional list of arguments that were passed to your call in the template. These optional arguments are already evaluated by the template processor.

The first argument is the Imperia::View::PlugIn object, that represents the plug-in call. The object has two interesting protected properties, that you might need:

_data: This property contains the data hash with all known variables.
_embedded: If your plug-in call has a body, then this property is the Imperia::View object with the compiled template. If you want to get the rendered output, you have to do as follows:

... my $view = $_[1]; my $data = $view->{_data}; my $embedded = $view->{_embedded}; die “Plug-In called without body!\n” unless $embedded; my $rendered_body = $embedded->render($data); ...

Error Reporting#

You should report errors by simply throwing an exception with die().

The `ViewImport` API#

If you want to add new functions you have to write a Dynamic::ViewImport plug-in.

Interface#

Your plug-in must implement the following methods:

new()#

The constructor must return a reference to your object. It is called without arguments.

exports()#

This method must return a reference to the list of names of the functions that your module defines.

getCode(functionname)#

This method must return a code reference that defines the function of the specified name.

isSafe(functionname, context)#

This function must return a truth value, if the function is considered to produce “safe” output, in the particular environment used. Otherwise it should return a false value or die.

Inheritance#

You can safe a lot of work, by subclassing from Imperia::View::Import. You just have to provide one constant method then, all other methods can be inherited from the base class. A very simple plug-in could look like this then:

package Dynamic::View::MySpace::Strings;
use strict;
use constant EXPORTS => {
    lower => {
        code => sub { lc shift },
},
upper => {
    code => sub { uc shift },
},
vaporize => {
    code => sub { return '' },
    safe => 1,
    },
};
1;

For every function your plug-in defines, you just give the code reference and say whether the function is considered safe or not.

API

The Dynamic::View Interface#