Note: escape_char has been replaced with token-escape-char.
Note: cache-template option has been added and is enabled by default.
name-label (default TEMPLATE): Represents the label used for
identifying the template name in the hash of template variables.
template-dir: IO object representing the directory where the
templates are located.
cache-template (default: True): If True then the whole template
file is cached in memory, this improves performance.
die-on-bad-params (default: False): If True, then an attempt to
populate a template with a variable that doesn't exist (i.e. name
not found in template file) results in an error.
Note that it allows to leave variables undefined (i.e. name found in
template file but not defined in template hash). Undefined variables
are replaced with empty string. This is for compatibility with
Template::Nest (Raku).
You might want to keep this enabled during development & testing.
show-labels (default: False): If True, an string is appended to
every rendered template which is helpful in identifying which
template the output text came from. This is useful in development
when you have many templates.
Example:
<!-- BEGIN 00-simple-page -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Simple Page</title>
</head>
<body>
<p>A fairly simple page to test the performance of Template::Nest.</p>
<p>Simple Variable</p>
<!-- BEGIN 01-simple-component -->
<p>Simple Variable in Simple Component</p>
<!-- END 01-simple-component -->
</body>
</html>
<!-- END 00-simple-page -->
Here, 'BEGIN' & 'END' blocks have been added because show-labels
was set to True.
If you're not templating HTML and still want labels, you can set
comment-delims.
comment-delims (default: ['<!--', '-->']): Use this in
conjunction with show-labels. Expects a 2 element array. Example,
for templating JS you could do:
my $nest-alt = Template::Nest::Fast.new(
:$template-dir, :show-labels, comment-delims => ['/*', '*/']
);
Example output:
/* BEGIN js-file */
...
/* END js-file */
You can set the second comment token as an empty string if the
language you are templating does not use one. Example, for
templating Raku you could do:
my $nest-alt = Template::Nest::Fast.new(
:$template-dir, :show-labels, comment-delims => ['#', '']
);
Example output:
# BEGIN raku-file
...
# END raku-file */
template-extension (default: html): get/set the template
extension. This is so you can save typing your template extension
all the time if it's always the same. There is no reason why this
templating system could not be used to construct any other type of
file (or why you could not use another extension even if you were
producing html). Example, to manipulate JavaScript files, this will
look for 30-main.js in $template-dir:
my $nest-js = Template::Nest::Fast.new: :$template-dir, :template-extension('js');
my %simple-page-js = %(
TEMPLATE => '30-main',
var => 'Simple Variable',
);
Or if you have an empty template-extension, this will look for
30-main.html in $template-dir:
my $nest = Template::Nest::Fast.new: :$template-dir, :template-extension('');
my %simple-page-js = %(
TEMPLATE => '30-main.html',
var => 'Simple Variable',
);
fixed-indent (default: False): Intended to improve readability
when inspecting nested templates. For example, consider these templates:
wrapper.html:
<div>
<!--% contents %-->
</div>
photo.html:
<div>
<img src='/some-image.jpg'>
</div>
Output without fixed-indent:
<div>
<div>
<img src='/some-image.jpg'>
</div>
</div>
Output with fixed-indent:
<div>
<div>
<img src='/some-image.jpg'>
</div>
</div>
token-delims (default: ['<!--%', '%-->']): Set the delimiters
that define a token (to be replaced). For example, setting
token-delims to ['<%', '%>'] would mean that render will now
recognize and interpolate tokens in the format:
<% variable %>
token-escape-char (default: empty string): On rare occasions you
may actually want to use the exact character string you are using
for your token delimiters in one of your templates. For example,
here render is going to consider this as a token and remove it:
did you know we are using token delimiters <!--% and %--> in our templates?
To include the token, escape it with token-escape-char set to
(\):
did you know we are using token delimiters \<!--% and %--> in our templates?
Set it to an empty string to disable the behaviour.
defaults: Provide a hash of default values that are substituted if
template hash does not provide a value. For example, passing this
defaults hash:
my $nest = Template::Nest::Fast.new(
:$template-dir,
defaults => %(
variable => 'Simple Variable',
space => %(
inside => 'A variable inside a space.'
)
),
);
This $nest will first look for variable in template hash, then in
%defaults hash. If no value is found then namespaced defaults are
considered (look defaults-namespace-char).
defaults-namespace-char (default: .): Say you want to namespace
values in %defaults hash to differentiate parameters coming from
template hash and chose to prefix those variables like so:
<!--% config.title %--> - <!--% config.description %-->
You can pass a defaults like:
%(
"config.title" => "Title",
"config.description" => "Description"
)
However, writing config. repeatedly is a bit effortful, so you can
do the following:
%(
config => %(
"title" => "Title",
"description" => "Description"
)
)
Note: To disable this behaviour set defaults-namespace-char to an
empty string.
advanced-indexing (default: False): When enabled, ::Fast stores the
timestamp of template file index and if the file on disk is newer, it
re-indexes the file. It also indexes files that are present on disk but
weren't indexed when ::Fast was initialized.
This is a simple example that injects a variable in a template. We use
another template as a component as well.
Template variable can be a string, another template hash or an array too. The
array itself can contain template hash, string or nested array.