File Coverage

blib/lib/CGI/Application/Plugin/AnyTemplate.pm

Criterion	Covered	Total	%
statement	171	174	98.2
branch	62	70	88.5
condition	24	32	75.0
subroutine	22	22	100.0
pod	5	6	83.3
total	284	304	93.4

package CGI::Application::Plugin::AnyTemplate;

=head1 NAME

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

=head1 VERSION

Version 0.18

=cut

our $VERSION = '0.18';

=head1 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);
    }

=head1 DESCRIPTION

=head2 Template-Independence

C allows you to use any
supported Perl templating system using a single consistent interface.

Currently supported templating systems include L,
L, L,
L and L.

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.

=head2 Embedded Components

In addition to template abstraction, C also provides a
I.  For instance, you might include a
I component at the top of every page and a I component
at the bottom of every page.

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

=head2 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);

    }

=head2 Flexible Syntax

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

=head3 CGI::Application::Plugin::TT style syntax

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

or (with slightly less typing):

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

=head3 CGI::Application load_tmpl style syntax

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

=head3 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 L<"CHANGING THE NAME OF THE 'template' METHOD">.

=cut

use strict;
use CGI::Application;
use Carp;
use Scalar::Util qw(weaken);

if ( ! eval { require Clone } ) {
    if ( eval { require Clone::PP } ) {
        no strict 'refs';
        *Clone::clone = *Clone::PP::clone;
    }
    else {
        die "Neiter Clone nor Clone::PP found - $@\n";
    }
}

use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $CAPAT_Namespace);

@ISA = ('Exporter');

@ISA         = 'Exporter';
@EXPORT      = qw(template);
@EXPORT_OK   = qw(load_tmpl);
%EXPORT_TAGS = (load_tmpl => ['load_tmpl', @EXPORT]);

$CAPAT_Namespace = '__ANY_TEMPLATE';

if (CGI::Application->can('new_hook')) {
    CGI::Application->new_hook('template_pre_process');
    CGI::Application->new_hook('template_post_process');
    CGI::Application->new_hook('load_tmpl');
}

sub _new {
    my $proto     = shift;
    my $class     = ref $proto || $proto;
    my $webapp    = shift;
    my $conf_name = shift;

    my $self = {
        'conf_name'      => $conf_name,
        'base_config'    => {},
        'current_config' => {},
        'webapp'         => $webapp,
    };

    bless $self, $class;

    weaken $self->{'webapp'};

    return $self;
}

sub _default_type      { 'HTMLTemplate' }
sub _default_extension { '.html'        }

=head1 METHODS

=head2 config

Initialize the C 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 C