.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 3"
.TH CGI::Application::Plugin::AnyTemplate::Base 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.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;
.Ve
.Sp
.Vb 1
\&    my @param_names = $template->param();
.Ve
.Sp
.Vb 1
\&    my $value = $template->param('name');
.Ve
.Sp
.Vb 5
\&    $template->param('name' => 'value');
\&    $template->param(
\&        'name1' => 'value1',
\&        'name2' => 'value2'
\&    );
.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(
\&        'name1' => 'value1',
\&        'name1' => 'value2'
\&    );
\&    $template->clear_params;
\&    $template->param(
\&        'name_foo' => 'value_bar',
\&    );
.Ve
.Sp
.Vb 2
\&    # params are now:
\&        'name_foo' => 'value_bar',
.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('name' => 'value', 'name2' => 'value2');
.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 1
\&    $self->add_callback('template_pre_process', \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) = @_;
.Ve
.Sp
.Vb 2
\&        # Change the internal template parameters by reference
\&        my $params = $template->get_param_hash;
.Ve
.Sp
.Vb 3
\&        foreach my $key (keys %$params) {
\&            $params{$key} = to_piglatin($params{$key});
\&        }
.Ve
.Sp
.Vb 2
\&        # Can also set values using the param method
\&        $template->param('foo', 'bar');
.Ve
.Sp
.Vb 1
\&    }
.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 1
\&    $self->add_callback('template_post_process', \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) = @_;
.Ve
.Sp
.Vb 2
\&        $$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.
.Sh "\s-1METHODS\s0 \s-1FOR\s0 \s-1DEVELOPERS\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 paramters are passed to the driver and available as keys of the
driver's \f(CW$self\fR object:
.Sp
.Vb 5
\&     'driver_config' => ...    # hashref of driver-specific config
\&     'native_config' => ...    # hashref of native template system specific config
\&     'include_paths' => ...    # listref of template include paths
\&     'filename'      => ...    # template filename
\&     'webapp'        => ...    # 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    => 'embed',
\&              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'embed_tag_name'\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 {
\&        'template_extension',
\&        'embed_tag_name'
\&    }
.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 => '.foo',
\&            embed_tag_name     => 'embed',
\&        };
\&    }
.Ve
.IP "render_template" 4
.IX Item "render_template"
This method must be overriden 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`<mag\-perl@occamstoothbrush.com>\*(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 "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
.Ve
.PP
.Vb 1
\&    CGI::Application
.Ve
.PP
.Vb 2
\&    Template::Toolkit
\&    HTML::Template
.Ve
.PP
.Vb 2
\&    HTML::Template::Pluggable
\&    HTML::Template::Plugin::Dot
.Ve
.PP
.Vb 1
\&    Petal
.Ve
.PP
.Vb 1
\&    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.