Template::Filters(3pm)

1Template::Filters(3)  User Contributed Perl Documentation Template::Filters(3)
2
3
4

NAME

6       Template::Filters - Post-processing filters for template blocks
7

SYNOPSIS

9           use Template::Filters;
10
11           $filters = Template::Filters->new(\%config);
12
13           ($filter, $error) = $filters->fetch($name, \@args, $context);
14
15           if ($filter) {
16               print &$filter("some text");
17           }
18           else {
19               print "Could not fetch $name filter: $error\n";
20           }
21

DESCRIPTION

23       The "Template::Filters" module implements a provider for creating
24       subroutines that implement the standard filters. Additional custom
25       filters may be provided via the FILTERS configuration option.
26

METHODS

28   new(\%params)
29       Constructor method which instantiates and returns a reference to a
30       "Template::Filters" object.  A reference to a hash array of
31       configuration items may be passed as a parameter.  These are described
32       below.
33
34           my $filters = Template::Filters->new({
35               FILTERS => { ... },
36           });
37
38           my $template = Template->new({
39               LOAD_FILTERS => [ $filters ],
40           });
41
42       A default "Template::Filters" module is created by the Template module
43       if the LOAD_FILTERS option isn't specified.  All configuration
44       parameters are forwarded to the constructor.
45
46           $template = Template->new({
47               FILTERS => { ... },
48           });
49
50   fetch($name, \@args, $context)
51       Called to request that a filter of a given name be provided.  The name
52       of the filter should be specified as the first parameter.  This should
53       be one of the standard filters or one specified in the FILTERS
54       configuration hash.  The second argument should be a reference to an
55       array containing configuration parameters for the filter.  This may be
56       specified as 0, or undef where no parameters are provided.  The third
57       argument should be a reference to the current Template::Context object.
58
59       The method returns a reference to a filter sub-routine on success.  It
60       may also return "(undef, STATUS_DECLINE)" to decline the request, to
61       allow delegation onto other filter providers in the LOAD_FILTERS chain
62       of responsibility.  On error, "($error, STATUS_ERROR)" is returned
63       where $error is an error message or Template::Exception object
64       indicating the error that occurred.
65
66       When the "TOLERANT" option is set, errors are automatically downgraded
67       to a "STATUS_DECLINE" response.
68
69   use_html_entities()
70       This class method can be called to configure the "html_entity" filter
71       to use the HTML::Entities module. An error will be raised if it is not
72       installed on your system.
73
74           use Template::Filters;
75           Template::Filters->use_html_entities();
76
77   use_apache_util()
78       This class method can be called to configure the "html_entity" filter
79       to use the Apache::Util module. An error will be raised if it is not
80       installed on your system.
81
82           use Template::Filters;
83           Template::Filters->use_apache_util();
84

CONFIGURATION OPTIONS

86       The following list summarises the configuration options that can be
87       provided to the "Template::Filters" new() constructor. Please see
88       Template::Manual::Config for further information about each option.
89
90   FILTERS
91       The FILTERS option can be used to specify custom filters which can then
92       be used with the FILTER directive like any other. These are added to
93       the standard filters which are available by default.
94
95           $filters = Template::Filters->new({
96               FILTERS => {
97                   'sfilt1' =>   \&static_filter,
98                   'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
99               },
100           });
101
102   TOLERANT
103       The TOLERANT flag can be set to indicate that the "Template::Filters"
104       module should ignore any errors and instead return "STATUS_DECLINED".
105
106   DEBUG
107       The DEBUG option can be used to enable debugging messages for the
108       Template::Filters module by setting it to include the "DEBUG_FILTERS"
109       value.
110
111           use Template::Constants qw( :debug );
112
113           my $template = Template->new({
114               DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
115           });
116

STANDARD FILTERS

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

AUTHOR

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

COPYRIGHT

125       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
126
127       This module is free software; you can redistribute it and/or modify it
128       under the same terms as Perl itself.
129