Template::Filters(3)           User Contributed Perl Documentation           Template::Filters(3)



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 imple-
       ment the standard filters. Additional custom filters may be provided via the FILTERS con-
       figuration 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 refer-
       ence to an array containing configuration parameters for the filter.  This may be speci-
       fied as 0, or undef where no parameters are provided.  The third argument should be a ref-
       erence 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 "STA-
       TUS_DECLINE" response.

CONFIGURATION OPTIONS
       The following list summarises the configuration options that can be provided to the "Tem-
       plate::Filters" new() constructor. Please see Template::Manual::Config for further infor-
       mation 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 avail-
       able 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 <> <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



perl v5.8.8                                 2008-08-06                       Template::Filters(3)