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 <, " to ", 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').