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 & 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.