/ 
Dancer2-Template-TextTemplate-1.003
River stage zero No dependents
/ Dancer2::Template::TextTemplate

NAME

Dancer2::Template::TextTemplate - Text::Template engine for Dancer2

VERSION

version 1.003

SYNOPSIS

To use this engine, you may configure Dancer2 via config.yml:

template: text_template

DESCRIPTION

This template engine allows you to use Text::Template in Dancer2.

Configuration

Here are all available options, as you would set them in a config.yml, with their default values:

template: text_template
engines:
    text_template:
        caching: 1
        expires: 3600               # in seconds; use 0 to disable
        cache_stringrefs: 1
        delimiters: [ "{", "}" ]
        prepend: |
            use strict;
            use warnings;
        safe: 1
        safe_opcodes: [ ":default", ":load" ]
        safe_disposable: 0

The following sections explain what these options do.

Global caching - caching, expires

Contrary to other template engines (like Template::Toolkit), where one instance may work on multiple templates, one Text::Template instance is created for each template. Therefore, if:

  • you don't use a huge amount of different templates;

  • you don't use each template just once;

then it may be interesting to cache Text::Template instances for later use. Since these conditions seem to be common, this engine uses a cache (via CHI) by default.

If you're OK with caching, you should specify a timeout (expires) after which cached Text::Template instances are to be refreshed, since you might have changed your template sources without restarting Dancer2. By default, this engine uses expires: 3600 (one hour). Use 0 to tell it that templates never expire.

If you don't want any caching, just set caching to 0.

"String-ref templates" caching - cache_stringrefs

Just like with Dancer2::Template::Toolkit, you can pass templates either as filenames (for a template file) or string references ("string-refs", which are dereferenced and used as the template's content). In some cases, you may want to disable caching for string-refs only: for instance, if you generate a lot of templates on-the-fly and use them only once, caching them is useless and fills your cache. You can therefore disable caching for string-refs only by setting cache_stringrefs to 0.

Note that if you set caching to 0, you don't have any caching, so cache_stringrefs is ignored.

Custom delimiters - delimiters

The delimiters option allows you to specify a custom delimiters pair (opening and closing) for your templates. See the Text::Template documentation for more about delimiters, since this module just pass them to Text::Template. This option defaults to { and }, meaning that in a {b} c, b (and only b) will be interpolated.

Prepending code - prepend

This option specifies Perl code run by Text::Template before evaluating each template. For instance, with this option's default value, i.e.:

use strict;
use warnings FATAL => 'all';

then evaluating the following template:

you're the { $a + 1 }th visitor!

is the same as evaluating:

{
    use strict;
    use warnings FATAL => 'all';
    ""
}you're the { $a + 1 }th visitor!

and thus you'd get:

Program fragment delivered error
``Use of uninitialized value $a in addition (+) [...]

in your template output if you forgot to pass a value for $a.

If you don't want anything prepended to your templates, simply give a non-dying, side-effects-free Perl expression to prepend, like 0 or "".

Running in a Safe - safe, safe_opcodes, safe_disposable

This option (enabled by default) makes your templates to be evaluated in a Safe compartment, i.e. where some potentially dangerous operations (such as system) are disabled. Note that the same Safe compartment will be used to evaluate all your templates, unless you explicitly specify safe_disposable: 1 (one compartment per template evaluation).

This Safe uses the :default and :load opcode sets (see the Opcode documentation), unless you specify it otherwise with the safe_opcodes option. You can, of course, mix opcodes and optags, as in:

safe_opcodes:
    - ":default"
    - "time"

which enables the default opcode set and time. But be careful: with the previous example for instance, you don't allow require, and thus break the default value of the prepend option (which contains use)!

METHODS

render( $template, \%tokens )

Renders the template.

  • $template is either a (string) filename for the template file or a reference to a string that contains the template.

  • \%tokens is a hashref for the tokens you wish to pass to Text::Template for rendering, as if you were using Text::Template::fill_in.

Carps if an error occurs.

AUTHOR

Thibaut Le Page <thilp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Thibaut Le Page.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.