.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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 "Text::MicroMason::HTMLTemplate 3pm"
.TH Text::MicroMason::HTMLTemplate 3pm "2019-11-10" "perl v5.30.0" "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"
Text::MicroMason::HTMLTemplate \- Alternate Syntax like HTML::Template
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Instead of using this class directly, pass its name to be mixed in:
.PP
.Vb 2
\&  use Text::MicroMason;
\&  my $mason = Text::MicroMason::Base\->new( \-HTMLTemplate );
.Ve
.PP
Use the standard compile and execute methods to parse and evaluate templates:
.PP
.Vb 2
\&  print $mason\->compile( text=>$template )\->( @%args );
\&  print $mason\->execute( text=>$template, @args );
.Ve
.PP
Or use HTML::Template's calling conventions:
.PP
.Vb 3
\&    $template = Text::MicroMason\->new( \-HTMLTemplate, filename=>\*(Aqsimple.tmpl\*(Aq );
\&    $template\->param( %arguments );
\&    print $template\->output();
.Ve
.PP
HTML::Template provides a syntax to embed values into a text template:
.PP
.Vb 9
\&    <TMPL_IF NAME="user_is_dave">
\&      I\*(Aqm sorry <TMPLVAR NAME="name">, I\*(Aqm afraid I can\*(Aqt do that right now.
\&    <TMPL_ELSE>
\&      <TMPL_IF NAME="daytime_is_morning">
\&        Good morning, <TMPLVAR NAME="name">!
\&      <TMPL_ELSE>
\&        Good afternoon, <TMPLVAR NAME="name">!
\&      </TMPL_IF>
\&    </TMPL_IF>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This mixin class overrides several methods to allow MicroMason to emulate
the template syntax and some of the other features of HTML::Template.
.PP
This class automatically includes the following other mixins: TemplateDir, HasParams, and StoreOne.
.SS "Compatibility with HTML::Template"
.IX Subsection "Compatibility with HTML::Template"
This is not a drop-in replacement for HTML::Template, as the implementation is quite different, but it should be able to process most existing templates without major changes.
.PP
This should allow current HTML::Template users to take advantage of
MicroMason's one-time compilation feature, which in theory could be faster 
than HTML::Template's run-time interpretation. (No benchmarking yet.)
.PP
The following features of HTML::Template are not supported yet:
.IP "\(bu" 4
Search path for files. (Candidate for separate mixin class or addition to TemplateDir.)
.IP "\(bu" 4
Many HTML::Template options are either unsupported or have different names and need to be mapped to equivalent sets of attributes. (Transform these in the \fBnew()\fR method or croak if they're unsupported.)
.PP
The following features of HTML::Template will likely never be supported due to fundamental differences in implementation:
.IP "\(bu" 4
\&\fBquery()\fR method
.PP
Contributed patches to more closely support the behavior of HTML::Template 
would be welcomed by the author.
.SS "Template Syntax"
.IX Subsection "Template Syntax"
The following elements are recognized by the HTMLTemplate lexer:
.IP "\(bu" 4
\&\fIliteral_text\fR
.Sp
Anything not specifically parsed by the below rule is interpreted as literal text.
.IP "\(bu" 4
<\s-1TMPL_\s0\fItagname\fR>
.Sp
A template tag with no attributes.
.IP "\(bu" 4
<\s-1TMPL_\s0\fItagname\fR \fIvarname\fR>
.Sp
A template tag with a name attribute.
.IP "\(bu" 4
<\s-1TMPL_\s0\fItagname\fR NAME=\fIvarname\fR \fIoption\fR=\fIvalue\fR ...>
.Sp
A template tag with one or more attributes.
.IP "\(bu" 4
</TMPL_\fItagname\fR>
.Sp
A closing template tag.
.PP
The following tags are supported by the HTMLTemplate assembler:
.IP "tmpl_var" 4
.IX Item "tmpl_var"
<tmpl_var name=... ( default=... ) ( escape=... ) >
.IP "tmpl_include" 4
.IX Item "tmpl_include"
<tmpl_include name=... >
.IP "tmpl_if" 4
.IX Item "tmpl_if"
<tmpl_if name=... > ... </tmpl_if>
.IP "tmpl_unless" 4
.IX Item "tmpl_unless"
<tmpl_unless name=...> ... </tmpl_unless>
.IP "tmpl_else" 4
.IX Item "tmpl_else"
<tmpl_else>
.IP "tmpl_loop" 4
.IX Item "tmpl_loop"
<tmpl_loop name=...> ... </tmpl_loop>
.SS "Supported Attributes"
.IX Subsection "Supported Attributes"
.IP "associate" 4
.IX Item "associate"
Optional reference to a \s-1CGI\s0 parameter object or other object with a similar \fBparam()\fR method.
.ie n .IP "loop_global_vars (HTML::Template's ""global_vars"")" 4
.el .IP "loop_global_vars (HTML::Template's ``global_vars'')" 4
.IX Item "loop_global_vars (HTML::Template's global_vars)"
If set to true, don't hide external parameters inside a loop scope.
.IP "loop_context_vars" 4
.IX Item "loop_context_vars"
If set to true, defines additional variables within each <\s-1TMPL_LOOP\s0>: _\|_counter_\|_, which specifies the row index, and four boolean flags, _\|_odd_\|_, _\|_first_\|_, _\|_inner_\|_, and _\|_last_\|_.
.SS "Public Methods"
.IX Subsection "Public Methods"
.IP "\fBnew()\fR" 4
.IX Item "new()"
Creates a new Mason object. If a filename parameter is supplied, the corresponding file is compiled.
.IP "\fBparam()\fR" 4
.IX Item "param()"
Gets and sets parameter arguments. Similar to the \fBparam()\fR method provied by HTML::Template and the \s-1CGI\s0 module.
.IP "\fBoutput()\fR" 4
.IX Item "output()"
Executes the most-recently compiled template and returns the results.
.Sp
Optionally accepts a filehandle to print the results to.
.Sp
.Vb 1
\&  $template\->output( print_to => *STDOUT );
.Ve
.SS "Private Methods"
.IX Subsection "Private Methods"
.IP "lex_token" 4
.IX Item "lex_token"
.Vb 1
\&  ( $type, $value ) = $mason\->lex_token();
.Ve
.Sp
Lexer for <TMPL_x> tags.
.Sp
Attempts to parse a token from the template text stored in the global \f(CW$_\fR and returns a token type and value. Returns an empty list if unable to parse further due to an error.
.IP "\fBparse_args()\fR" 4
.IX Item "parse_args()"
Lexer for arguments within a tag.
.IP "assemble_tmpl_*()" 4
.IX Item "assemble_tmpl_*()"
These methods define the mapping from the template tags to the equivalent Perl code.
.IP "\fBfilter()\fR" 4
.IX Item "filter()"
Used to implement the escape option for tmpl_var.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The interface being emulated is described in HTML::Template.
.PP
For an overview of this templating framework, see Text::MicroMason.
.PP
This is a mixin class intended for use with Text::MicroMason::Base.
.PP
For distribution, installation, support, copyright and license 
information, see Text::MicroMason::Docs::ReadMe.