.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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 turned on, 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 "Tenjin::Template 3pm"
.TH Tenjin::Template 3pm "2016-05-17" "perl v5.22.2" "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"
Tenjin::Template \- A Tenjin template object, either built from a file or from memory.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&        # mostly used internally, but you can manipulate
\&        # templates like so
\&
\&        my $template = Tenjin::Template\->new(\*(Aq/path/to/templates/template.html\*(Aq);
\&        my $context = { scalar => \*(Aqscalar\*(Aq, arrayref => [\*(Aqone\*(Aq, 2, "3"] };
\&        $template\->render($context);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is in charge of the task of compiling Tenjin templates.
Templates in Tenjin are compiled into standard Perl code (combined with
any Perl code used inside the templates themselves). Rendering a template
means \f(CW\*(C`eval\*(C'\fRuating that Perl code and returning its output.
.PP
The Tenjin engine reads a template file or a template string, and creates
a Template object from it. Then the object compiles itself by traversing
the template, parsing Tenjin macros like 'include' and 'start_capture',
replaces Tenjin expressions (i.e. \f(CW\*(C`[== $expr =]\*(C'\fR or \f(CW\*(C`[= $expr =]\*(C'\fR) with the
appropriate Perl code, etc. This module ties a template object with
a context object, but all context manipulation (and the actual \f(CW\*(C`eval\*(C'\fRuation
of the Perl code) is done by Tenjin::Context.
.PP
If you're planning on using this module by itself (i.e. without the Tenjin
engine), keep in mind that template caching and layout templates are not
handled by this module.
.SH "METHODS"
.IX Header "METHODS"
.SS "new( [$filename, \e%opts] )"
.IX Subsection "new( [$filename, %opts] )"
Creates a new Tenjin::Template object, possibly from a file on the file
system (in which case \f(CW$filename\fR must be provided and be an absolute
path to a template file). Optionally, a hash-ref of options can be
passed to set some customizations. Available options are 'escapefunc',
which will be in charge of escaping expressions (from \f(CW\*(C`[= $expr =]\*(C'\fR) instead
of the internal method (which uses HTML::Entities); and 'rawclass',
which can be used to prevent variables and objects of a certain class
from being escaped, in which case the variable must be a hash-ref
that has a key named 'str', which will be used instead. So, for example,
if you have a variable named \f(CW$var\fR which is a hash-ref, and 'rawclass'
is set as '\s-1HASH\s0', then writing \f(CW\*(C`[= $var =]\*(C'\fR on your templates will replace
\&\f(CW$var\fR with \f(CW\*(C`$var\->{str}\*(C'\fR.
.SS "render( [$_context] )"
.IX Subsection "render( [$_context] )"
Renders the template, possibly with a context hash-ref, and returns the
rendered output. If errors have occurred when rendering the template (which
might happen since templates have and are Perl code), then this method
will croak.
.SH "INTERNAL METHODS"
.IX Header "INTERNAL METHODS"
.ie n .SS "convert_file( $filename )"
.el .SS "convert_file( \f(CW$filename\fP )"
.IX Subsection "convert_file( $filename )"
Receives an absolute path to a template file, converts that file
to Perl code by calling \fIconvert()\fR and
returns that code.
.ie n .SS "convert( $input, [$filename] )"
.el .SS "convert( \f(CW$input\fP, [$filename] )"
.IX Subsection "convert( $input, [$filename] )"
Receives a text of a template (i.e. the template itself) and possibly
an absolute path to the template file (if the template comes from a file),
and converts the template into Perl code, which is later \f(CW\*(C`eval\*(C'\fRuated
for rendering. Conversion is done by parsing the statements in the
template (see \fIparse_stmt()\fR).
.ie n .SS "compile_stmt_pattern( $pl )"
.el .SS "compile_stmt_pattern( \f(CW$pl\fP )"
.IX Subsection "compile_stmt_pattern( $pl )"
Receives a string which denotes the Perl code delimiter which is used
inside templates. Tenjin uses '\f(CW\*(C`<?pl ... ?>\*(C'\fR' and '\f(CW\*(C`<?PL ... ?>\*(C'\fR'
(the latter for preprocessing), so \f(CW$pl\fR will be 'pl'. This method
returns a tranlsation regular expression which will be used for reading
embedded Perl code.
.SS "stmt_pattern"
.IX Subsection "stmt_pattern"
Returns the default pattern (which uses 'pl') with the
previous_method.
.SS "\fIexpr_pattern()\fP"
.IX Subsection "expr_pattern()"
Defines how expressions are written in Tenjin templates (\f(CW\*(C`[== $expr =]\*(C'\fR
and \f(CW\*(C`[= $expr =]\*(C'\fR).
.ie n .SS "parse_stmt( $bufref, $input )"
.el .SS "parse_stmt( \f(CW$bufref\fP, \f(CW$input\fP )"
.IX Subsection "parse_stmt( $bufref, $input )"
Receives a buffer which is used for saving a template's expressions
and the template's text, parses all expressions in the templates and
pushes them to the buffer.
.ie n .SS "hook_stmt( $stmt )"
.el .SS "hook_stmt( \f(CW$stmt\fP )"
.IX Subsection "hook_stmt( $stmt )"
.ie n .SS "expand_macro( $funcname, $arg )"
.el .SS "expand_macro( \f(CW$funcname\fP, \f(CW$arg\fP )"
.IX Subsection "expand_macro( $funcname, $arg )"
This method is in charge of invoking macro functions which might be used
inside templates. The following macros are available:
.IP "\(bu" 4
\&\f(CW\*(C`include( $filename )\*(C'\fR
.Sp
Includes another template, whose name is \f(CW$filename\fR, inside the current
template. The included template will be placed inside the template as if
they were one unit, so the context variable applies to both.
.IP "\(bu" 4
\&\f(CW\*(C`start_capture( $name )\*(C'\fR and \f(CW\*(C`end_capture()\*(C'\fR
.Sp
Tells Tenjin to capture the output of the rendered template from the point
where \f(CW\*(C`start_capture()\*(C'\fR was called to the point where \f(CW\*(C`end_capture()\*(C'\fR
was called. You must provide a name for the captured portion, which will be
made available in the context as \f(CW\*(C`$_context\->{$name}\*(C'\fR for immediate
usage. Note that the captured portion will not be printed unless you do
so explicilty with \f(CW\*(C`$_context\->{$name}\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`start_placeholder( $var )\*(C'\fR and \f(CW\*(C`end_placeholder()\*(C'\fR
.Sp
This is a special method which can be used for making your templates a bit
cleaner. Suppose your context might have a variable whose name is defined
in \f(CW$var\fR. If that variable exists in the context, you simply want to print
it, but if it's not, you want to print and/or perform other things. In that
case you can call \f(CW\*(C`start_placeholder( $var )\*(C'\fR with the name of the context
variable you want printed, and if it's not, anything you do between
\&\f(CW\*(C`start_placeholder()\*(C'\fR and \f(CW\*(C`end_placeholder()\*(C'\fR will be printed instead.
.IP "\(bu" 4
echo( \f(CW$exr\fR )
.Sp
Just prints the provided expression. You might want to use it if you're
a little too comfortable with \s-1PHP.\s0
.ie n .SS "get_expr_and_escapeflag( $not_escape, $expr, $delete_newline )"
.el .SS "get_expr_and_escapeflag( \f(CW$not_escape\fP, \f(CW$expr\fP, \f(CW$delete_newline\fP )"
.IX Subsection "get_expr_and_escapeflag( $not_escape, $expr, $delete_newline )"
.ie n .SS "parse_expr( $bufref, $input )"
.el .SS "parse_expr( \f(CW$bufref\fP, \f(CW$input\fP )"
.IX Subsection "parse_expr( $bufref, $input )"
.ie n .SS "start_text_part( $bufref )"
.el .SS "start_text_part( \f(CW$bufref\fP )"
.IX Subsection "start_text_part( $bufref )"
.ie n .SS "stop_text_part( $bufref )"
.el .SS "stop_text_part( \f(CW$bufref\fP )"
.IX Subsection "stop_text_part( $bufref )"
.ie n .SS "add_text( $bufref, $text )"
.el .SS "add_text( \f(CW$bufref\fP, \f(CW$text\fP )"
.IX Subsection "add_text( $bufref, $text )"
.ie n .SS "add_stmt( $bufref, $stmt )"
.el .SS "add_stmt( \f(CW$bufref\fP, \f(CW$stmt\fP )"
.IX Subsection "add_stmt( $bufref, $stmt )"
.ie n .SS "add_expr( $bufref, $expr, $flag_escape )"
.el .SS "add_expr( \f(CW$bufref\fP, \f(CW$expr\fP, \f(CW$flag_escape\fP )"
.IX Subsection "add_expr( $bufref, $expr, $flag_escape )"
.ie n .SS "defun( $funcname, @args )"
.el .SS "defun( \f(CW$funcname\fP, \f(CW@args\fP )"
.IX Subsection "defun( $funcname, @args )"
.SS "\fIcompile()\fP"
.IX Subsection "compile()"
.ie n .SS "escaped_expr( $expr )"
.el .SS "escaped_expr( \f(CW$expr\fP )"
.IX Subsection "escaped_expr( $expr )"
Receives a Perl expression (from \f(CW\*(C`[= $expr =]\*(C'\fR) and escapes it. This will
happen in one of three ways: with the escape function defined in
\&\f(CW\*(C`$opts\->{escapefunc}\*(C'\fR (if defined), with a scalar string (if
\&\f(CW\*(C`$opts\->{rawclass}\*(C'\fR is defined), or with \f(CW\*(C`escape_xml()\*(C'\fR from
Tenjin::Util, which uses HTML::Entites.
.ie n .SS "_read_file( $filename, [$lock_required] )"
.el .SS "_read_file( \f(CW$filename\fP, [$lock_required] )"
.IX Subsection "_read_file( $filename, [$lock_required] )"
Receives an absolute path to a template file, reads its content and
returns it. If \f(CW$lock_required\fR is passed (and has a true value), the
file will be locked for reading.
.ie n .SS "_write_file( $filename, $content, [$lock_required] )"
.el .SS "_write_file( \f(CW$filename\fP, \f(CW$content\fP, [$lock_required] )"
.IX Subsection "_write_file( $filename, $content, [$lock_required] )"
Receives an absolute path to a template file and the templates contents,
and creates the file (or truncates it, if existing) with that contents.
If \f(CW$lock_required\fR is passed (and has a true value), the file will be
locked exclusively when writing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tenjin.
.SH "AUTHOR, LICENSE AND COPYRIGHT"
.IX Header "AUTHOR, LICENSE AND COPYRIGHT"
See Tenjin.