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

NAME

       CGI::Application::Plugin::AnyTemplate - Use any templating system from within
       CGI::Application using a unified interface

VERSION

       Version 0.18

SYNOPSIS

       In your CGI::Application-based webapp:

           use base 'CGI::Application';
           use CGI::Application::Plugin::AnyTemplate;

           sub cgiapp_init {
               my $self = shift;

               # Set template options
               $self->template->config(
                   default_type => 'TemplateToolkit',
               );
           }

       Later on, in a runmode:

           sub my_runmode {
               my $self = shift;

               my %template_params = (
                   name     => 'Winston Churchill',
                   age      => 7,
               );

               $self->template->fill('some_template', \%template_params);
           }

DESCRIPTION

   Template-Independence
       "CGI::Application::Plugin::AnyTemplate" allows you to use any supported Perl templating
       system using a single consistent interface.

       Currently supported templating systems include HTML::Template, HTML::Template::Expr,
       HTML::Template::Pluggable, Template::Toolkit and Petal.

       You can access any of these templating systems using the same interface.  In this way, you
       can use the same code and switch templating systems on the fly.

       This approach has many uses.  For instance, it can be useful in migrating your application
       from one templating system to another.

   Embedded Components
       In addition to template abstraction, "AnyTemplate" also provides a embedded component
       mechanism.  For instance, you might include a header component at the top of every page
       and a footer component at the bottom of every page.

       These components are actually full CGI::Application run modes, and can do anything normal
       run mode can do, including processing form parameters and filling in their own templates.
       See below under "EMBEDDED COMPONENTS" for details.

   Multiple Named Template Configurations
       You can set up multiple named template configurations and select between them at run time.

           sub cgiapp_init {
               my $self = shift;

               # Can't use Template::Toolkit any more -
               # The boss wants everything has to be XML,
               # so we switch to Petal

               # Set old-style template options (legacy scripts)
               $self->template('oldstyle')->config(
                   default_type => 'TemplateToolkit',
                   TemplateToolkit => {
                       POST_CHOMP => 1,
                   }
               );
               # Set new-style template options as default
               $self->template->config(
                   default_type => 'Petal',
                   auto_add_template_extension => 0,
               );
           }

           sub old_style_runmode {
               my $self = shift;

               # ...

               # use TemplateToolkit to fill template edit_user.tmpl
               $self->template('oldstyle')->fill('edit_user', \%params);

           }

           sub new_style_runmode {
               my $self = shift;

               # ...

               # use Petal to fill template edit_user.xhml
               $self->template->fill('edit_user.xhtml', \%params);

           }

   Flexible Syntax
       The syntax is pretty flexible.  Pick a style that's most comfortable for you.

       CGI::Application::Plugin::TT style syntax

           $self->template->process('edit_user', \%params);

       or (with slightly less typing):

           $self->template->fill('edit_user', \%params);

       CGI::Application load_tmpl style syntax

           my $template = $self->template->load('edit_user');
           $template->param('foo' => 'bar');
           $template->output;

       Verbose syntax (for complete control)

           my $template = $self->template('named_config')->load(
               file              => 'edit_user'
               type              => 'TemplateToolkit'
               add_include_paths => '.',
           );

           $template->param('foo' => 'bar');
           $template->output;

       See also below under "CHANGING THE NAME OF THE 'template' METHOD".

