Provided by: libcgi-application-plugin-anytemplate-perl_0.18-1_all bug

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.

perl v5.10.1                                2011-CGI::Application::Plugin::AnyTemplate::Base(3pm)