Dancer...stract(3pm)

✨ NAME ✨

Dancer::Template::Abstract — it's the abstract class for Dancer's template engines, bestie 💅

This page is from the User Contributed Perl Documentation, and yes we're doing the Dancer...stract(3pm) thing, iykyk 🌸

---

🎀 VERSION 🎀

version 1.3522 ✨

---

🦋 DESCRIPTION 🦋

Okay so, this class? It's the blueprint. It gets handed to every single template engine as its base class. Any template engine that wants to play has to inherit from it, and it has to bring the whole set of methods described down below. No shortcuts, no vibes-only implementations, periodt. 👑

---

🌈 TEMPLATE TOKENS 🌈

By default, Dancer injects a lil' set of tokens (aka variables, same thing bestie) into your templates. Here's the whole squad:

• perl_version — the Perl version that's running right now at this exact moment 🐪
• dancer_version — the Dancer version that's running right now 💃
• settings — a hash so you can peek at your current application settings
• request — a hash so you can peek at your current request
• params — a hash so you can peek at your request parameters
• vars — a hash so you can peek at your defined variables (the ones you set with vars)
• session — a hash so you can peek at your session (only if you have session enabled, obviously 🙈)

---

💖 INTERFACE 💖

init()

The template engine is allowed to overload this method if there's some initialization stuff that has to happen before the template engine gets used. Getting-ready energy, we love to see it ✨

The base class gives you a plain init() method that literally just returns true. That's it. That's the whole method. Lowkey iconic.

default_tmpl_ext()

Any template class that inherits this class should override this method and return a default template extension. Like, for example: for Template::Toolkit it returns tt, and for HTML::Mason it returns mason. So when you go and call template 'index'; in your dispatch code, Dancer will go looking for a file called index.tt or index.mason based on whichever template you're using. Cute, right? 🎀

Note 1: when you're returning that extension string, please please PLEASE do not add a dot in front of the extension — Dancer will do that part itself. Do not fight Dancer on this. 🙅♀️

Note 2: for backwards compatibility, the abstract class returns tt instead of throwing an exception saying 'method not implemented'. Legacy behavior, we respect the elders 💜

Your user would be able to change the default extension using the <extension> configuration variable on the template configuration. For example, for the default (Simple) engine:

template: "simple"
engines:
  simple:
    extension: 'tmpl'

view($view)

The default behavior of this method is to return the path of the given view, appending the default template extension — that's either the value of the extension setting in the configuration, or the value returned by default_tmpl_ext — if it is not present in the view name given and no layout template with that exact name existed. So basically, in other words: given a layout name main, if main exists in the layouts dir, that's the one getting used. If it doesn't exist? Then main.tmpl will be looked for, where tmpl is the value of the extension setting, or the value returned by default_tmpl_ext. Simple as that 💅

view_exists($view_path)

By default, Dancer::Template::Abstract checks to see if it can find the view file by calling view_exists($path_to_file). If it can't find it, it will generate a nice error message for the user. Very thoughtful of it 🫶

If you're extending Dancer::Template::Abstract to use a template system with multiple document roots (like Text::XSlate or Template), you can override this method to always return true, and therefore skip this check entirely. Main character move, honestly.

layout($layout, $tokens, $content)

The default behavior of this method is to merge a content with a layout. The layout file gets looked for with similar logic as per view — an exact match first, then it attempts to append the default template extension, if the view name given did not already end with it. First come, first served, no cap. 🌸

render($self, $template, $tokens)

This method must be implemented by the template engine. No skipping this one, bestie, it's the whole point 😭 Given a template and a set of tokens, it returns a processed string.

If $template is a reference, it's assumed to be a reference to a string that contains the template itself. If it's not a reference, it's assumed to be the path to a template file, as a string. The render method will then have to open it and read its content (Dancer::FileUtils::read_file_content does that job for you, you're welcome 💖).

This method's return value must be a string which is the result of the interpolation of $tokens in $template. That's the whole assignment. ✨

If an error occurs, the method should trigger an exception with die(). Dramatic? Yes. Necessary? Also yes. 💀

Examples:

# with a template as a file
$content = $engine->render('/my/template.txt', { var => 42 };

# with a template as a scalar
my $template = "here is <% var %>";
$content = $engine->render(\$template, { var => 42 });

---

👑 AUTHOR 👑

This module has been written by Alexis Sukrieh, see Dancer for details. Shoutout to the legend 🫡

---

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

---

okay bestie that's the whole page, you ate it, no crumbs left 💅✨

btw this was perl v5.40.1, dated 2026-05-05, straight out of the Dancer...stract(3pm) part of the User Contributed Perl Documentation. mwah 🎀