view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/AnyTemplate.pm  view on Meta::CPAN

        'name2' => 'value2'
    );

It is designed to behave similarly to the C<param> method in other modules like
L<CGI> and L<HTML::Template>.

=head2 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'

=head2 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 C<return_references> option is set to true, then the return value
of C<output> will be a reference to a string.  If the
C<return_references> option is false, then a copy of the string will be
returned.  By default C<return_references> is true.

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

=head1 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
C<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 C<CGI::Application>.

=head2 The load_tmpl hook

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

The C<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 C<load_tmpl> callback with:

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

When the C<load_tmpl> callback is executed it will be passed three
arguments (I<adapted from the> L<CGI::Application> I<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 C<$ht_params>, all but 'path' are
ignored, because these are specific to C<HTML::Template>.  If you want to
write a generic callback that needs to be able to access or modify
C<HTML::Template> parameters then let me know, or add a feature request
on L<http://rt.cpan.org>.

The C<path> param of C<$ht_params> is initially set to the value of
C<add_include_paths> (if set).  Your callback can modify the C<path>
param, and C<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 L<CGI::Application>'s built-in
C<load_tmpl>.

=head2 The template_pre_process and template_post_process hooks

Before the template output is generated, the C<< template_pre_process >>
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> callback as follows:

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

Pre-process callbacks will be passed a reference to the C<$template>
object, and can can modify the parameters passed into the template by
using the C<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 C<template_post_process> hook is called.
You can register a C<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/;
    }



=head1 EMBEDDED COMPONENTS

=head2 Introduction

C<CGI::Application::Plugin::AnyTemplate> allows you to include application
components within your templates.

For instance, you might include a I<header> component a the top of every
page and a I<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.

=head2 Syntax

L<HTML::Template> syntax:

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

L<HTML::Template::Expr> syntax:

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

L<HTML::Template::Pluggable> syntax:

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

L<Template::Toolkit|Template> syntax:

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

L<Petal> syntax:

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

=head2 Getting Template Variables from the Containing Template