NAME
HTML::Blitz::Template - pre-parsed HTML documents ready for template expansion
SYNOPSIS
my $template = $blitz->apply_to_file("src/template.html");
my $data = {
title => $title,
people => [
{ name => $name1, job => $job1 },
{ name => $name2, job => $job2 },
{ name => $name3, job => $job3 },
],
};
my $html = $template->process($data);
my $func = $template->compile_to_sub;
my $html = $func->($data);
$template->compile_to_file("precompiled/template.pl");
my $func = do "precompiled/template.pl";
my $html = $func->($data);
DESCRIPTION
Objects of this class represent document templates that result from applying a set of template actions to an HTML source document. See HTML::Blitz.
There are three things you can do with an HTML::Blitz::Template object:
Give it a set of variables and get an HTML document back. This involves the "compile_to_sub" method and calling the returned function (or using the "process" method, which does it for you).
Serialize the code to a string (via "compile_to_string") or straight to disk (via "compile_to_fh" or "compile_to_file").
Use it as a component of another template. See the
replace_inner_template
andreplace_outer_template
actions in HTML::Blitz.
METHODS
This class has no public constructor. Instances can be created with "apply_to_html" in HTML::Blitz and "apply_to_file" in HTML::Blitz.
compile_to_string
my $code = $template->compile_to_string;
Creates Perl code that implements the functionality of the template (which is the result of applying a rule set to an HTML source document) and returns it as a string.
compile_to_sub
my $func = $template->compile_to_sub;
my $html = $func->($variables);
Like "compile_to_string", but returns a code reference instead of source code. Equivalent to eval $template->compile_to_string
, but without clobbering $@
. It also caches the generated function internally, so calling compile_to_sub
twice will return the same reference.
The returned code reference takes an argument that specifies the variables that the template is to be instantiated with. This argument takes the form of a variable environment.
A variable environment is a hash reference whose keys are the names of runtime variables used by the template (and the values are the corresponding values). Template variables fall into the following categories:
Strings.
These are used to expand variables in text (e.g.
replace_inner_var
) and attribute values (e.g.set_attribute_var
).Booleans.
These are used in conditions (e.g.
remove_if
).Functions.
These are used to dynamically transform text (e.g.
transform_inner_var
) and attribute values (e.g.transform_attribute_var
).Templates (i.e. instances of HTML::Blitz::Template).
These are used to embed sub-templates into other templates, as a form of component reuse (e.g.
replace_inner_template
).Dynamic HTML (i.e. instances of HTML::Blitz::Builder).
These are used to insert dynamically generated HTML fragments (e.g.
replace_inner_dyn_builder
).Arrays (of variable environments).
These are used to provide input values to repeated subsections of the source document (e.g.
repeat_outer
).
process
my $html = $template->process($variables);
Equivalent to $template->compile_to_sub->($variables)
.
compile_to_fh
$template->compile_to_fh($filehandle [, $filename ]);
Like "compile_to_string", but writes the resulting code to the file handle passed as the first argument instead of returning it as a string. The second argument is optional; it is used in the error message thrown if the write fails.
compile_to_file
$template->compile_to_file($filename);
$template->compile_to_file($filename, do_sync => 1);
Like "compile_to_string", but writes the resulting code to the file whose name is passed as the first argument. (If the file doesn't exist, it is created; otherwise it is overwritten.)
If do_sync => 1
is passed, "$io->sync" in IO::Handle is called before the file is closed, which flushes file data at the OS level (see fsync(2)).
FREEZE
my @pieces = $template->FREEZE($data_model);
Implements the generic object serialization protocol from Types::Serialiser. This allows template objects to be serialized by Cpanel::JSON:::XS with allow_tags
enabled (creating a non-standard superset of JSON) or Sereal::Encoder with freeze_callbacks
enabled.
Any other generic serializer should also work, provided it can encode undef
, numbers, strings, as well as references to scalars, arrays, and hashes.
THAW
my $template = HTML::Blitz::Template->THAW($data_model, @pieces);
Implements the generic object serialization protocol from Types::Serialiser. This allows template objects to be deserialized by Cpanel::JSON:::XS with allow_tags
enabled (parsing a non-standard superset of JSON) or Sereal::Decoder.
AUTHOR
Lukas Mai, <lmai at web.de>
COPYRIGHT & LICENSE
Copyright 2022 Lukas Mai.
This module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.