Chunk Tag Filters

From Chunk Java Template Engine

Jump to: navigation, search

Chunk includes several useful filters right out of the box, eg {$tag|upper}.

Filters may be chained ad infinitum: {$tag|md5hex|upper}.


[edit] alternate(<evenoutput>,<oddoutput>)

When tag value is even, output <evenoutput> - when odd, output <oddoutput>. Unbraced tags are valid arguments, eg:

output the strings "even" and "odd":

{% $i|alternate(even,odd) %}

output {$even} and {$odd} tags:

{% $i|alternate($even,$odd) %}

include templates {#even} and {#odd}

{% $i|alternate(+#even,+#odd) %}

Alias: evenodd

[edit] base64


[edit] base64decode


[edit] bool

Translates "truthy" values to "TRUE"/null for use in "if" expressions.

eg: {% if ($n|calc($x * $x > 20)|bool) %} ... {% endif %}

Input Output
null null
empty string:  "" null
whitespace-only string:  " " null
any defined, non-empty string:  "bananas" TRUE
"0" null
"1" TRUE
"2" TRUE
"-1" TRUE
"0.0" null
"1.0" TRUE
"21.0" TRUE
"-1.0" TRUE
"true" TRUE
"false" null
"True" TRUE
"False" null
"FALSE" null
non-null object TRUE
null object null
the string "null":  "null" TRUE

Alias: boolean

[edit] calc(<expr>[,<fmt>])

Requires jeplite - see GitHub project page for download instructions.

The calc filter is similar to the comp filter but provides much richer expression parsing and simple $tag references.

If $x appears in <expr> then the input value is substituted for $x, otherwise the input value is prepended to the expression.

The input may be filtered before passing to the calc filter, but direct $tag references in the expression may not use any filter/default modifiers.


{% $n:2|calc(+2) %}
output: 4.0

{% $n:2|calc("$x+$x") %}
output: 4.0

{% $n:0.5|calc("sin(pi*$x)","%.2f") %}
output: 1.00

{% $a|calc("(-$b + sqrt($b^2 - 4*$x*$c))/(2*$x)") %}
output: well, it depends on values of $a $b $c ...


  • Non-numeric input (including null/undefined) will pass through the filter with no processing and the expression will not be executed.
  • Behavior when referencing non-numeric tag values in expressions is undefined
  • Functions available: sin cos tan asin acos atan sqrt log ln angle abs mod sum rand umin add
  • Computational operators: * / + - ^ %
  • Comparison operators: > < >= <= == != <>
  • Grouping operators: ( )
  • Constants available: e and pi

Jeplite evaluates comparisons as 0.0 for false and 1.0 for true, so that output must be passed through the "bool" filter if you wish to use it in an "if" expression.

[edit] capitalize

Uppercase the first letter of each word. Leave case of other characters intact. See title.

Alias: cap

[edit] checked(<testvalue>[,<output>])

Output checked="checked" (or <output> if specified) when tag value matches <testvalue>. Argument may be an unbraced $tag.

[edit] comp(<operation>)

Perform a limited set of comparisons (> < >= <= <> == !=) or mathematical transformations (+, -, *, /, %, ^) on an integer (long) or floating-point (decimal) input. eg: {% $tag|qcalc(+20) %}.

The <operation> argument syntax is very strict: an operator symbol must come first, followed by a number. Compound expressions are not allowed, but the filter may be chained multiple times.

A decimal point in the input or argument will force conversion of both to a double float. Integer division is performed on integers, floating point division on floats.

Comparisons evaluate to null when false, or the string "TRUE" when true, which is expected by "if" expressions, eg:

{% if $n|comp(>30) %}...{% endif %}

NB: When using the comp filter for comparisons in a standalone tag, you must provide a default "FALSE" value to avoid triggering tag pass-through preservation:

{% $n|comp(>30):FALSE %} evaluates to TRUE or FALSE

{% $n|comp(>30) %} evaluates to TRUE or {% $n|comp(>30) %}

Aliases: qcalc, qc
Versions: 3.1.1+

[edit] defang

Remove all but a short list of "harmless" characters - can apply to values from untrusted sources to neuter potential XSS attacks.

Alias: neuter

[edit] default(<output>)

Output <output> if the $tag is not found in the tag table. If the tag is found, the tag value is _not_ consulted. Empty string, or a string that is completely whitespace will be output and will _not_ trigger the default output. v2.5 and up. See onempty.

[edit] escapequotes

Escape single and double quotes (and backslashes) with a backslash.

Aliases: qs, quoted, quotedstring

[edit] escapexml

Convert & to &amp; and handle angle brackets, single and double quotes, etc. See unescapexml.

Aliases: xml, html, xmlescape, htmlescape

[edit] filter(<#xtemplate>)

Bind the tag value to {$x} and include the specified template. Provides a way to write user-contributed filters using template tag language.

[edit] get(<index>)

Output the LIST element at <index>. Zero (0) is the first element and -1 is the last element. Negative indices count back from the end of the LIST.

[edit] indent(<howmany>[,indentstring])

Indent each line of the input by <howmany>. Default indentstring is a single space.

[edit] join[(<delimiter>)]

Join the LIST elements into a STRING, optionally delimited by <delimiter>. Null input results in null output (3.6.0+).

[edit] length

Outputs the size of a LIST or OBJECT, or the length of a STRING input.

Alias: len

[edit] lower

Convert text to lowercase. Honors Java locale settings.

Alias: lc

[edit] lpad[(<prefix>[,<howmany>])]

If tag is defined and non-empty, output with prefix (default prefix is a single space " ").

[edit] md5hex

MD5-hash (bytes encoded in two-character hex format)

Alias: md5

[edit] ondefined(<output>)

Output <output> when tag value is defined. White space or the empty string is not considered defined for this test.

[edit] onempty(<output>)

For undefined _or_ "empty" values (ie empty string or only whitespace), output the given <output>, otherwise let the tag value pass through. See default.

[edit] page(<pagenum>[,<pagesize>])

Convenience filter for slicing one "page" of a LIST. First page is pagenum=1, not pagenum=0. The pagenum argument may be a positive integer or a $tag that resolves to a positive integer.

Default page size is 10.

Versions: 3.1.3+

[edit] reverse

Reverse a LIST.

[edit] rpad[(<suffix>[,<howmany>])]

If tag is defined and non-empty, output with suffix (default suffix is a single space " ").

[edit] s/<regex>/<replace>/[flags]

Perl-style regular expression search and replace.

[edit] selected(<testvalue>[,<output>])

Output selected="selected" (or <output> if specified) when tag value matches <testvalue>. Argument may be an unbraced $tag.

Aliases: select, sel

[edit] sha1hex

SHA-1 hash (bytes encoded in two-character hex format).

Alias: sha1

[edit] slice([from][:to][:step])

Subset a LIST using python-style slice notation. Negative indices and steps are supported. Default values for <from> and <to> are the beginning and end of the list. If input is null, output will be null (3.6.0+). Works on strings too (treats string as list of characters). May separate args with comma instead of colon if desired.

[edit] sort

Sort a LIST of homogenous, comparable items.

[edit] split[(<delimiter>|/<regexdelim>/[,<limit>])]

Transform delimited STRING into a LIST, using a simple delimiter or a /regex/ delimiter. Default delimiter is whitespace. <limit> arg is also optional.

[edit] sprintf(<format>)

The classic formatter. See [sprintf examples].

[edit] string

The string representation of an object. Calls the object's .toString() method. Only useful in rare cases (eg when chaining filters) since this mirrors the default rendering behavior.

Alias: str

[edit] th

English ordinal suffix (1 -> 1st, 2 -> 2nd, 10 -> 10th etc.).

Alias: ordsuffix

[edit] title

Uppercase the first letter of each word, and lowercase all other characters. See capitalize. Does not follow any rules about not title-casing small words.

[edit] translate

See complete localization documentation to learn how to use this feature.

Aliases: xlate, _

[edit] trim

Trim leading and trailing whitespace.

[edit] type

Output STRING, LIST, OBJECT, CHUNK or NULL per the tag value type.

[edit] unescapexml

Unescape xml-escaped entities, including eg &#123; and &#x03BB; See escapexml.

Aliases: unescapehtml, unxml, unhtml, xmlunescape

[edit] upper

Convert text to uppercase. Honors Java locale settings.

Alias: uc

[edit] urldecode

Restore %AB encoded characters. Plus character (+) is translated back to space.

[edit] urlencode

URL-Encode the value.

Alias: url

Personal tools