# Template::Filters - phpMan

## 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();

  use_rfc2732()
    This class method can be called to configure the "uri" and "url" filters
    to use the older RFC2732 standard for matching unsafe characters.

  use_rfc3986()
    This class method can be called to configure the "uri" and "url" filters
    to use the newer RFC3986 standard for matching unsafe characters.

## 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-2014 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]