<html><head><title>Dancer2::Template::TextTemplate</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
BODY {
background: white;
color: black;
font-family: arial,sans-serif;
margin: 0;
padding: 1ex;
}
A:link, A:visited {
background: transparent;
color: #006699;
}
A[href="#POD_ERRORS"] {
background: transparent;
color: #FF0000;
}
DIV {
border-width: 0;
}
DT {
margin-top: 1em;
margin-left: 1em;
}
.pod { margin-right: 20ex; }
.pod PRE {
background: #eeeeee;
border: 1px solid #888888;
color: black;
padding: 1em;
white-space: pre;
}
.pod H1 {
background: transparent;
color: #006699;
font-size: large;
}
.pod H1 A { text-decoration: none; }
.pod H2 A { text-decoration: none; }
.pod H3 A { text-decoration: none; }
.pod H4 A { text-decoration: none; }
.pod H2 {
background: transparent;
color: #006699;
font-size: medium;
}
.pod H3 {
background: transparent;
color: #006699;
font-size: medium;
font-style: italic;
}
.pod H4 {
background: transparent;
color: #006699;
font-size: medium;
font-weight: normal;
}
.pod IMG {
vertical-align: top;
}
.pod .toc A {
text-decoration: none;
}
.pod .toc LI {
line-height: 1.2em;
list-style-type: none;
}
/*]]>*/-->
</style>
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.28,
using Pod::Simple::PullParser v3.28,
under Perl v5.018002 at Thu Apr 17 17:05:01 2014 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#VERSION'>VERSION</a>
<li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Configuration'>Configuration</a>
<li class='indexItem indexItem2'><a href='#Global_caching_-_caching%2C_expires'>Global caching - caching, expires</a>
<li class='indexItem indexItem2'><a href='#%22String-ref_templates%22_caching_-_cache_stringrefs'>"String-ref templates" caching - cache_stringrefs</a>
<li class='indexItem indexItem2'><a href='#Custom_delimiters_-_delimiters'>Custom delimiters - delimiters</a>
<li class='indexItem indexItem2'><a href='#Prepending_code_-_prepend'>Prepending code - prepend</a>
<li class='indexItem indexItem2'><a href='#Running_in_a_Safe_-_safe%2C_safe_opcodes%2C_safe_disposable'>Running in a Safe - safe, safe_opcodes, safe_disposable</a>
</ul>
<li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#render(_%24template%2C_%5C%25tokens_)'>render( $template, \%tokens )</a>
</ul>
<li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
<li class='indexItem indexItem1'><a href='#COPYRIGHT_AND_LICENSE'>COPYRIGHT AND LICENSE</a>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Dancer2::Template::TextTemplate - Text::Template engine for Dancer2</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="VERSION"
>VERSION</a></h1>
<p>version 1.003</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<p>To use this engine,
you may configure <a href="http://search.cpan.org/perldoc?Dancer2" class="podlinkpod"
>Dancer2</a> via <code>config.yml</code>:</p>
<pre> template: text_template</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This template engine allows you to use <a href="http://search.cpan.org/perldoc?Text%3A%3ATemplate" class="podlinkpod"
>Text::Template</a> in <a href="http://search.cpan.org/perldoc?Dancer2" class="podlinkpod"
>Dancer2</a>.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Configuration"
>Configuration</a></h2>
<p>Here are all available options, as you would set them in a <code>config.yml</code>, with their <b>default</b> values:</p>
<pre> template: text_template
engines:
text_template:
caching: 1
expires: 3600 # in seconds; use 0 to disable
cache_stringrefs: 1
delimiters: [ "{", "}" ]
prepend: |
use strict;
use warnings;
safe: 1
safe_opcodes: [ ":default", ":load" ]
safe_disposable: 0</pre>
<p>The following sections explain what these options do.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Global_caching_-_caching,_expires"
>Global caching - <code>caching</code>, <code>expires</code></a></h2>
<p>Contrary to other template engines (like <a href="http://search.cpan.org/perldoc?Template%3A%3AToolkit" class="podlinkpod"
>Template::Toolkit</a>), where <i>one</i> instance may work on <i>multiple</i> templates, <i>one</i> <a href="http://search.cpan.org/perldoc?Text%3A%3ATemplate" class="podlinkpod"
>Text::Template</a> instance is created <i>for each</i> template. Therefore, if:</p>
<ul>
<li>you don't use a huge amount of different templates;</li>
<li>you don't use each template just once;</li>
</ul>
<p>then it may be interesting to <b>cache</b> Text::Template instances for later use. Since these conditions seem to be common, this engine uses a cache (<i>via</i> <a href="http://search.cpan.org/perldoc?CHI" class="podlinkpod"
>CHI</a>) <b>by default</b>.</p>
<p>If you're OK with caching, you should specify a <b>timeout</b> (<code>expires</code>) after which cached Text::Template instances are to be refreshed, since you might have changed your template sources without restarting Dancer2. By default, this engine uses <code>expires: 3600</code> (one hour). Use <code>0</code> to tell it that templates never expire.</p>
<p>If you don't want any caching, just set <code>caching</code> to <code>0</code>.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name=""String-ref_templates"_caching_-_cache_stringrefs"
>"String-ref templates" caching - <code>cache_stringrefs</code></a></h2>
<p>Just like with <a href="http://search.cpan.org/perldoc?Dancer2%3A%3ATemplate%3A%3AToolkit" class="podlinkpod"
>Dancer2::Template::Toolkit</a>, you can pass templates either as filenames (for a template file) or string references ("string-refs", which are dereferenced and used as the template's content). In some cases, you may want to disable caching for string-refs only: for instance, if you generate a lot of templates on-the-fly and use them only once, caching them is useless and fills your cache. You can therefore disable caching <i>for string-refs only</i> by setting <code>cache_stringrefs</code> to <code>0</code>.</p>
<p>Note that if you set <code>caching</code> to <code>0</code>, you don't have <i>any</i> caching, so <code>cache_stringrefs</code> is ignored.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Custom_delimiters_-_delimiters"
>Custom delimiters - <code>delimiters</code></a></h2>
<p>The <code>delimiters</code> option allows you to specify a custom delimiters pair (opening and closing) for your templates. See the <a href="http://search.cpan.org/perldoc?Text%3A%3ATemplate" class="podlinkpod"
>Text::Template</a> documentation for more about delimiters, since this module just pass them to Text::Template. This option defaults to <code>{</code> and <code>}</code>, meaning that in <code>a {b} c</code>, <code>b</code> (and only <code>b</code>) will be interpolated.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Prepending_code_-_prepend"
>Prepending code - <code>prepend</code></a></h2>
<p>This option specifies Perl code run by Text::Template <i>before</i> evaluating each template. For instance, with this option's default value, i.e.:</p>
<pre> use strict;
use warnings FATAL => 'all';</pre>
<p>then evaluating the following template:</p>
<pre> you're the { $a + 1 }th visitor!</pre>
<p>is the same as evaluating:</p>
<pre> {
use strict;
use warnings FATAL => 'all';
""
}you're the { $a + 1 }th visitor!</pre>
<p>and thus you'd get:</p>
<pre> Program fragment delivered error
``Use of uninitialized value $a in addition (+) [...]</pre>
<p>in your template output if you forgot to pass a value for <code>$a</code>.</p>
<p>If you don't want anything prepended to your templates, simply give a non-dying, side-effects-free Perl expression to <code>prepend</code>, like <code>0</code> or <code>""</code>.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Running_in_a_Safe_-_safe,_safe_opcodes,_safe_disposable"
>Running in a <a href="http://search.cpan.org/perldoc?Safe" class="podlinkpod"
>Safe</a> - <code>safe</code>, <code>safe_opcodes</code>, <code>safe_disposable</code></a></h2>
<p>This option (enabled by default) makes your templates to be evaluated in a <a href="http://search.cpan.org/perldoc?Safe" class="podlinkpod"
>Safe</a> compartment, i.e. where some potentially dangerous operations (such as <code>system</code>) are disabled. Note that the same Safe compartment will be used to evaluate all your templates, unless you explicitly specify <code>safe_disposable: 1</code> (one compartment per template <i>evaluation</i>).</p>
<p>This Safe uses the <code>:default</code> and <code>:load</code> opcode sets (see <a href="https://metacpan.org/pod/Opcode#Predefined-Opcode-Tags" class="podlinkurl"
>the Opcode documentation</a>), unless you specify it otherwise with the <code>safe_opcodes</code> option. You can, of course, mix opcodes and optags, as in:</p>
<pre> safe_opcodes:
- ":default"
- "time"</pre>
<p>which enables the default opcode set <i>and</i> <code>time</code>. But <b>be careful</b>: with the previous example for instance, you don't allow <code>require</code>, and thus break the default value of the <code>prepend</code> option (which contains <code>use</code>)!</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="render(_$template,_\%tokens_)"
>render( $template, \%tokens )</a></h2>
<p>Renders the template.</p>
<ul>
<li><code>$template</code> is either a (string) filename for the template file or a reference to a string that contains the template.</li>
<li><code>\%tokens</code> is a hashref for the tokens you wish to pass to <a href="http://search.cpan.org/perldoc?Text%3A%3ATemplate" class="podlinkpod"
>Text::Template</a> for rendering, as if you were using <code>Text::Template::fill_in</code>.</li>
</ul>
<p><a href="http://search.cpan.org/perldoc?Croak" class="podlinkpod"
>Carp</a>s if an error occurs.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Thibaut Le Page <thilp@cpan.org></p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>This software is copyright (c) 2014 by Thibaut Le Page.</p>
<p>This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.</p>
<!-- end doc -->
</body></html>