Man pages sections > man3 > CGI::Application::Plugin::AnyTemplate::Base

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

CGI::Application::Plugin::AnyTemplate::Base(3pm) User Contributed Perl Documentation CGI::Application::Plugin::AnyTemplate::Base(3pm)

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 parameters 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 overridden 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, "<mgraham@cpan.org>"

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.

SOURCE

The source code repository for this module can be found at http://github.com/mgraham/CAP-AnyTemplate/

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 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.
2015-06-07 perl v5.20.2