NAME

CGI::Application::Plugin::AnyTemplate::Base - Base class for templates

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

METHODS

param

The param method gets and sets values within the template.

my $template = $self->template->load;

my @param_names = $template->param();

my $value = $template->param('name');

$template->param('name' => 'value');
$template->param(
    'name1' => 'value1',
    'name2' => 'value2'
);

It is designed to behave similarly to the param method in other modules like CGI and HTML::Template.

get_param_hash

Returns the template variables as a hash of names and values.

my %params     = $template->get_param_hash;

In a scalar context, returns a reference to the hash used internally to contain the values:

my $params_ref = $template->get_param_hash;

clear_params

Clears the values stored in the template:

$template->param(
    'name1' => 'value1',
    'name1' => 'value2'
);
$template->clear_params;
$template->param(
    'name_foo' => 'value_bar',
);

# params are now:
    'name_foo' => 'value_bar',

output

Returns the template with all the values filled in.

return $template->output();

You can also supply names and values to the template at this stage:

return $template->output('name' => 'value', 'name2' => 'value2');

Before the template output is generated, the template_pre_process hook is called. Any callbacks that you register to this hook will be called before each template is processed. Register a template_pre_process callback as follows:

$self->add_callback('template_pre_process', \&my_tmpl_pre_process);

Pre-process callbacks will be passed a reference to the $template object, and can can modify the parameters passed into the template by using the param method:

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('foo', 'bar');

}

After the template output is generated, the template_post_process hook is called. You can register a template_post_process callback as follows:

$self->add_callback('template_post_process', \&my_tmpl_post_process);

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:

sub my_tmpl_post_process {
    my ($self, $template, $output_ref) = @_;

    $$output_ref =~ s/foo/bar/;
}

When you call the output method, any components embedded in the template are run. See EMBEDDED COMPONENTS, below.

filename

If the template was loaded from a file, the filename method returns the template filename.

string_ref

If the template was loaded from a string, the string_ref method returns a reference to the string.

object

Returns a reference to the underlying template driver, e.g. the HTML::Template object or the Template::Toolkit object.

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.

METHODS FOR DEVELOPERS

initialize

This method is called by the controller at load to create the driver-specific subclass of CGI::Application::Plugin::AnyTemplate

This is a virtual method and must be defined in the subclass.

The following paramters are passed to the driver and available as keys of the driver's $self object:

'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

driver_config_keys

When it creates the driver object, CGI::Application::Plugin::AnyTemplate has to separate the driver_config from the native_config.

driver_config_params should return a list of parameters that are specific to the driver_config and not the native template system config.

For instance, the user can specify

$self->template->config(
    HTMLTemplate => {
          embed_tag_name    => 'embed',
          global_vars       => 1,
          die_on_bad_params => 0,
          cache             => 1
    },
);

The parameters global_vars, die_on_bad_params, and cache are all specific to HTML::Template. These are considered native parameters.

But embed_tag_name configures the CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate subclass. This is considered a driver parameter.

Therefore 'embed_tag_name' should be included in the list of params returned by driver_config_params.

Example driver_config_params:

sub driver_config_keys {
    'template_extension',
    'embed_tag_name'
}

default_driver_config

Should return a hash of default values for driver_config_params.

For instance:

sub default_driver_config {
    {
        template_extension => '.foo',
        embed_tag_name     => 'embed',
    };
}

render_template

This method must be overriden in a subclass. It has the responsibility of filling the template in $self->filename with the values in $self->param via the appropriate template system, and returning the output as either a string or a reference to a string.

It also must manage embedding nested components.

AUTHOR

Michael Graham, <mag-perl@occamstoothbrush.com>

BUGS

Please report any bugs or feature requests to bug-cgi-application-plugin-anytemplate@rt.cpan.org, 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.

SEE ALSO

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

COPYRIGHT & LICENSE

Copyright 2005 Michael Graham, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.