NAME

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

VERSION

Version 0.08

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, 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_path => '.',
    );

    $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,
    );

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

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

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',
        },
        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::TemplateToolkit
CGI::Application::Plugin::AnyTemplate::Driver::Petal

Copying Query data into Templates

By default, all data in $self->query are copied into the template object before the template is processed.

For the HTMLTemplate and HTMLTemplateExpr 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 disable this feature, pass a false value to associate_query or emulate_associate_query (depending on the template system):

    $self->template->config(
        default_type => 'HTMLTemplate',
        HTMLTemplate => {
            associate_query => 0,
        },
        HTMLTemplateExpr => {
            associate_query => 0,
        },
        TemplateToolkit => {
            emulate_associate_query => 0,
        },
        Petal => {
            emulate_associate_query => 0,
        },
    );

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.

If you call load with one paramter, 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 paramters directly:

    my $template = $self->template->load(
        file                        => 'some_file.tmpl',
        type                        => 'HTMLTemplate',
        auto_add_template_extension => 0,
        add_inlcude_path            => '..',
        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 paramters 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);

process

"process" is an alias for "fill".

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

PRE- AND POST- PROCESS

Before the template output is generated, your application's $self->template_pre_process method is called. This method is passed a reference to the $template object.

It can modify the parameters passed into the template by using the param method:

    sub template_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, your application's $self->template_post_process method is called. This method is passed a reference to the template object and a reference to the output generated by the template. You can modify this output:

    sub template_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.

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

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

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>

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, <mag-perl@occamstoothbrush.com>

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.

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install CGI::Application::Plugin::AnyTemplate, copy and paste the appropriate command in to your terminal.

cpanm

cpanm CGI::Application::Plugin::AnyTemplate

CPAN shell

perl -MCPAN -e shell
install CGI::Application::Plugin::AnyTemplate

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

Template-Independence

Embedded Components

Multiple Named Template Configurations

Flexible Syntax

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

CGI::Application load_tmpl style syntax

Verbose syntax (for complete control)

METHODS

config

Plugin Configuration

Driver and Native Configuration

Copying Query data into Templates

load

fill

process

DRIVER METHODS

PRE- AND POST- PROCESS

EMBEDDED COMPONENTS

Introduction

Syntax

Getting Template Variables from the Containing Template

Passing Parameters

CHANGING THE NAME OF THE 'template' METHOD

AUTHOR

ACKNOWLEDGEMENTS

BUGS

SEE ALSO

COPYRIGHT & LICENSE

Module Install Instructions