view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/AnyTemplate/Driver/HTMLTemplate.pm  view on Meta::CPAN

package CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate;

=head1 NAME

CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate - HTML::Template driver to AnyTemplate

=head1 DESCRIPTION

This is a driver for L<CGI::Application::Plugin::AnyTemplate>, which
provides the implementation details specific to rendering templates via
the L<HTML::Template> templating system.

All C<AnyTemplate> drivers are designed to be used the same way.  For
general usage instructions, see the documentation of
L<CGI::Application::Plugin::AnyTemplate>.

=head1 EMBEDDED COMPONENT SYNTAX (HTML::Template)

=head2 Syntax

The L<HTML::Template> syntax for embedding components is:

    <TMPL_VAR NAME="cgiapp_embed('some_run_mode', param1, param2, 'literal string3')">

I<(Support for parameter passing is limited.  See the note on paramters below.)>

This can be overridden by the following configuration variables:

    embed_tag_name       # default 'cgiapp_embed'

For instance by setting the following value in your configuration file:

    embed_tag_name       '***component***'

Then the embedded component tag will look like:

    <TMPL_VAR NAME="***component***('some_run_mode')">

=head2 Parameters

Since L<HTML::Template> doesn't support parameter passing in the
template, the C<HTMLTemplate> driver emulates this behaviour.

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 C<< $self->param >>; 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.

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.

For proper parameter handling using L<HTML::Template>-style templates,
use either the
L<CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr>
or the L<CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplatePluggable>
driver instead.


=cut


use strict;
use Carp;

use CGI::Application::Plugin::AnyTemplate::ComponentHandler;

use CGI::Application::Plugin::AnyTemplate::Base;
use vars qw(@ISA);
@ISA = ('CGI::Application::Plugin::AnyTemplate::Base');

=head1 CONFIGURATION

The L<CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate> driver