Base class for templates
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
The \*(C`param\*(C' 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 \*(C`param\*(C' method in other modules like \*(C`CGI\*(C' and \*(C`HTML::Template\*(C'.
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;
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',
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 \*(C`template_pre_process\*(C' hook is called. Any callbacks that you register to this hook will be called before each template is processed. Register a \*(C`template_pre_process\*(C' 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 \*(C`param\*(C' 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 \*(C`template_post_process\*(C' hook is called. You can register a \*(C`template_post_process\*(C' 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 \*(C`output\*(C' method, any components embedded in the template are run. See \*(C`EMBEDDED COMPONENTS\*(C', below.
If the template was loaded from a file, the \*(C`filename\*(C' method returns the template filename.
If the template was loaded from a string, the \*(C`string_ref\*(C' method returns a reference to the string.
Returns a reference to the underlying template driver, e.g. the \*(C`HTML::Template\*(C' object or the \*(C`Template::Toolkit\*(C' object.
The following documentation is of interest primarly for developers who wish to add support for a new type of Template system.
This method is called by the controller at \*(C`load\*(C' to create the driver-specific subclass of \*(C`CGI::Application::Plugin::AnyTemplate\*(C' 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
When it creates the driver object, \*(C`CGI::Application::Plugin::AnyTemplate\*(C' has to separate the \*(C`driver_config\*(C' from the \*(C`native_config\*(C'. \*(C`driver_config_params\*(C' 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 \*(C`global_vars\*(C', \*(C`die_on_bad_params\*(C', and \*(C`cache\*(C' are all specific to HTML::Template. These are considered native parameters. But \*(C`embed_tag_name\*(C' configures the \*(C`CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate\*(C' subclass. This is considered a driver parameter. Therefore 'embed_tag_name' should be included in the list of params returned by \*(C`driver_config_params\*(C'. Example \*(C`driver_config_params\*(C': sub driver_config_keys { 'template_extension', 'embed_tag_name' }
Should return a hash of default values for \*(C`driver_config_params\*(C'. For instance: sub default_driver_config { { template_extension => '.foo', embed_tag_name => 'embed', }; }
This method must be overridden in a subclass. It has the responsibility of filling the template in \*(C`$self->filename\*(C' with the values in \*(C`$self->param\*(C' 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.
Michael Graham, \*(C`<[email protected]>\*(C'
Please report any bugs or feature requests to \*(C`[email protected]\*(C', 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.
The source code repository for this module can be found at http://github.com/mgraham/CAP-AnyTemplate/
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.