METHODS

   config
       Initialize the "AnyTemplate" system and provide the default configuration.

           $self->template->config(
               default_type => 'HTMLTemplate',
           );

       You can keep multiple configurations handy at the same time by passing a value to
       "template":

           $self->template('oldstyle')->config(
               default_type => 'HTML::Template',
           );
           $self->template('newstyle')->config(
               default_type => 'HTML::Template::Expr',
           );

       Then in a runmode you can mix and match configurations:

           $self->template('oldstyle')->load  # loads an HTML::Template driver object
           $self->template('newstyle')->load  # loads an HTML::Template::Expr driver object

       The configuration passed to "config" is divided into three areas: plugin configuration,
       driver configuration, and native configuration:

           Config Type       What it Configures
           -----------       ------------------
           Plugin Config     AnyTemplate itself
           Driver Config     AnyTemplate Driver (e.g. HTMLTemplate)
           Native Config     Actual template module (e.g. HTML::Template)

       These are described in more detail below.

       Plugin Configuration

       These configuration params are specific to the "CGI::Application::Plugin::AnyTemplate"
       itself.  They are included at the top level of the configuration hash passed to "config".
       For instance:

           $self->template->config(
               default_type                => 'HTMLTemplate',
               auto_add_template_extension => 0,
           );

       The plugin configuration parameters and their defaults are as follows:

       default_type
       type
           The default type of template for this named configuration.  Should be the name of a
           driver in the "CGI::Application::Plugin::AnyTemplate::Driver" namespace:

               Type                Driver
               ----                ------
               HTMLTemplate        CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate
               HTMLTemplateExpr    CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr
               TemplateToolkit     CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit
               Petal               CGI::Application::Plugin::AnyTemplate::Driver::Petal

       include_paths
           Include Paths (sometimes called search paths) are used by the various template
           backends to find filenames that aren't fully qualified by an absolute path.  Each
           directory is searched in turn until the template file is found.

           Can be a single string or a reference to a list.

       auto_add_template_extension
           Add a template-system specific extension to template filenames.

           So, if this feature is enabled and you provide the filename "myfile", then the actual
           filename will depend on the current template driver:

               Driver                 Template
               ------                 --------
               HTMLTemplate           myfile.html
               HTMLTemplateExpr       myfile.html
               TemplateToolkit        myfile.tmpl
               Petal                  myfile.xhtml

           The per-type extension is controlled by the driver config for each "AnyTemplate"
           driver (see below under "Driver and Native Configuration" for how to set this).

           The "auto_add_template_extension" feature is on by default.  To disable it, pass a
           value of zero:

               $self->template->config(
                   auto_add_template_extension => 0,
               );

           The automatic extension feature is not just there to save typing - it's actually there
           so you can have templates of different types sitting in the same directory.

               sub my_runmode {
                   my $self = shift;
                   $self->template->fill;
               }

           Then in your template path you can have three files:

               my_runmode.html
               my_runmode.tmpl
               my_runmode.xhtml

           Then you can change which templates is used by changing the value of "type" that you
           pass to "$self->template->config".

           For applications that want to dynamically choose their template system without
           changing app code, it's a cleaner solution to use the extensions than trying to swap
           template paths at runtime.  Even if you keep each type of template in its own
           directory, it's simpler to include all the directories all the time and use different
           extensions for different template types.

       template_filename_generator
           If you don't pass a filename to "load", one will be generated for you based on the
           current run mode.  If you want to customize this process, you can pass a reference to
           a subroutine to do the translation.  This subroutine will be passed a reference to the
           CGI::Application $self object.

           Here is a subroutine that emulates the built-in behaviour of "AnyTemplate":

               $self->template->config(
                   template_filename_generator => sub {
                       my ($self, $calling_method_name) = @_;
                           return $self->get_current_runmode;
                       }
                   }
               );

           Here is an example of using a template filename generator to make full templates with
           full paths based on the module name as well as the current run mode (this is similar
           to how CGI::Application::Plugin::TT generates its template filenames):

               package My::WebApp;
               use File::Spec;

               sub cgiapp_init {
                   my $self = shift;

                   $self->template->config(
                       template_filename_generator => sub {
                           my $self     = shift;
                           my $run_mode = $self->get_current_runmode;
                           my $module   = ref $self;

                           my @segments = split /::/, $module;

                           return File::Spec->catfile(@segments, $run_mode);
                       }
                   );
               }

               sub run_mode {
                   my $self = shift;
                   $self->template->load;  # loads My/WebApp/run_mode.html
               }

               sub other_run_mode {
                   my $self = shift;
                   $self->template->load;  # loads My/WebApp/other_run_mode.html
               }

           Note that if the "auto_add_template_extension" option is on (which it is by default),
           then the extension will be added to your generated filename after you return it.  If
           you do not want this to happen, then set "auto_add_template_extension" to a false
           value.

       component_handler_class
           Normally, component embedding is handled by
           CGI::Application::Plugin::AnyTemplate::ComponentHandler.  If you want to use a
           different class for this purpose, specify the class name as the value of this
           parameter.

           It still has to provide the same interface as
           CGI::Application::Plugin::AnyTemplate::ComponentHandler.  See the source code of that
           module for details.

       return_references
           When true (the default), "output" will return a reference to a string rather than a
           copy.  Normally this won't matter.  For instance, "CGI::Application" doesn't care
           whether you return a string or a reference to a string from your run modes.

           However, if you want to manipulate the output of the $html returned from the template,
           you may find it convenient to make "output" return a string instead of a reference.
           Especially if you are converting old code based on HTML::Template which expects
           "output" to return a string.

       Driver and Native Configuration

       You can configure all the drivers at once with a single call to "config", by including
       subsections for each driver type:

           $self->template->config(
               default_type => 'HTMLTemplate',
               HTMLTemplate => {
                   cache              => 1,
                   global_vars        => 1,
                   die_on_bad_params  => 0,
                   template_extension => '.html',
               },
               HTMLTemplateExpr => {
                   cache              => 1,
                   global_vars        => 1,
                   die_on_bad_params  => 0,
                   template_extension => '.html',
               },
               HTMLTemplatePluggable => {
                   cache              => 1,
                   global_vars        => 1,
                   die_on_bad_params  => 0,
                   template_extension => '.html',
               },
               TemplateToolkit => {
                   POST_CHOMP         => 1,
                   template_extension => '.tmpl',
               },
               Petal => {
                   error_on_undef     => 0,
                   template_extension => '.xhtml',
               },
           );

       Each driver knows how to separate its own configuration from the configuration belonging
       to the underlying template system.

       For instance in the example above, the "HTMLTemplate" driver knows that
       "template_extension" is a driver config parameter, but "cache_global_vars" and
       "die_on_bad_params" are all HTML::Template configuration parameters.

       Similarly, The "TemplateToolkit" driver knows that template_extension is a driver config
       parameter, but "POST_CHOMP" is a "Template::Toolkit" configuration parameter.

       For details on driver configuration, see the docs for the individual drivers:

       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

       Copying Query data into Templates

       This feature is now deprecated and will be removed in a future release.

       When you enable this feature all data in "$self->query" are copied into the template
       object before the template is processed.

       For the "HTMLTemplate", "HTMLTemplateExpr" and "HTMLTemplatePluggable" drivers this is
       done with the "associate" feature of HTML::Template and HTML::Template::Expr,
       respectively:

           my $template = HTML::Template->new(
               associate => $self->query,
           );

       For the other systems, this feature is emulated, by copying the query params into the
       template params before the template is processed.

       To enable this feature, pass a true value to "associate_query" or
       "emulate_associate_query" (depending on the template system):
           $self->template->config(
               default_type => 'HTMLTemplate',
               HTMLTemplate => {
                   associate_query => 1,
               },
               HTMLTemplateExpr => {
                   associate_query => 1,
               },
               HTMLTemplatePluggable => {
                   associate_query => 1,
               },
               TemplateToolkit => {
                   emulate_associate_query => 1,
               },
               Petal => {
                   emulate_associate_query => 1,
               },
           );

       The reason this feature is now disabled by default is that it poses a potential XSS (Cross
       Site Scripting) security risk.

       The reason this feature is now deprecated is that in an ideal world developers shouldn't
       have to flatten objects and hashes in order to make them available to their templates.
       They should be able to pass the query object (or another object such as a config object)
       directly into the template:

           $template->param(
               'query' => $self->query,
               'cfg'   => $self->cfg,
               'ENV'   => $ENV,
           );

       And in the template retrieve parameters directly:

           your username: [% query.param('username') %]
           administrator: [% cfg.admin %]
           hostname:      [% ENV.SERVER_NAME %]

       This approach works with Template::Toolkit, Petal, and HTML::Template::Pluggable (via the
       HTML::Template::Plugin::Dot plugin).

       Note that "associate" and "associate_query" are not compatible.  So if you want to
       associate the query and an additional object, pass a list to "associate":

           $template->config(
               HTMLTemplate => {
                   associate => [$self->query, $self->conf]
               }
           );

   load
       Create a new template object and configure it.

       This can be as simple (and magical) as:

           my $template = $self->template->load;

       When you call "load" with no parameters, it uses the default template type, the default
       template configuration, and it determines the name of the template based on the name of
       the current run mode.  It determines the current run mode by calling
       "$self->get_current_runmode".

       If you want to have the current runmode updated when you pass control to another runmode,
       use the CGI::Application::Plugin::Forward module:

           use CGI::Application::Plugin::Forward;

           sub first_runmode {
               my $self = shift;
               return $self->forward('second_runmode');
           }
           sub second_runmode {
               my $self = shift;
               my $template = $self->template->load;  # loads 'second_runmode.html'
           }

       If instead you call "$self->other_method" directly, the value of
       "$self->get_current_runmode" will not be updated:

           sub first_runmode {
               my $self = shift;
               return $self->other_method;
           }
           sub other_method {
               my $self = shift;
               my $template = $self->template->load;  # loads 'first_runmode.html'
           }

       If you want to override the way the default template filename is generated, you can do so
       with the "template_filename_generator" configuration parameter.

       If you call "load" with one parameter, it is taken to be either the filename or a
       reference to a string containing the template text:

           my $template = $self->template->load('somefile');
           my $template = $self->template->load(\$some_text);

       If the parameter "auto_add_template_exension" is true, then the appropriate extension will
       be added for this template type.

       If you call "load" with more than one parameter, then you can specify filename and
       configuration parameters directly:

           my $template = $self->template->load(
               file                        => 'some_file.tmpl',
               type                        => 'HTMLTemplate',
               auto_add_template_extension => 0,
               add_include_paths           => '..',
               HTMLTemplate => {
                   die_on_bad_params => 1,
               },
           );

       To initialize the template from a string rather than a file, use:

           my $template = $self->template->load(
               string =>  \$some_text,
           );

       The configuration parameters you pass to "load" are merged with the configuration that was
       passed to "config".

       You can include any of the configuration parameters that you can pass to config, plus the
       following extra parameters:

       file
           If you are loading the template from a file, then the "file" parameter contains the
           template's filename.

       string
           If you are loading the template from a string, then the "string" parameter contains
           the text of the template.  It can be either a scalar or a reference to a scalar.  Both
           of the following will work:

               # passing a string
               my $template = $self->template->load(
                   string => $some_text,
               );

               # passing a reference to a string
               my $template = $self->template->load(
                   string => \$some_text,
               );

       add_include_paths
           Additional include paths.  These will be merged with "include_paths" before being
           passed to the template driver.

       The "load" method returns a template driver object.  See below under "DRIVER METHODS", for
       how to use this object.

   fill
       Fill is a convenience method which in a single step creates the template, fills it with
       the template parameters and returns its output.

       You can call it with or without a filename (or string ref).

       The code:

           $self->template->fill('filename', \%params);

       is equivalent to:

           my $template = $self->template->load('filename');
           $template->output(\%params);

       And the code:

           $self->template->fill(\$some_text, \%params);

       is equivalent to:

           my $template = $self->template->load(\$some_text);
           $template->output(\%params);

       And the code:

           $self->template->fill(\%params);

       is equivalent to:

           my $template = $self->template->load;
           $template->output(\%params);

       And the code:

           $self->template->fill('filename');

       is equivalent to:

           my $template = $self->template->load('filename');
           $template->output;

       And the code:

           $self->template->fill(\$some_text);

       is equivalent to:

           my $template = $self->template->load(\$some_text);
           $template->output;

       And the code:

           $self->template->fill;

       is equivalent to:

           my $template = $self->template->load;
           $template->output;

   process
       "process" is an alias for "fill".

