NAME
Template::Pure::Filters - Default Data Filters
SYNOPSIS
my $html = qq[
<html>
<head>
<title>Page Title</title>
</head>
<body>
</body>
</html>
];
my $pure = Template::Pure->new(
template=>$html,
directives=> [
'body' => 'content | repeat(3) | escape_html',
]
);
my $data = +{
content => q[
<p>Are you <b>doomed</b> to discover that you never recovered from the narcoleptic
country in which you once <u>stood?</u> Where the fire's always burning, but
there's <i>never enough wood</i></p>?
],
};
print $pure->render($data);Returns:
<html>
<head>
<title>Page Title</title>
</head>
<body>
<p>Are you <b>doomed</b> to discover that you never recovered from the narcoleptic
country in which you once <u>stood?</u> Where the fire's always burning, but
there's <i>never enough wood</i></p>
<p>Are you <b>doomed</b> to discover that you never recovered from the narcoleptic
country in which you once <u>stood?</u> Where the fire's always burning, but
there's <i>never enough wood</i></p>
<p>Are you <b>doomed</b> to discover that you never recovered from the narcoleptic
country in which you once <u>stood?</u> Where the fire's always burning, but
there's <i>never enough wood</i></p>
</body>
</html>(Note that the embedded HTML was not HTML encoded due to the use of the 'escape_html' filter.)
DESCRIPTION
Container modules for all the filters that are bundled with Template::Pure. Please see "Filtering your data" in Template::Pure for usage. A lot of this is copied from Template::Filters and other filters from template languages like Xslate.
Filters are arrange in 'UNIX pipe' syntax, so the output of the first filter becomes the input of the second and so forth. It also means filter are order sensitive. Some filters like the 'escape_html' filter only make sense if they are the last in the pipe.
Some filters may take arguments, for example:
directives=> [
'body' => 'content | repeat(3)',
]Generally these are literals which are parsed out via regular expressions and then we use eval to generate Perl values. As a result you are strongly encouraged to properly untaint and secure these arguments (for example don't pass them in from a HTML form POST...).
You may pass arguments to filters via the data context using placeholder notation. Placeholder notation may be freely mixed in with argument literals.
directives=> [
'body' => 'content | repeat(#{times_to_repeat})',
]Filters may be added to your current Template::Pure instance:
my $pure = Template::Pure->new(
filters => {
my_custom_filter => sub {
my ($template_pure, $data, @args) = @_;
return $modified_data;
},
}, ... );Custom filters get the current Template::Pure instance, the current data context and any arguments; you are expected to return modified data.
FILTERS
This module defines the following subroutines that are used as filters for Template::Pure:
format ($format)
The format filter takes a format string as a parameter (as per sprintf()) and formats the data accordingly.
my $pure = Template::Pure->new(
template => '<p>Price: $<span>1.00</span></p>'
directives => [
'span' => 'price | format(%.2f)',
],
);
print $pure->render({
price => '2.0000001'
});Output:
<p>Price: $<span>2.00</span></p>strftime ($format)
Given an object that does 'strftime' return a string formatted date / time;
my $pure = Template::Pure->new(
template => '<p>Year</p>'
directives => [
'p' => 'date | strftime(%Y)',
],
);
print $pure->render({
date => DateTime->new(year=>2016, month=>12),
});Output:
<p>2016</p>dump
This filter doesn't actually change the data. It just uses Data::Dumper and sends Dumper output to STDOUT via warn. Can be useful during debugging when you can't figure out what is amiss with your data. After it dumps to STDOUT we just return the value unaltered.
uri_escape
uri_escape_utf8
These filters are just wrappers around the same in URI::Escape.
upper
lower
upper_first
lower_first
Does text case conversions using Perl built in functions uc, lc, ucfirst and lcfirst.
collapse
Collapse any whitespace sequences in the input text into a single space. Leading and trailing whitespace (which would be reduced to a single space) is removed, as per trim.
encoded_string
By default Template::Pure escapes your values using a simple HTML escape function so that your output is 'safe' from HTML injection attacks. However there might be cases when you wish to all raw HTML to be injected into your template, froom known, safe data. In this case you can use this function to mark your data as "don't encode". We will assume you know what you are doing...
escape_html
As mentioned in the previous filter documentation, we nearly always automatically escape your data values when they get rendered into your template to produce a document. However as also mentioned there are a few case where we don't, since we think its the more common desired behavior, such as when you are injecting a template object or you are setting the value from the contents of a different node inside the same template. In those cases, should HTML escaping be desired you can use this filter to make it so.
truncate ($length, $affix)
Truncates string data to $length (where $length is the total allowed number of characters). In the case when we need to truncate, add $affix to the end to indicate truncation. For example you may set $affix to '...' to indicate characters were removed. There is no default $affix.
NOTE Should you use an $affix we automatically increase the required truncation so that the new string INCLUDING THE $affix fits into the required $length.
repeat ($times)
Repeat a value by $times.
remove ($match)
Searches the input text for any occurrences of the specified string and removes them. A Perl regular expression may be specified as the search string.
replace ($match, $replacement)
Like "remove" but does a global search and replace instead of removing. Can also use a regular expression in the $match
default ($value)
Should $data be undefined, use $value instead.
rtrim
ltrim
trim
Removes all whitespace from either the right side, left side, or both sides of the data
comma
Given a data value which is a number, comma-fy it for readability (100000 = > 100,000).
cond
A filter that is like the conditional operator (?). Takes two arguments and returns the first one if the filtered value is true and the second one otherwise.
my $pure = Template::Pure->new(
template=>q[
<input name='toggle' type='checkbox'>
],
directives=> [
'input[name="toggle"]@checked' => 'checkbox_is_set |cond("on", undef)',
],
);SEE ALSO
AUTHOR
John Napiorkowski L<email:jjnapiork@cpan.org>But lots of this code was copied from Template::Filters and other prior art on CPAN. Thanks!
COPYRIGHT & LICENSE
Please see Template::Pure for copyright and license information.