Template::Filters
Author: Andy Wardley

TT2 Home Page

- Modules
- Template::*
- Filters.pm

Click to view the menu. It's very nice. Click to hide the menu and go all widescreen!
Back

#### Template::Exception

Exception handling class module Up

#### Template::* Modules

Next

#### Template::Grammar

Parser state/rule tables for the TT grammar

# Template::Filters

## Post-processing filters for template blocks

# Contents

Top

# SYNOPSIS

Top

    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

Top

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

Top

## new(\%params)

Top

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)

Top

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

Top

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

Top

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

Top

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

Top

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

Top

The TOLERANT flag can be set to indicate that the `Template::Filters` module should ignore any errors and instead return `STATUS_DECLINED`.

## DEBUG

Top

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

Top

Please see Template::Manual::Filters for a list of the filters provided with the Template Toolkit, complete with examples of use.

# AUTHOR

Top

Andy Wardley <abw@wardley.org> http://wardley.org/

# COPYRIGHT

Top

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

Top

Template::Manual::Filters, Template, Template::Context

http://template-toolkit.org/docs/modules/Template/Filters.html