NAME¶
Template::Filters - Post-processing filters for template blocks
SYNOPSIS¶
use Template::Filters;
$filters = Template::Filters->new(\%config);
($filter, $error) = $filters->fetch($name, \@args, $context);
if ($filter) {
print &$filter("some text");
}
else {
print "Could not fetch $name filter: $error\n";
}
DESCRIPTION¶
The "Template::Filters" module implements a provider for creating
subroutines that implement the standard filters. Additional custom filters may
be provided via the FILTERS configuration option.
METHODS¶
new(\%params)¶
Constructor method which instantiates and returns a reference to a
"Template::Filters" object. A reference to a hash array of
configuration items may be passed as a parameter. These are described below.
my $filters = Template::Filters->new({
FILTERS => { ... },
});
my $template = Template->new({
LOAD_FILTERS => [ $filters ],
});
A default "Template::Filters" module is created by the Template module
if the LOAD_FILTERS option isn't specified. All configuration parameters are
forwarded to the constructor.
$template = Template->new({
FILTERS => { ... },
});
fetch($name, \@args, $context)¶
Called to request that a filter of a given name be provided. The name of the
filter should be specified as the first parameter. This should be one of the
standard filters or one specified in the FILTERS configuration hash. The
second argument should be a reference to an array containing configuration
parameters for the filter. This may be specified as 0, or undef where no
parameters are provided. The third argument should be a reference to the
current Template::Context object.
The method returns a reference to a filter sub-routine on success. It may also
return "(undef, STATUS_DECLINE)" to decline the request, to allow
delegation onto other filter providers in the LOAD_FILTERS chain of
responsibility. On error, "($error, STATUS_ERROR)" is returned where
$error is an error message or Template::Exception object indicating the error
that occurred.
When the "TOLERANT" option is set, errors are automatically downgraded
to a "STATUS_DECLINE" response.
use_html_entities()¶
This class method can be called to configure the "html_entity" filter
to use the HTML::Entities module. An error will be raised if it is not
installed on your system.
use Template::Filters;
Template::Filters->use_html_entities();
use_apache_util()¶
This class method can be called to configure the "html_entity" filter
to use the Apache::Util module. An error will be raised if it is not installed
on your system.
use Template::Filters;
Template::Filters->use_apache_util();
CONFIGURATION OPTIONS¶
The following list summarises the configuration options that can be provided to
the "Template::Filters"
new() constructor. Please see
Template::Manual::Config for further information about each option.
FILTERS¶
The FILTERS option can be used to specify custom filters which can then be used
with the FILTER directive like any other. These are added to the standard
filters which are available by default.
$filters = Template::Filters->new({
FILTERS => {
'sfilt1' => \&static_filter,
'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
},
});
TOLERANT¶
The TOLERANT flag can be set to indicate that the "Template::Filters"
module should ignore any errors and instead return
"STATUS_DECLINED".
DEBUG¶
The DEBUG option can be used to enable debugging messages for the
Template::Filters module by setting it to include the
"DEBUG_FILTERS" value.
use Template::Constants qw( :debug );
my $template = Template->new({
DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
});
STANDARD FILTERS¶
Please see Template::Manual::Filters for a list of the filters provided with the
Template Toolkit, complete with examples of use.
AUTHOR¶
Andy Wardley <abw@wardley.org> <
http://wardley.org/>
COPYRIGHT¶
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
SEE ALSO¶
Template::Manual::Filters, Template, Template::Context