Dancer2...Toolkit(3)

🎀 NAME 🎀

okay so Dancer2::Template::TemplateToolkit — that's her, that's the whole page — she's the Template Toolkit engine for Dancer2. 💖

(your terminal might squish the name down to Dancer2...Toolkit(3) because it has zero patience for long names, but it's the same girl, no cap.)

---

💫 VERSION 💫

version 2.2.1 ✨

---

🌸 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:   '%>'

heads up bestie: start_tag and end_tag are regexes. So if you wanna use PHP-style tags, you gotta 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! 😭 Not a vibe, but that's the tea.

---

🦋 DESCRIPTION 🦋

This template engine allows you to use Template::Toolkit in Dancer2. That's it, that's the whole glow-up. 🌈

---

💅 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. 👑

Custom Template::Toolkit class

When subclassing this module it is possible to use a different Template::Toolkit class (for example if you have also subclassed that). To do that simply define a different template_class property:

package Dancer2::Template::TemplateToolkit::FooBar;

use Moo;

extends 'Dancer2::Template::TemplateToolkit';

has '+template_class' => ( default => 'TemplateFooBar' );

1;

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. ✨ (iconic behaviour honestly)

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

---

and that's the whole page, bestie — shipped as User Contributed Perl Documentation, running on perl v5.42.3, dated 2026-09-20. go forth and template, mwah 💋🎀