.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate 3pm"
.TH CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate 3pm "2020-10-26" "perl v5.30.3" "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"
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate \- HTML::Template driver to AnyTemplate
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a driver for CGI::Application::Plugin::AnyTemplate, which
provides the implementation details specific to rendering templates via
the HTML::Template templating system.
.PP
All \f(CW\*(C`AnyTemplate\*(C'\fR drivers are designed to be used the same way.  For
general usage instructions, see the documentation of
CGI::Application::Plugin::AnyTemplate.
.SH "EMBEDDED COMPONENT SYNTAX (HTML::Template)"
.IX Header "EMBEDDED COMPONENT SYNTAX (HTML::Template)"
.SS "Syntax"
.IX Subsection "Syntax"
The HTML::Template syntax for embedding components is:
.PP
.Vb 1
\&    <TMPL_VAR NAME="cgiapp_embed(\*(Aqsome_run_mode\*(Aq, param1, param2, \*(Aqliteral string3\*(Aq)">
.Ve
.PP
\&\fI(Support for parameter passing is limited.  See the note on parameters below.)\fR
.PP
This can be overridden by the following configuration variables:
.PP
.Vb 1
\&    embed_tag_name       # default \*(Aqcgiapp_embed\*(Aq
.Ve
.PP
For instance by setting the following value in your configuration file:
.PP
.Vb 1
\&    embed_tag_name       \*(Aq***component***\*(Aq
.Ve
.PP
Then the embedded component tag will look like:
.PP
.Vb 1
\&    <TMPL_VAR NAME="***component***(\*(Aqsome_run_mode\*(Aq)">
.Ve
.SS "Parameters"
.IX Subsection "Parameters"
Since HTML::Template doesn't support parameter passing in the
template, the \f(CW\*(C`HTMLTemplate\*(C'\fR driver emulates this behaviour.
.PP
The parameter list passed to the embed subroutine is parsed before
the template is parsed.  Literal strings (strings enclosed in single or
double quotes) are passed verbatim to the target run mode.  Params not
enclosed in quotes are looked up in \f(CW\*(C`$self\->param\*(C'\fR; the resulting
literal or looked up values are passed to the target run mode.  Finally,
the return value of the run mode (its output) is passed as a parameter
value to the template.
.PP
Note that the param lookup scheme is somewhat simplistic.  For instance,
it does not respect the scope of loops or conditional constructs within
the template.
.PP
For proper parameter handling using HTML::Template\-style templates,
use either the
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr
or the CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplatePluggable
driver instead.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate driver
accepts the following config parameters:
.IP "embed_tag_name" 4
.IX Item "embed_tag_name"
The name of the tag used for embedding components.  Defaults to
\&\f(CW\*(C`cgiapp_embed\*(C'\fR.
.IP "template_extension" 4
.IX Item "template_extension"
If \f(CW\*(C`auto_add_template_extension\*(C'\fR is true, then
CGI::Application::Plugin::AnyTemplate will append the value of
\&\f(CW\*(C`template_extension\*(C'\fR to \f(CW\*(C`filename\*(C'\fR.  By default
the \f(CW\*(C`template_extension\*(C'\fR is \f(CW\*(C`.html\*(C'\fR.
.IP "associate_query" 4
.IX Item "associate_query"
\&\fBThis feature is now deprecated and will be removed in a future release.\fR
.Sp
If this config parameter is true, then
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate will
copy all of the webapp's query params into the template using
HTML::Template's \f(CW\*(C`associate\*(C'\fR mechanism:
.Sp
.Vb 3
\&    my $driver = HTML::Template\->new(
\&        associate => $self\->query,
\&    );
.Ve
.Sp
By default \f(CW\*(C`associate_query\*(C'\fR is false.
.Sp
If you provide an \f(CW\*(C`associate\*(C'\fR config parameter of your own, that will
disable the \f(CW\*(C`associate_query\*(C'\fR functionality.
.PP
All other configuration parameters are passed on unchanged to HTML::Template.
.SS "required_modules"
.IX Subsection "required_modules"
The \f(CW\*(C`required_modules\*(C'\fR function returns the modules required for this driver
to operate.  In this case: HTML::Template.
.SH "DRIVER METHODS"
.IX Header "DRIVER METHODS"
.IP "initialize" 4
.IX Item "initialize"
Initializes the \f(CW\*(C`HTMLTemplate\*(C'\fR driver.  See the docs for
\&\f(CW\*(C`CGI::Application::Plugin::AnyTemplate::Base\*(C'\fR for details.
.IP "render_template" 4
.IX Item "render_template"
Fills the \f(CW\*(C`HTML::Template\*(C'\fR object with \f(CW\*(C`$self\->param\*(C'\fR
replacing any magic \f(CW\*(C`*embed*\*(C'\fR tags with the content generated by the
appropriate runmodes.
.Sp
Returns the output of the filled template as a string reference.
.Sp
See the docs for \f(CW\*(C`CGI::Application::Plugin::AnyTemplate::Base\*(C'\fR for details.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 7
\&    CGI::Application::Plugin::AnyTemplate
\&    CGI::Application::Plugin::AnyTemplate::Base
\&    CGI::Application::Plugin::AnyTemplate::ComponentHandler
\&    CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr
\&    CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplatePluggable
\&    CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit
\&    CGI::Application::Plugin::AnyTemplate::Driver::Petal
\&
\&    CGI::Application
\&
\&    Template::Toolkit
\&    HTML::Template
\&
\&    HTML::Template::Pluggable
\&    HTML::Template::Plugin::Dot
\&
\&    Petal
\&
\&    Exporter::Renaming
\&
\&    CGI::Application::Plugin::TT
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Graham, \f(CW\*(C`<mgraham@cpan.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2005 Michael Graham, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.