APPLICATION METHODS

       These methods are called directly on your application's $self object.

   load_tmpl
       This is an emulation of CGI::Application's built-in "load_tmpl" method.  For instance:

           $self->load_tmpl('some_template.html');

       It is not exported by default.  To enable it, use:

           use CGI::Application::Plugin::AnyTemplate qw/:load_tmpl/;

       You can call it the same way as documented in "CGI::Application" and it will have the same
       effect.  However, it will respect the current template "type", so you can still use it to
       fill templates of different backends.

       The idea is that you can take an existing CGI::Application-based webapp which uses
       "HTML::Template" templates, and add the following code to it:

           use CGI::Application::Plugin::AnyTemplate qw/:load_tmpl/;

           sub setup {
               my $self = shift;
               $self->template->config(type => TemplateToolkit);
           }

       This will change all existing calls to load_tmpl within your application to use
       Template::Toolkit based templates.

       Calling:

           my $template = $self->load_tmpl('some_template.html');

       It is the equivalent of calling:

           my $template = $self->template->load(
               file => 'some_template.html',
               auto_add_template_extension => 0,
           );

       If you add extra options to "load_tmpl", these will be assumed to be HTML::Template
       specific options, with the exception of the "path" option, which will be extracted and
       used as 'add_include_paths':

           my $template = $self->load_tmpl('some_template.html',
               cache => 0,
               path  => '/path/to/templates',
           );

       This will get translated into:

           my $template = $self->template->load(
               file => 'some_template.html',
               auto_add_template_extension => 0,
               add_include_paths => '/path/to/templates',
               HTMLTemplate => {
                   cache => 0,
               }
           );

       Note that if you specify any HTML::Template-specific options here, they will completely
       overwrite any options that you passed to config.

       Some notes and caveats about using the "load_tmpl" method:

       •   This method only works for the default template configuration (i.e.
           "$self->template()").  If you set up a named configuration (e.g.
           "$self->template('myconfig')") there is no way to access it with "load_tmpl".  Since
           plugins should be using named configurations, this means that the "load_tmpl" method
           should not be used by plugins.  See "NOTES FOR AUTHORS OF PLUGINS AND REUSABLE
           APPLICATIONS", below.

       •   The "load_tmpl" method does not automatically add an extension to the filename you
           pass to it, even if you have "auto_add_template_extension" set to a true value in your
           call to "$self->template->config".

       •   The "load_tmpl" method ignores always returns a string, not a reference to a string.
           It ignores the setting of the "returns_references" option.

   tmpl_path
       You can set the template "include_paths" by calling
       "$self->tmpl_path('/path/to/templates')".

       You can also do so by passing a value to the "TMPL_PATH" parameter to your application's
       "new" method:

           my $webapp = App->new(
               TMPL_PATH => '/path/to/templates',
           );

       Paths that you set via "tmpl_path"/"TMPL_PATH" will be put last in the list of include
       paths, after "add_include_paths" and "include_paths".

