NAME

       Dancer::Template::TemplateToolkit - Template Toolkit wrapper for Dancer

VERSION

       version 1.3202

DESCRIPTION

       This class is an interface between Dancer's template engine abstraction layer and the
       Template module.

       This template engine is recommended for production purposes, but depends on the Template
       module.

       In order to use this engine, use the template setting:

           template: template_toolkit

       This can be done in your config.yml file or directly in your app code with the set
       keyword.

       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:

           template: template_toolkit
           engines:
               template_toolkit:
                   start_tag: '[%'
                   stop_tag: '%]'

       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:

           engines:
               template_toolkit:
                   COMPILE_DIR: 'caches/templates'
                   COMPILE_EXT: '.ttc'

       Note though that unless you change them, Dancer sets both of the Template options
       "ANYCASE" and "ABSOLUTE" on, as well as pointing "INCLUDE_PATH" to your views directory
       and setting "ENCODING" to your charset setting.

SUBCLASSING

       By default, Template is used, but you can configure Dancer to use a subclass of Template
       with the "subclass" option.

           engines:
               template_toolkit:
                   subclass: My::Template

       When used like this, Dancer skips the defaults mentioned above.  Only those included in
       your config file are sent to the subclass.

WRAPPER, META variables, SETs

       Dancer already provides a WRAPPER-like ability, which we call a "layout". The reason we do
       not use TT's WRAPPER (which also makes it incompatible with it) is because not all
       template systems support it. Actually, most don't.

       However, you might want to use it, and be able to define META variables and regular
       Template::Toolkit variables.

       These few steps will get you there:

       •   Disable the layout in Dancer

           You can do this by simply commenting (or removing) the "layout" configuration in the
           config.yml file.

       •   Use Template Toolkit template engine

           Change the configuration of the template to Template Toolkit:

               # in config.yml
               template: "template_toolkit"

       •   Tell the Template Toolkit engine who's your wrapper

               # in config.yml
               # ...
               engines:
                   template_toolkit:
                       WRAPPER: layouts/main.tt

       Done! Everything will work fine out of the box, including variables and META variables.

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>).

       To enable this:

           # in app.pl
           # ...
           set engines => {
               template_toolkit => {
                   embedded_templates => 1,
               },
           };
           set template => 'template_toolkit';

       This feature requires Template::Provider::FromDATA. Put your templates in the __DATA__
       section, and start every template with __${templatename}__.

USING TT'S WRAPPER STACK

       This engine provides three additional methods to access the WRAPPER stack of
       TemplateToolkit.

   set_wrapper
       Synopsis:

           engine('template')->set_wrapper( inner => 'inner_layout.tt' );
           engine('template')->set_wrapper( outer => 'outer_layout.tt' );
           engine('template')->set_wrapper( 'only_layout.tt' );

       The first two lines pushes/unshifts layout files to the wrapper array.  The third line
       overwrites the wrapper array with a single element.

   unset_wrapper
       Synopsis:

           engine('template')->unset_wrapper('inner') # returns 'inner_layout.tt';
           engine('template')->unset_wrapper('outer') # returns 'outer_layout.tt';

       These lines pops/shifts layout files from the wrapper array and returns the removed
       elements.

   reset_wrapper
       Synopsis:

           engine('template')->reset_wrapper;

       This method restores the wrapper array after a set_wrapper call.

SEE ALSO

       Dancer, Template

AUTHOR

       Dancer Core Developers

COPYRIGHT AND LICENSE

       This software is copyright (c) 2010 by Alexis Sukrieh.

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