Dancer...Toolkit(3pm)

📦
version 1.3522 · 6 versions
, in ubuntu stonking

💖 Dancer::Template::TemplateToolkit 💖

okay bestie, so the manual name is Dancer::Template::TemplateToolkit (that's the 3pm one btw) and it lives in the Perl user-contributed docs, and it's literally the Template Toolkit wrapper for Dancer. slay.

✨ VERSION ✨

version 1.3522 — yes, she's got a version number and she's proud of it 🎀

🦋 DESCRIPTION 🦋

So this class is the little matchmaker between Dancer's template engine abstraction layer and the Template module. it's giving interface, it's giving glue code, it's giving "I make these two talk to each other".

ngl, this template engine is recommended for production purposes, but — and this is the catch — it depends on the Template module. so make sure that's installed, bestie.

To actually use this engine, you set the template setting like so:

template: template_toolkit

You can do that in your config.yml file, or literally right in your app code with the set keyword. whatever feels more main character to you 💅

heads up: by default, Dancer configures the Template::Toolkit engine to use <% %> brackets instead of its own default [% %] brackets. iconic of Dancer tbh.

You can change that in your config file, for example:

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

You can also throw in any options you would normally pass to the Template module's initialization. For instance, you could enable saving the compiled templates:

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

But bestie, note this: unless you change them, Dancer sets both of the Template options ANYCASE and ABSOLUTE on, points INCLUDE_PATH at your views directory, and sets ENCODING to your charset setting. so those are the defaults you're getting whether you asked or not 🫶

🌸 SUBCLASSING 🌸

By default, Template is used. But you can configure Dancer to use a subclass of Template with the subclass option. look at her go:

engines:
    template_toolkit:
        subclass: My::Template

When used like this, Dancer skips the defaults mentioned above. Only the things included in your config file get sent to the subclass. so no sneaky defaults, periodt.

🎀 WRAPPER, META variables, SETs 🎀

Okay so 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. so if that's your vibe, here's how you get there:

  • Disable the layout in Dancer

You can do this by simply commenting out (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. ate and left no crumbs 🔥

⭐ EMBEDDED TEMPLATES ⭐

You can embed your templates right 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}__. no cap, that's the whole ritual 🧚

💜 USING TT'S WRAPPER STACK 💜

This engine provides three additional methods to access the WRAPPER stack of TemplateToolkit. three little icons, each with a job 👑

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 push/unshift layout files onto the wrapper array. The third line overwrites the wrapper array with a single element. so it's giving "add to the stack" and also giving "replace the whole stack", depending on how you call her 💅

unset_wrapper

Synopsis:

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

These lines pop/shift layout files from the wrapper array and return the removed elements. she gives them back, she's polite like that 🫶

reset_wrapper

Synopsis:

engine('template')->reset_wrapper;

This method restores the wrapper array after a set_wrapper call. the undo button, basically. the "jk bestie" button.

🌈 SEE ALSO 🌈

  • Dancer
  • Template

👑 AUTHOR 👑

Dancer Core Developers

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.

and that's the whole page bestie, mwah! 💋 this one's from perl v5.40.1, dated 2026-05-05, and it's the Dancer...Toolkit(3pm) page from the User Contributed Perl Documentation. go forth and template, you got this ⭐🦋💅

📦 where this page comes from