DRIVER METHODS

       These are the most commonly used methods of the "AnyTemplate" driver object.  The driver
       is what you get back from calling "$self->template->load".

   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     = $self->template->get_param_hash;

       In a scalar context, returns a reference to the hash used internally to contain the
       values:

           my $params_ref = $self->template->get_param_hash;

           $params_ref->{'foo'} = 'bar';  # directly change parameter 'foo'

   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');

       If "return_references" option is set to true, then the return value of "output" will be a
       reference to a string.  If the "return_references" option is false, then a copy of the
       string will be returned.  By default "return_references" is true.

       When you call the "output" method, any components embedded in the template are run.  See
       "EMBEDDED COMPONENTS", below.

PRE- AND POST- PROCESS

       There are several ways to customize the template process.  You can modify the template
       parameters before the template is filled, and you can modify the output of the template
       after it has been filled.

       Multiple applications and plugins can hook into the template process pipeline, each making
       changes to the template input and output.

       For instance, it will be possible to make a general-purpose "CGI::Application" plugin that
       adds arbitrary data to each new template (such as query parameters or configuration data).

       Note that the API has changed for version 0.10 in a non-backwards-compatible way in order
       to use the new hook system provided by recent versions of "CGI::Application".

   The load_tmpl hook
       The "load_tmpl" hook is designed to be compatible with the "load_tmpl" hook defined by
       "CGI::Application" itself.

       The "load_tmpl" hook is called before the template object is created.  Any callbacks that
       you register to this hook will be called before each template is loaded.  Register a
       "load_tmpl" callback with:

          $self->add_callback('load_tmpl',\&my_load_tmpl);

       When the "load_tmpl" callback is executed it will be passed three arguments (adapted from
       the CGI::Application docs):

        1. A hash reference of the extra params passed into C<load_tmpl>
           (ignored by AnyTemplate with the exception of 'path')

        2. Followed by a hash reference to template parameters.
           You can modify this hash by reference to affect values that are
           actually passed to the param() method of the template object.

        3. The name of the template file.

       Here's an example stub for a load_tmpl() callback:

           sub my_load_tmpl_callback {
               my ($self, $ht_params, $tmpl_params, $tmpl_file) = @_;
               # modify $tmpl_params by reference...
           }

       Currently, of all the params in $ht_params, all but 'path' are ignored, because these are
       specific to "HTML::Template".  If you want to write a generic callback that needs to be
       able to access or modify "HTML::Template" parameters then let me know, or add a feature
       request on <http://rt.cpan.org>.

       The "path" param of $ht_params is initially set to the value of "add_include_paths" (if
       set).  Your callback can modify the "path" param, and "add_include_param" will be set to
       the result.

       Plugin authors who want to provide template processing features are encouraged to use the
       'load_tmpl' hook when possible, since it will work both with AnyTemplate and with
       CGI::Application's built-in "load_tmpl".

   The template_pre_process and template_post_process hooks
       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/;
           }

