--- name: "CGI::Application::Plugin::AnyTemplate::Base" section: "3pm" platform: "linux" package: "libcgi-application-plugin-anytemplate-perl" version: "0.18-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/CGI::Application::Plugin::AnyTemplate::Base" --- # CGI::Application::Plugin::AnyTemplate::Base(3pm) Base class for templates ## 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, `""` ## BUGS Please report any bugs or feature requests to `"bug-cgi-application-plugin-anytemplate@rt.cpan.org"`, or through the web interface at \. 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.