4.29. filter

4.29.1. Summary

Parameters: op

Positional parameters in same order.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [filter] FOO [/filter]. Nesting: NO

Invalidates cache: no

Called Routine:

ASP-like Perl call:

    $Tag->filter(
        {
         op => VALUE,
        },
        BODY
    )

 OR

    $Tag->filter($op, $BODY);
    [filter op]
Parameters Description Default
op   DEFAULT_VALUE
Attributes Default
interpolate No
reparse Yes
Other_Characteristics  
Invalidates cache no
Container tag Yes
Has Subtags No
Nests No

Tag expansion example:

    [filter lc]UPPER CASE YOU WANT TO SEE AS LOWER CASE[/filter]

    Produces:

                upper case you want to see as lower case

ASP-like Perl call:

   $Tag->filter(  { op => VALUE_op
}, $body  );

or similarly with positional parameters,

    $Tag->filter(op, $attribute_hash_reference, $body);

4.29.2. Description

Applies any of Interchange's standard filters to an arbitrary value, or you may define your own. The filters are also available as parameters to the cgi, data, and value tags.

Filters can be applied in sequence and as many as needed can be applied.

Here is an example. If you store your author or artist names in the database "LAST, First" so that they sort properly, you still might want to display them normally as "First Last". This call

    [filter op="name namecase"]WOOD, Grant[/filter]

will display as

    Grant Wood

Another way to do this would be:

    [data table=products column=artist key=99-102 filter="name namecase"]

Filters available include:

4.29.2.1. Length filter

If you pass just a numeric argument, filter will return only first N characters. For example:

[filter 5]Interchange[/filter]

results in:

"Inter"

By appending a ".", you can direct Interchange to append an ellipsis:

[filter 5.]Interchange[/filter]

results in:

"Inter..."

                if (/^(\d+)(\.?)$/) {
                        substr($value, $1) = $2 ? '...' : ''
                                if length($value) > $1;
                        next;
                }

4.29.2.2. cgi

Returns the value of the CGI variable. Useful for starting a filter sequence with a seed value.

    'cgi' =>    sub {
                    return $CGI::values(shift);
                },

4.29.2.3. digits

Returns only digits.

    'digits' => sub {
                    my $val = shift;
                    $val =~ s/\D+//g;
                    return $val;
                },

4.29.2.4. digits_dot

Returns only digits and periods, i.e. [.0-9]. Useful for decommifying numbers.

    'digits_dot' => sub {
                    my $val = shift;
                    $val =~ s/[^\d.]+//g;
                    return $val;
                },

4.29.2.5. dos

Turns linefeeds into carriage-return / linefeed pairs.

    'dos' =>    sub {
                    my $val = shift;
                    $val =~ s/\r?\n/\r\n/g;
                    return $val;
                },

4.29.2.6. entities

Changes < to &lt;, " to &quot;, etc.

    'entities' => sub {
                    return HTML::Entities::encode(shift);
                },

4.29.2.7. gate

Performs a security screening by testing to make sure a corresponding scratch variable has been set.

    'gate' =>   sub {
                    my ($val, $var) = @_;
                    return '' unless $::Scratch->{$var};
                    return $val;
                },

4.29.2.8. lc

Lowercases the text.

    'lc' =>     sub {
                    return lc(shift);
                },

4.29.2.9. lookup

Looks up an item in a database based on the passed table and column. Call would be:

    [filter op="uc lookup.country.name"]US[/filter]

This would be the equivalent of [data table=country column=name key=US].

    'lookup' => sub {
                        my ($val, $tag, $table, $column) = @_;
                        return tag_data($table, $column, $val) || $val;
                },

4.29.2.10. mac

Changes newlines to carriage returns.

    'mac' =>    sub {
                    my $val = shift;
                    $val =~ s/\r?\n|\r\n?/\r/g;
                    return $val;
                },

4.29.2.11. name

Transposes a LAST, First name pair.

    'name' => sub {
                    my $val = shift;
                    return $val unless $val =~ /,/;
                    my($last, $first) = split /\s*,\s*/, $val, 2;
                    return "$first $last";
                },

4.29.2.12. namecase

Namecases the text. Only works on values that are uppercase in the first letter, i.e. [filter op=namecase]LEONARDO da Vinci[/filter] will return "Leonardo da Vinci".

    'namecase' => sub {
                    my $val = shift;
                    $val =~ s/([A-Z]\w+)/\L\u$1/g;
                    return $val;
                },

4.29.2.13. no_white

Strips all whitespace.

    'no_white' =>   sub {
                    my $val = shift;
                    $val =~ s/\s+//g;
                    return $val;
                },

4.29.2.14. pagefile

Strips leading slashes and dots.

    'pagefile' => sub {
                    $_[0] =~ s:^[./]+::;
                    return $_[0];
                },

4.29.2.15. sql

Change single-quote characters into doubled versions, i.e. ' becomes ''.

    'sql'       => sub {
                    my $val = shift;
                    $val =~ s:':'':g; # '
                    return $val;
                },

4.29.2.16. strip

Strips leading and trailing whitespace.

    'strip' =>  sub {
                    my $val = shift;
                    $val =~ s/^\s+//;
                    $val =~ s/\s+$//;
                    return $val;
                },

4.29.2.17. text2html

Rudimentary HTMLizing of text.

    'text2html' => sub {
                    my $val = shift;
                    $val =~ s|\r?\n\r?\n|<P>|;
                    $val =~ s|\r?\n|<BR>|;
                    return $val;
                },

4.29.2.18. uc

Uppercases the text.

    'uc' =>     sub {
                    return uc(shift);
                },

4.29.2.19. unix

Removes those crufty carriage returns.

    'unix' =>   sub {
                    my $val = shift;
                    $val =~ s/\r?\n/\n/g;
                    return $val;
                },

4.29.2.20. urlencode

Changes non-word characters (except colon) to %3c notation.

    'urlencode' => sub {
                    my $val = shift;
                    $val =~ s|[^\w:]|sprintf "%%%02x", ord $1|eg;
                    return $val;
                },

4.29.2.21. value

Returns the value of the user session variable. Useful for starting a filter sequence with a seed value.

    'value' =>  sub {
                    return $::Values->(shift);
                },

4.29.2.22. word

Only returns word characters. Locale does apply if collation is properly set.

    'word' =>   sub {
                    my $val = shift;
                    $val =~ s/\W+//g;
                    return $val;
                },

You can define your own filters in a GlobalSub (or Sub or ActionMap):

    package Vend::Interpolate;

    $Filter{reverse} = sub { $val = shift; return scalar reverse $val  };

That filter will reverse the characters sent.

The arguments sent to the subroutine are the value to be filtered, any associated variable or tag name, and any arguments appended to the filter name with periods as the separator.

A [filter op=lookup.products.price]99-102[/filter] will send ('99-102', undef, 'products', 'price') as the parameters. Assuming the value of the user variable foo is bar, the call [value name=foo filter="lookup.products.price.extra"] will send ('bar', 'foo', 'products', 'price', 'extra').

4.29.2.23. op