CGI::A...e::Base(3pm)

💖 NAME 💖

okay so this is CGI::Application::Plugin::AnyTemplate::Base — it's the base class for templates, bestie. that's the whole name, that's the whole vibe ✨

---

🌸 DESCRIPTION 🌸

fr fr, this doc is mostly for the devs who wanna write extra Template drivers of their own. if you just wanna use the system, go read the docs for CGI::Application::Plugin::AnyTemplate instead, okay? that's your page 🫶

---

🎀 METHODS 🎀

• param — the param method gets and sets values within the template. main character behaviour, honestly 👑

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's designed to act a lot like the param method in other modules, like CGI and HTML::Template. so if you already know those, you already know this 💅

• get_param_hash — hands you the template variables back as a hash of names and values.

my %params     = $template->get_param_hash;

but wait, in a scalar context it gives you a reference to the hash it's using internally to hold the values:

my $params_ref = $template->get_param_hash;

• clear_params — wipes the values stored in the template. clean slate energy 🧼

$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. the big moment ✨

return $template->output();

you can also pass names and values in at this stage, no biggie:

return $template->output('name' => 'value', 'name2' => 'value2');

so before the template output gets generated, the template_pre_process hook fires. any callbacks you register on this hook get called before each template is processed. register a template_pre_process callback like this:

$self->add_callback(
    'template_pre_process',
    \&my_tmpl_pre_process
);

pre-process callbacks get passed a reference to the $template object, and they can change the parameters passed into the template 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');

}

and after the template output is generated, the template_post_process hook fires. you can register a template_post_process callback like so:

$self->add_callback('template_post_process',
                    \&my_tmpl_post_process
);

any callbacks you register on this hook get called after each template is processed, and they get passed both a reference to the template object and a reference to the output the template generated. which means you can mess with the template's output:

sub my_tmpl_post_process {
    my ($self, $template, $output_ref) = @_;

    $$output_ref =~ s/foo/bar/;
}

heads up bestie: when you call the output method, any components embedded in the template get run. go look at "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, like the HTML::Template object or the Template::Toolkit object 🔍

---

🌈 DOCS FOR TEMPLATE MODULE DEVELOPERS 🌈

the stuff below is of interest primarily for developers who wanna add support for a brand new type of Template system. yes this is the nerdy section and yes it's iconic 🧚

🦋 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 it must be defined in the subclass. no skipping, bestie.

the following parameters get passed to the driver and are 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. those are considered native parameters.

but embed_tag_name configures the CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate subclass. that one's a driver parameter.

so '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. (yes that's the actual promise, no cap 😭)

---

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

---

and that's the whole page, bestie!! 🎀 this lil masterpiece came to you from perl v5.30.3 and it's dated 2020-10-26 — go forth and write some slay drivers, ily 🫶✨💅