.\" 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::Base 3pm"
.TH CGI::Application::Plugin::AnyTemplate::Base 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::Base \- Base class for templates
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This documentation is mainly for developers who want to write additional
Template drivers. For how to use the system, see the docs for
CGI::Application::Plugin::AnyTemplate
.SH "METHODS"
.IX Header "METHODS"
.IP "param" 4
.IX Item "param"
The \f(CW\*(C`param\*(C'\fR method gets and sets values within the template.
.Sp
.Vb 1
\&    my $template = $self\->template\->load;
\&
\&    my @param_names = $template\->param();
\&
\&    my $value = $template\->param(\*(Aqname\*(Aq);
\&
\&    $template\->param(\*(Aqname\*(Aq => \*(Aqvalue\*(Aq);
\&    $template\->param(
\&        \*(Aqname1\*(Aq => \*(Aqvalue1\*(Aq,
\&        \*(Aqname2\*(Aq => \*(Aqvalue2\*(Aq
\&    );
.Ve
.Sp
It is designed to behave similarly to the \f(CW\*(C`param\*(C'\fR method in other modules like
\&\f(CW\*(C`CGI\*(C'\fR and \f(CW\*(C`HTML::Template\*(C'\fR.
.IP "get_param_hash" 4
.IX Item "get_param_hash"
Returns the template variables as a hash of names and values.
.Sp
.Vb 1
\&    my %params     = $template\->get_param_hash;
.Ve
.Sp
In a scalar context, returns a reference to the hash used
internally to contain the values:
.Sp
.Vb 1
\&    my $params_ref = $template\->get_param_hash;
.Ve
.IP "clear_params" 4
.IX Item "clear_params"
Clears the values stored in the template:
.Sp
.Vb 8
\&    $template\->param(
\&        \*(Aqname1\*(Aq => \*(Aqvalue1\*(Aq,
\&        \*(Aqname1\*(Aq => \*(Aqvalue2\*(Aq
\&    );
\&    $template\->clear_params;
\&    $template\->param(
\&        \*(Aqname_foo\*(Aq => \*(Aqvalue_bar\*(Aq,
\&    );
\&
\&    # params are now:
\&        \*(Aqname_foo\*(Aq => \*(Aqvalue_bar\*(Aq,
.Ve
.IP "output" 4
.IX Item "output"
Returns the template with all the values filled in.
.Sp
.Vb 1
\&    return $template\->output();
.Ve
.Sp
You can also supply names and values to the template at this stage:
.Sp
.Vb 1
\&    return $template\->output(\*(Aqname\*(Aq => \*(Aqvalue\*(Aq, \*(Aqname2\*(Aq => \*(Aqvalue2\*(Aq);
.Ve
.Sp
Before the template output is generated, the \f(CW\*(C`template_pre_process\*(C'\fR
hook is called.  Any callbacks that you register to this hook will be
called before each template is processed.  Register a
\&\f(CW\*(C`template_pre_process\*(C'\fR callback as follows:
.Sp
.Vb 4
\&    $self\->add_callback(
\&        \*(Aqtemplate_pre_process\*(Aq,
\&        \e&my_tmpl_pre_process
\&    );
.Ve
.Sp
Pre-process callbacks will be passed a reference to the \f(CW$template\fR
object, and can can modify the parameters passed into the template by
using the \f(CW\*(C`param\*(C'\fR method:
.Sp
.Vb 2
\&    sub my_tmpl_pre_process {
\&        my ($self, $template) = @_;
\&
\&        # Change the internal template parameters by reference
\&        my $params = $template\->get_param_hash;
\&
\&        foreach my $key (keys %$params) {
\&            $params{$key} = to_piglatin($params{$key});
\&        }
\&
\&        # Can also set values using the param method
\&        $template\->param(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq);
\&
\&    }
.Ve
.Sp
After the template output is generated, the \f(CW\*(C`template_post_process\*(C'\fR hook is called.
You can register a \f(CW\*(C`template_post_process\*(C'\fR callback as follows:
.Sp
.Vb 3
\&    $self\->add_callback(\*(Aqtemplate_post_process\*(Aq,
\&                        \e&my_tmpl_post_process
\&    );
.Ve
.Sp
Any callbacks that you register to this hook will be called after each
template is processed, and will be passed both a reference to the
template object and a reference to the output generated by the template.
This allows you to modify the output of the template:
.Sp
.Vb 2
\&    sub my_tmpl_post_process {
\&        my ($self, $template, $output_ref) = @_;
\&
\&        $$output_ref =~ s/foo/bar/;
\&    }
.Ve
.Sp
When you call the \f(CW\*(C`output\*(C'\fR method, any components embedded in the
template are run.  See \f(CW\*(C`EMBEDDED COMPONENTS\*(C'\fR, below.
.IP "filename" 4
.IX Item "filename"
If the template was loaded from a file, the \f(CW\*(C`filename\*(C'\fR method returns the template filename.
.IP "string_ref" 4
.IX Item "string_ref"
If the template was loaded from a string, the \f(CW\*(C`string_ref\*(C'\fR method returns a reference to the string.
.IP "object" 4
.IX Item "object"
Returns a reference to the underlying template driver, e.g. the
\&\f(CW\*(C`HTML::Template\*(C'\fR object or the \f(CW\*(C`Template::Toolkit\*(C'\fR object.
.SH "DOCS FOR TEMPLATE MODULE DEVELOPERS"
.IX Header "DOCS FOR TEMPLATE MODULE DEVELOPERS"
The following documentation is of interest primarly for developers who
wish to add support for a new type of Template system.
.SS "\s-1METHODS FOR DEVELOPERS\s0"
.IX Subsection "METHODS FOR DEVELOPERS"
.IP "initialize" 4
.IX Item "initialize"
This method is called by the controller at \f(CW\*(C`load\*(C'\fR to create the
driver-specific subclass of \f(CW\*(C`CGI::Application::Plugin::AnyTemplate\*(C'\fR
.Sp
This is a virtual method and must be defined in the subclass.
.Sp
The following parameters are passed to the driver and available as keys of the
driver's \f(CW$self\fR object:
.Sp
.Vb 7
\&     \*(Aqdriver_config\*(Aq => ...    # hashref of driver\-specific config
\&     \*(Aqnative_config\*(Aq => ...    # hashref of native template system
\&                               # specific config
\&     \*(Aqinclude_paths\*(Aq => ...    # listref of template include paths
\&     \*(Aqfilename\*(Aq      => ...    # template filename
\&     \*(Aqwebapp\*(Aq        => ...    # reference to the current
\&                               # CGI::Application $self
.Ve
.IP "driver_config_keys" 4
.IX Item "driver_config_keys"
When it creates the driver object,
\&\f(CW\*(C`CGI::Application::Plugin::AnyTemplate\*(C'\fR has to separate the
\&\f(CW\*(C`driver_config\*(C'\fR from the \f(CW\*(C`native_config\*(C'\fR.
.Sp
\&\f(CW\*(C`driver_config_params\*(C'\fR should return a list of parameters that are
specific to the driver_config and not the native template system
config.
.Sp
For instance, the user can specify
.Sp
.Vb 8
\&    $self\->template\->config(
\&        HTMLTemplate => {
\&              embed_tag_name    => \*(Aqembed\*(Aq,
\&              global_vars       => 1,
\&              die_on_bad_params => 0,
\&              cache             => 1
\&        },
\&    );
.Ve
.Sp
The parameters \f(CW\*(C`global_vars\*(C'\fR, \f(CW\*(C`die_on_bad_params\*(C'\fR, and \f(CW\*(C`cache\*(C'\fR are all
specific to HTML::Template.  These are considered \fInative\fR parameters.
.Sp
But \f(CW\*(C`embed_tag_name\*(C'\fR configures the
\&\f(CW\*(C`CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate\*(C'\fR subclass.  This
is considered a \fIdriver\fR parameter.
.Sp
Therefore \f(CW\*(Aqembed_tag_name\*(Aq\fR should be included in the list of
params returned by \f(CW\*(C`driver_config_params\*(C'\fR.
.Sp
Example \f(CW\*(C`driver_config_params\*(C'\fR:
.Sp
.Vb 4
\&    sub driver_config_keys {
\&        \*(Aqtemplate_extension\*(Aq,
\&        \*(Aqembed_tag_name\*(Aq
\&    }
.Ve
.IP "default_driver_config" 4
.IX Item "default_driver_config"
Should return a hash of default values for \f(CW\*(C`driver_config_params\*(C'\fR.
.Sp
For instance:
.Sp
.Vb 6
\&    sub default_driver_config {
\&        {
\&            template_extension => \*(Aq.foo\*(Aq,
\&            embed_tag_name     => \*(Aqembed\*(Aq,
\&        };
\&    }
.Ve
.IP "render_template" 4
.IX Item "render_template"
This method must be overridden in a subclass.  It has the responsibility
of filling the template in \f(CW\*(C`$self\->filename\*(C'\fR with the values in \f(CW\*(C`$self\->param\*(C'\fR
via the appropriate template system, and returning the output as either
a string or a reference to a string.
.Sp
It also must manage embedding nested components.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Graham, \f(CW\*(C`<mgraham@cpan.org>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-cgi\-application\-plugin\-anytemplate@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>.  I will be notified, and then you'll automatically
be notified of progress on your bug as I make changes.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for this module can be found at http://github.com/mgraham/CAP\-AnyTemplate/
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 7
\&    CGI::Application::Plugin::AnyTemplate
\&    CGI::Application::Plugin::AnyTemplate::ComponentHandler
\&    CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate
\&    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
\&
\&    CGI::Application::Plugin::TT
.Ve
.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.