EMBEDDED COMPONENTS

   Introduction
       "CGI::Application::Plugin::AnyTemplate" allows you to include application components
       within your templates.

       For instance, you might include a header component a the top of every page and a footer
       component at the bottom of every page.

       These componenets are actually first-class run modes.  When the template engine finds a
       special tag marking an embedded component, it passes control to the run mode of that name.
       That run mode can then do whatever a normal run mode could do.  But typically it will load
       its own template and return the template's output.

       This output returned from the embedded run mode is inserted into the containing template.

       The syntax for embed components is specific to each type of template driver.

   Syntax
       HTML::Template syntax:

           <TMPL_VAR NAME="CGIAPP_embed('some_run_mode')">

       HTML::Template::Expr syntax:

           <TMPL_VAR EXPR="CGIAPP_embed('some_run_mode')">

       HTML::Template::Pluggable syntax:

           <TMPL_VAR EXPR="cgiapp.embed('some_run_mode')">

       Template::Toolkit syntax:

           [% CGIAPP.embed("some_run_mode") %]

       Petal syntax:

           <span tal:replace="structure CGIAPP/embed 'some_run_mode'">
               this text gets replaced by the output of some_run_mode
           </span>

   Getting Template Variables from the Containing Template
       The component run mode is passed a reference to the template object that contained the
       component.  The component run mode can use this object to access the params that were
       passed to the containing template.

       For instance:

           sub header {
               my ($self, $containing_template, @other_params) = @_;

               my %tmplvars = (
                   'title' => 'My glorious home page',
               );

               my $template = $self->template->load;

               $template->param(%tmplvars, $containing_template->get_param_hash);
               return $template->output;
           }

       In this example, the template values of the enclosing template would override any values
       set by the embedded component.

   Passing Parameters
       The template can pass parameters to the target run mode.  These are passed in after the
       reference to the containing template object.

       Parameters can either be literal strings, specified within the template text, or they can
       be keys that will be looked up in the template's params.

       Literal strings are enclosed in double or single quotes.  Param keys are barewords.

       HTML::Template syntax:

           <TMPL_VAR NAME="CGIAPP_embed('some_run_mode', param1, 'literal string2')">

       Note that HTML::Template doesn't support this type of callback natively and that this
       behaviour is emulated by the HTMLTemplate driver see the docs to
       CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate for limitations to the
       emulation.

       HTML::Template::Expr syntax:

           <TMPL_VAR EXPR="CGIAPP_embed('some_run_mode', param1, 'literal string2')">

       HTML::Template::Pluggable syntax:

           <TMPL_VAR EXPR="cgiapp.embed('some_run_mode', param1, 'literal string2')">

       Template::Toolkit syntax:

           [% CGIAPP.embed("some_run_mode", param1, 'literal string2' ) %]

       Petal syntax:

           <span tal:replace="structure CGIAPP/embed 'some_run_mode' param1 'literal string2' ">
               this text gets replaced by the output of some_run_mode
           </span>

