NAME

       Dancer2::Template::TemplateToolkit - Template toolkit engine for Dancer2

VERSION

       version 0.400001

SYNOPSIS

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

           template:   "template_toolkit"

       Or you may also change the rendering engine on a per-route basis by setting it manually
       with "set":

           # code code code
           set template => 'template_toolkit';

       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:

         engines:
           template:
             template_toolkit:
               start_tag: '<%'
               end_tag:   '%>'

       (Note: "start_tag" and "end_tag" are regexes.  If you want to use PHP-style tags, you will
       need to list them as "<\?" and "\?>".)  See Template::Manual::Config for the configuration
       variables.

       In addition to the standard configuration variables, the option "show_private_variables"
       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.

               show_private_variables: true

       Warning: Given the way Template::Toolkit implements this option, different Dancer2
       applications running within the same interpreter will share this option!

DESCRIPTION

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

METHODS

   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.

ADVANCED CUSTOMIZATION

       Template::Toolkit allows you to replace certain parts, like the internal STASH
       (Template::Stash). In order to do that, one usually passes an object of another
       implementation such as Template::Stash::AutoEscaping into the constructor.

       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.

       A subclass to use the aforementioned Template::Stash::AutoEscaping might look like this:

           package Dancer2::Template::TemplateToolkit::AutoEscaping;
           # or MyApp::

           use Moo;
           use Template::Stash::AutoEscaping;

           extends 'Dancer2::Template::TemplateToolkit';

           around '_build_engine' => 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;

       You can then use this new subclass in your config file instead of "template_toolkit".

           # in config.yml
           engines:
             template:
               TemplateToolkit::AutoEscaping:
                 start_tag: '<%'
                 end_tag:   '%>'
                 # optional arguments here
                 STASH:

       The same approach should work for SERVICE (Template::Service), CONTEXT
       (Template::Context), PARSER (Template::Parser) and GRAMMAR (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.

   Template Caching
       Template::Tookit templates can be cached by adding the "COMPILE_EXT" property to your
       template configuration settings:

           # in config.yml
           engines:
             template:
               template_toolkit:
                 start_tag: '<%'
                 end_tag:   '%>'
                 COMPILE_EXT: '.tcc' # cached file extension

       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.

       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 "COMPILE_DIR" property in your
       Dancer2 configuration file.

       Please see "Caching_and_Compiling_Options" in Template::Manual::Config for further details
       and more caching options.

SEE ALSO

       Dancer2, Dancer2::Core::Role::Template, Template::Toolkit.

AUTHOR

       Dancer Core Developers

COPYRIGHT AND LICENSE

       This software is copyright (c) 2023 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.