#============================================================= -*-Perl-*-
#
# Template::Plugin
#
# DESCRIPTION
#
# Module defining a base class for a plugin object which can be loaded
# and instantiated via the USE directive.
#
# AUTHOR
# Andy Wardley
#
# COPYRIGHT
# Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it an/or
# modify it under the same terms as Perl itself.
#
#============================================================================
package Template::Plugin;
use strict;
use warnings;
use base 'Template::Base';
our $VERSION = '3.106';
our $DEBUG = 0 unless defined $DEBUG;
our $ERROR = '';
our $AUTOLOAD;
#========================================================================
# ----- CLASS METHODS -----
#========================================================================
#------------------------------------------------------------------------
# load()
#
# Class method called when the plugin module is first loaded. It
# returns the name of a class (by default, its own class) or a prototype
# object which will be used to instantiate new objects. The new()
# method is then called against the class name (class method) or
# prototype object (object method) to create a new instances of the
# object.
#------------------------------------------------------------------------
sub load {
return $_[0];
}
#------------------------------------------------------------------------
# new($context, $delegate, @params)
#
# Object constructor which is called by the Template::Context to
# instantiate a new Plugin object. This base class constructor is
# used as a general mechanism to load and delegate to other Perl
# modules. The context is passed as the first parameter, followed by
# a reference to a delegate object or the name of the module which
# should be loaded and instantiated. Any additional parameters passed
# to the USE directive are forwarded to the new() constructor.
#
# A plugin object is returned which has an AUTOLOAD method to delegate
# requests to the underlying object.
#------------------------------------------------------------------------
sub new {
my $class = shift;
bless {
}, $class;
}
#------------------------------------------------------------------------
# fail($error)
#
# Version 1 error reporting function, now replaced by error() inherited
# from Template::Base. Raises a "deprecated function" warning and then
# calls error().
#------------------------------------------------------------------------
sub fail {
my $class = shift;
my ($pkg, $file, $line) = caller();
warn "Template::Plugin::fail() is deprecated at $file line $line. Please use error()\n";
$class->error(@_);
}
1;
__END__
=head1 NAME
Template::Plugin - Base class for Template Toolkit plugins
=head1 SYNOPSIS
package MyOrg::Template::Plugin::MyPlugin;
use base qw( Template::Plugin );
use Template::Plugin;
use MyModule;
sub new {
my $class = shift;
my $context = shift;
bless {
...
}, $class;
}
=head1 DESCRIPTION
A "plugin" for the Template Toolkit is simply a Perl module which
exists in a known package location (e.g. C) and
conforms to a regular standard, allowing it to be loaded and used
automatically.
The C module defines a base class from which other
plugin modules can be derived. A plugin does not have to be derived
from Template::Plugin but should at least conform to its object-oriented
interface.
It is recommended that you create plugins in your own package namespace
to avoid conflict with toolkit plugins. e.g.
package MyOrg::Template::Plugin::FooBar;
Use the L option to specify
the namespace that you use. e.g.
use Template;
my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugin',
});
=head1 METHODS
The following methods form the basic interface between the Template
Toolkit and plugin modules.
=head2 load($context)
This method is called by the Template Toolkit when the plugin module
is first loaded. It is called as a package method and thus implicitly
receives the package name as the first parameter. A reference to the
L object loading the plugin is also passed. The
default behaviour for the C method is to simply return the class
name. The calling context then uses this class name to call the C
package method.
package MyPlugin;
sub load { # called as MyPlugin->load($context)
my ($class, $context) = @_;
return $class; # returns 'MyPlugin'
}
=head2 new($context, @params)
This method is called to instantiate a new plugin object for the C