/ 
HTML-Blitz-0.0901
River stage zero No dependents
/ HTML::Blitz::Template

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:

  1. 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).

  2. Serialize the code to a string (via "compile_to_string") or straight to disk (via "compile_to_fh" or "compile_to_file").

  3. Use it as a component of another template. See the replace_inner_template and replace_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.

SEE ALSO

HTML::Blitz