.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dancer2::Template::TemplateToolkit 3pm"
.TH Dancer2::Template::TemplateToolkit 3pm "2021-03-13" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dancer2::Template::TemplateToolkit \- Template toolkit engine for Dancer2
.SH "VERSION"
.IX Header "VERSION"
version 0.300005
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
To use this engine, you may configure Dancer2 via \f(CW\*(C`config.yaml\*(C'\fR:
.PP
.Vb 1
\&    template:   "template_toolkit"
.Ve
.PP
Or you may also change the rendering engine on a per-route basis by
setting it manually with \f(CW\*(C`set\*(C'\fR:
.PP
.Vb 2
\&    # code code code
\&    set template => \*(Aqtemplate_toolkit\*(Aq;
.Ve
.PP
Most configuration variables available when creating a new instance of a
Template::Toolkit object can be declared inside the template toolkit
section on the engines configuration in your config.yml file.  For example:
.PP
.Vb 5
\&  engines:
\&    template:
\&      template_toolkit:
\&        start_tag: \*(Aq<%\*(Aq
\&        end_tag:   \*(Aq%>\*(Aq
.Ve
.PP
(Note: \f(CW\*(C`start_tag\*(C'\fR and \f(CW\*(C`end_tag\*(C'\fR are regexes.  If you want to use PHP-style
tags, you will need to list them as \f(CW\*(C`<\e?\*(C'\fR and \f(CW\*(C`\e?>\*(C'\fR.)
See Template::Manual::Config for the configuration variables.
.PP
In addition to the standard configuration variables, the option \f(CW\*(C`show_private_variables\*(C'\fR
is also available. Template::Toolkit, by default, does not render private variables
(the ones starting with an underscore). If in your project it gets easier to disable
this feature than changing variable names, add this option to your configuration.
.PP
.Vb 1
\&        show_private_variables: true
.Ve
.PP
\&\fBWarning:\fR Given the way Template::Toolkit implements this option, different Dancer2
applications running within the same interpreter will share this option!
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This template engine allows you to use Template::Toolkit in Dancer2.
.SH "METHODS"
.IX Header "METHODS"
.SS "render($template, \e%tokens)"
.IX Subsection "render($template, %tokens)"
Renders the template.  The first arg is a filename for the template file
or a reference to a string that contains the template. The second arg
is a hashref for the tokens that you wish to pass to
Template::Toolkit for rendering.
.SH "ADVANCED CUSTOMIZATION"
.IX Header "ADVANCED CUSTOMIZATION"
Template::Toolkit allows you to replace certain parts, like the internal
\&\s-1STASH\s0 (Template::Stash). In order to do that, one usually passes an object of another
implementation such as Template::Stash::AutoEscaping into the constructor.
.PP
Unfortunately that is not possible when you configure Template::Toolkit from
your Dancer2 configuration file. You cannot instantiate a Perl object in a yaml file.
Instead, you need to subclass this module, and use the subclass in your configuration file.
.PP
A subclass to use the aforementioned Template::Stash::AutoEscaping might look like this:
.PP
.Vb 2
\&    package Dancer2::Template::TemplateToolkit::AutoEscaping;
\&    # or MyApp::
\&    
\&    use Moo;
\&    use Template::Stash::AutoEscaping;
\&    
\&    extends \*(AqDancer2::Template::TemplateToolkit\*(Aq;
\&    
\&    around \*(Aq_build_engine\*(Aq => sub {
\&        my $orig = shift;
\&        my $self = shift;
\&    
\&        my $tt = $self\->$orig(@_);
\&    
\&        # replace the stash object
\&        $tt\->service\->context\->{STASH} = Template::Stash::AutoEscaping\->new(
\&            $self\->config\->{STASH}
\&        );
\&    
\&        return $tt;
\&    };
\&    
\&    1;
.Ve
.PP
You can then use this new subclass in your config file instead of \f(CW\*(C`template_toolkit\*(C'\fR.
.PP
.Vb 8
\&    # in config.yml
\&    engines:
\&      template:
\&        TemplateToolkit::AutoEscaping:
\&          start_tag: \*(Aq<%\*(Aq
\&          end_tag:   \*(Aq%>\*(Aq
\&          # optional arguments here
\&          STASH:
.Ve
.PP
The same approach should work for \s-1SERVICE\s0 (Template::Service), \s-1CONTEXT\s0 (Template::Context),
\&\s-1PARSER\s0 (Template::Parser) and \s-1GRAMMAR\s0 (Template::Grammar). If you intend to replace
several of these components in your app, it is suggested to create an app-specific subclass
that handles all of them at the same time.
.SS "Template Caching"
.IX Subsection "Template Caching"
Template::Tookit templates can be cached by adding the \f(CW\*(C`COMPILE_EXT\*(C'\fR property to your
template configuration settings:
.PP
.Vb 7
\&    # in config.yml
\&    engines:
\&      template:
\&        template_toolkit:
\&          start_tag: \*(Aq<%\*(Aq
\&          end_tag:   \*(Aq%>\*(Aq
\&          COMPILE_EXT: \*(Aq.tcc\*(Aq # cached file extension
.Ve
.PP
Template caching will avoid the need to re-parse template files or blocks each time they are
used. Cached templates are automatically updated when you update the original template file.
.PP
By default, cached templates are saved in the same directory as your template. To save
cached templates in a different directory, you can set the \f(CW\*(C`COMPILE_DIR\*(C'\fR property in your
Dancer2 configuration file.
.PP
Please see \*(L"Caching_and_Compiling_Options\*(R" in Template::Manual::Config for further
details and more caching options.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Dancer2, Dancer2::Core::Role::Template, Template::Toolkit.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2021 by Alexis Sukrieh.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.