The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Template-Pure-0.033
River stage zero No dependents
3 ++
/ Template::Pure::Filters

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

Template::Pure.

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.