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
85   use_rfc2732()
86       This class method can be called to configure the "uri" and "url"
87       filters to use the older RFC2732 standard for matching unsafe
88       characters.
89
90   use_rfc3986()
91       This class method can be called to configure the "uri" and "url"
92       filters to use the newer RFC3986 standard for matching unsafe
93       characters.
94

CONFIGURATION OPTIONS

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

STANDARD FILTERS

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

AUTHOR

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

COPYRIGHT

135       Copyright (C) 1996-2020 Andy Wardley.  All Rights Reserved.
136
137       This module is free software; you can redistribute it and/or modify it
138       under the same terms as Perl itself.
139