NOTES FOR AUTHORS OF PLUGINS AND REUSABLE APPLICATIONS

       If you are writing a CGI::Application plugin module, or you are writing a
       "CGI::Application" program that will be distributed to other people (e.g. on CPAN), then
       it's important to take steps to prevent your application's use of
       CGI::Application::Plugin::AnyTemplate from conflicting with other plugins or with your end
       users.

       When a plugin that uses CGI::Application::Plugin::AnyTemplate calls:

          $self->template->config(...)

       It overwrites any existing template configuration with the new settings.  So if two
       plugins do that, they probably clobber each other.

       However, CGI::Application::Plugin::AnyTemplate has the feature of named independent
       configs:

          $self->template('your_module')->config(...)
          $self->template('my_plugin')->config(...)

       These configs remain separate from each other.  However, you have to keep using these
       names throughout your module, even when you load and fill the template.  For instance:

          sub my_runmode {
              my $self = shift;
              my $template = $self->template('my_plugin')->load;
              $template->output;
          }

          sub your_runmode {
              my $self = shift;
              my %params;
              $self->template('your_module')->fill(\%params);
          }

       It's uglier and more verbose, but it also prevents plugins from stepping on each other's
       toes.

       CGI::Application plugins that use CGI::Application::Plugin::AnyTemplate should default to
       using their own package name for the AnyTemplate config name:

          $self->template(__PACKAGE__)->config(...);
          $self->template(__PACKAGE__)->fill(...);

