.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dancer::Template::Abstract 3pm"
.TH Dancer::Template::Abstract 3pm "2023-02-10" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dancer::Template::Abstract \- abstract class for Dancer's template engines
.SH "VERSION"
.IX Header "VERSION"
version 1.3521
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is provided as a base class for each template engine. Any template
engine must inherit from it and provide a set of methods described below.
.SH "TEMPLATE TOKENS"
.IX Header "TEMPLATE TOKENS"
By default Dancer injects some tokens (or variables) to templates. The
available tokens are:
.ie n .IP """perl_version""" 4
.el .IP "\f(CWperl_version\fR" 4
.IX Item "perl_version"
The current running Perl version.
.ie n .IP """dancer_version""" 4
.el .IP "\f(CWdancer_version\fR" 4
.IX Item "dancer_version"
The current running Dancer version.
.ie n .IP """settings""" 4
.el .IP "\f(CWsettings\fR" 4
.IX Item "settings"
Hash to access current application settings.
.ie n .IP """request""" 4
.el .IP "\f(CWrequest\fR" 4
.IX Item "request"
Hash to access your current request.
.ie n .IP """params""" 4
.el .IP "\f(CWparams\fR" 4
.IX Item "params"
Hash to access your request parameters.
.ie n .IP """vars""" 4
.el .IP "\f(CWvars\fR" 4
.IX Item "vars"
Hash to access your defined variables (using \f(CW\*(C`vars\*(C'\fR).
.ie n .IP """session""" 4
.el .IP "\f(CWsession\fR" 4
.IX Item "session"
Hash to access your session (if you have session enabled)
.SH "INTERFACE"
.IX Header "INTERFACE"
.IP "\fB\fBinit()\fB\fR" 4
.IX Item "init()"
The template engine can overload this method if some initialization stuff has to
be done before the template engine is used.
.Sp
The base class provides a plain \fBinit()\fR method that only returns true.
.IP "\fB\fBdefault_tmpl_ext()\fB\fR" 4
.IX Item "default_tmpl_ext()"
Template class that inherits this class should override this method to return a default template
extension, example: for Template::Toolkit it returns \*(L"tt\*(R" and for HTML::Mason it returns \*(L"mason\*(R".
So when you call \f(CW\*(C`template \*(Aqindex\*(Aq;\*(C'\fR in your dispatch code, Dancer will look for a file 'index.tt'
or 'index.mason' based on the template you use.
.Sp
Note 1: when returning the extension string, please do not add a dot in front of the extension
as Dancer will do that.
.Sp
Note 2: for backwards compatibility abstract class returns \*(L"tt\*(R" instead of throwing
an exception 'method not implemented'.
.Sp
User would be able to change the default extension using the
\&\f(CW\*(C`<extension\*(C'\fR> configuration variable on the template
configuration. For example, for the default (\f(CW\*(C`Simple\*(C'\fR) engine:
.Sp
.Vb 4
\&     template: "simple"
\&     engines:
\&       simple:
\&         extension: \*(Aqtmpl\*(Aq
.Ve
.IP "\fBview($view)\fR" 4
.IX Item "view($view)"
The default behavior of this method is to return the path of the given view,
appending the default template extension (either the value of the \f(CW\*(C`extension\*(C'\fR
setting in the configuration, or the value returned by \f(CW\*(C`default_tmpl_ext\*(C'\fR) if
it is not present in the view name given and no layout template with that exact
name existed.  (In other words, given a layout name \f(CW\*(C`main\*(C'\fR, if \f(CW\*(C`main\*(C'\fR exists
in the layouts dir, it will be used; if not, \f(CW\*(C`main.tmpl\*(C'\fR (where \f(CW\*(C`tmpl\*(C'\fR is the
value of the \f(CW\*(C`extension\*(C'\fR setting, or the value returned by \f(CW\*(C`default_tmpl_ext\*(C'\fR)
will be looked for.)
.IP "\fBview_exists($view_path)\fR" 4
.IX Item "view_exists($view_path)"
By default, Dancer::Template::Abstract checks to see if it can find the
view file calling \f(CW\*(C`view_exists($path_to_file)\*(C'\fR. If not, it will
generate a nice error message for the user.
.Sp
If you are using 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.
.IP "\fBlayout($layout, \f(CB$tokens\fB, \f(CB$content\fB)\fR" 4
.IX Item "layout($layout, $tokens, $content)"
The default behavior of this method is to merge a content with a layout.  The
layout file is looked for with similar logic as per \f(CW\*(C`view\*(C'\fR \- an exact match
first, then attempting to append the default template extension, if the view
name given did not already end with it.
.IP "\fBrender($self, \f(CB$template\fB, \f(CB$tokens\fB)\fR" 4
.IX Item "render($self, $template, $tokens)"
This method must be implemented by the template engine. Given a template and a
set of tokens, it returns a processed string.
.Sp
If \f(CW$template\fR 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 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).
.Sp
This method's return value must be a string which is the result of the
interpolation of \f(CW$tokens\fR in \f(CW$template\fR.
.Sp
If an error occurs, the method should trigger an exception with \f(CW\*(C`die()\*(C'\fR.
.Sp
Examples :
.Sp
.Vb 2
\&    # with a template as a file
\&    $content = $engine\->render(\*(Aq/my/template.txt\*(Aq, { var => 42 };
\&
\&    # with a template as a scalar
\&    my $template = "here is <% var %>";
\&    $content = $engine\->render(\e$template, { var => 42 });
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
This module has been written by Alexis Sukrieh, see Dancer for details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 by Alexis Sukrieh.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.