.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 "Dancer::Template::TemplateToolkit 3pm"
.TH Dancer::Template::TemplateToolkit 3pm "2018-12-23" "perl v5.28.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"
Dancer::Template::TemplateToolkit \- Template Toolkit wrapper for Dancer
.SH "VERSION"
.IX Header "VERSION"
version 1.3500
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is an interface between Dancer's template engine abstraction layer
and the Template module.
.PP
This template engine is recommended for production purposes, but depends on the
Template module.
.PP
In order to use this engine, use the template setting:
.PP
.Vb 1
\&    template: template_toolkit
.Ve
.PP
This can be done in your config.yml file or directly in your app code with the
\&\fBset\fR keyword.
.PP
Note that by default,  Dancer configures the Template::Toolkit engine to use
<% %> brackets instead of its default [% %] brackets.  This can be changed
within your config file \- for example:
.PP
.Vb 5
\&    template: template_toolkit
\&    engines:
\&        template_toolkit:
\&            start_tag: \*(Aq[%\*(Aq
\&            stop_tag: \*(Aq%]\*(Aq
.Ve
.PP
You can also add any options you would normally add to the Template module's
initialization. You could, for instance, enable saving the compiled templates:
.PP
.Vb 4
\&    engines:
\&        template_toolkit:
\&            COMPILE_DIR: \*(Aqcaches/templates\*(Aq
\&            COMPILE_EXT: \*(Aq.ttc\*(Aq
.Ve
.PP
Note though that unless you change them, Dancer sets both of the Template
options \f(CW\*(C`ANYCASE\*(C'\fR and \f(CW\*(C`ABSOLUTE\*(C'\fR on, as well as pointing \f(CW\*(C`INCLUDE_PATH\*(C'\fR
to your \fBviews\fR directory and setting \f(CW\*(C`ENCODING\*(C'\fR to your \fBcharset\fR
setting.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
By default, Template is used, but you can configure Dancer to use a
subclass of Template with the \f(CW\*(C`subclass\*(C'\fR option.
.PP
.Vb 3
\&    engines:
\&        template_toolkit:
\&            subclass: My::Template
.Ve
.PP
When used like this, Dancer skips the defaults mentioned above.  Only those
included in your config file are sent to the subclass.
.SH "WRAPPER, META variables, SETs"
.IX Header "WRAPPER, META variables, SETs"
Dancer already provides a WRAPPER-like ability, which we call a \*(L"layout\*(R". The
reason we do not use \s-1TT\s0's \s-1WRAPPER\s0 (which also makes it incompatible with it) is
because not all template systems support it. Actually, most don't.
.PP
However, you might want to use it, and be able to define \s-1META\s0 variables and
regular Template::Toolkit variables.
.PP
These few steps will get you there:
.IP "\(bu" 4
Disable the layout in Dancer
.Sp
You can do this by simply commenting (or removing) the \f(CW\*(C`layout\*(C'\fR configuration
in the \fIconfig.yml\fR file.
.IP "\(bu" 4
Use Template Toolkit template engine
.Sp
Change the configuration of the template to Template Toolkit:
.Sp
.Vb 2
\&    # in config.yml
\&    template: "template_toolkit"
.Ve
.IP "\(bu" 4
Tell the Template Toolkit engine who's your wrapper
.Sp
.Vb 5
\&    # in config.yml
\&    # ...
\&    engines:
\&        template_toolkit:
\&            WRAPPER: layouts/main.tt
.Ve
.PP
Done! Everything will work fine out of the box, including variables and \s-1META\s0
variables.
.SH "EMBEDDED TEMPLATES"
.IX Header "EMBEDDED TEMPLATES"
You can embed your templates in your script file, to get a self-contained dancer
application in one file (inspired by <http://advent.perldancer.org/2011/3>).
.PP
To enable this:
.PP
.Vb 8
\&    # in app.pl
\&    # ...
\&    set engines => {
\&        template_toolkit => {
\&            embedded_templates => 1,
\&        },
\&    };
\&    set template => \*(Aqtemplate_toolkit\*(Aq;
.Ve
.PP
This feature requires Template::Provider::FromDATA. Put your templates in the
_\|_DATA_\|_ section, and start every template with _\|_${templatename}_\|_.
.SH "USING TT'S WRAPPER STACK"
.IX Header "USING TT'S WRAPPER STACK"
This engine provides three additional methods to access the \s-1WRAPPER\s0 stack of
TemplateToolkit.
.SS "set_wrapper"
.IX Subsection "set_wrapper"
Synopsis:
.PP
.Vb 3
\&    engine(\*(Aqtemplate\*(Aq)\->set_wrapper( inner => \*(Aqinner_layout.tt\*(Aq );
\&    engine(\*(Aqtemplate\*(Aq)\->set_wrapper( outer => \*(Aqouter_layout.tt\*(Aq );
\&    engine(\*(Aqtemplate\*(Aq)\->set_wrapper( \*(Aqonly_layout.tt\*(Aq );
.Ve
.PP
The first two lines pushes/unshifts layout files to the wrapper array.
The third line overwrites the wrapper array with a single element.
.SS "unset_wrapper"
.IX Subsection "unset_wrapper"
Synopsis:
.PP
.Vb 2
\&    engine(\*(Aqtemplate\*(Aq)\->unset_wrapper(\*(Aqinner\*(Aq) # returns \*(Aqinner_layout.tt\*(Aq;
\&    engine(\*(Aqtemplate\*(Aq)\->unset_wrapper(\*(Aqouter\*(Aq) # returns \*(Aqouter_layout.tt\*(Aq;
.Ve
.PP
These lines pops/shifts layout files from the wrapper array and returns the
removed elements.
.SS "reset_wrapper"
.IX Subsection "reset_wrapper"
Synopsis:
.PP
.Vb 1
\&    engine(\*(Aqtemplate\*(Aq)\->reset_wrapper;
.Ve
.PP
This method restores the wrapper array after a set_wrapper call.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Dancer, Template
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 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.