view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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