CHANGING THE NAME OF THE 'template' METHOD

       If you want to access the features of this module using a method other than "template",
       you can do so via Anno Siegel's Exporter::Renaming module (available on CPAN).

       For instance, to use syntax similar to CGI::Application::Plugin::TT:

           use Exporter::Renaming;
           use CGI::Application::Plugin::AnyTemplate Renaming => [ template => tt];

           sub cgiapp_init {
               my $self = shift;

               my %params = ( ... );

               # Set config file and other options
               $self->tt->config(
                   default_type => 'TemplateToolkit',
               );

           }

           sub my_runmode {
               my $self = shift;
               $self->tt->process('file', \%params);
           }

       And to use syntax similar to CGI::Application's "load_tmpl" mechanism:

           use Exporter::Renaming;
           use CGI::Application::Plugin::AnyTemplate Renaming => [ template => tmpl];

           sub cgiapp_init {
               my $self = shift;

               # Set config file and other options
               $self->tmpl->config(
                   default_type => 'HTMLTemplate',
               );

           }

           sub my_runmode {
               my $self = shift;

               my %params = ( ... );

               my $template = $self->tmpl->load('file');
               $template->param(\%params);
               $template->output;
           }

AUTHOR

       Michael Graham, "<mgraham@cpan.org>"

ACKNOWLEDGEMENTS

       I originally wrote this to be a subsystem in Richard Dice's CGI::Application-based
       framework, before I moved it into its own module.

       Various ideas taken from CGI::Application (Jesse Erlbaum), CGI::Application::Plugin::TT
       (Cees Hek) and "Text::Boilerplate" (Stephen Nelson).

       "Template::Toolkit" singleton support code stolen from CGI::Application::Plugin::TT.

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::Base
           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

           Exporter::Renaming

           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.