This document lists and shows examples for each of the the built-in Template Filters that are already registered with Modulo template system.

Template Filters

add

Adds the argument to the value. Example:

<Template>
    {{ state.value|add:7 }} hacks <br />
    {{ state.value|add:state.another }} hz
</Template>

<State
    value:=1330
    another:=1270
></State>

allow

Given an "allowed list" of comma separated strings, only permit values that exist exactly the "allowed list". If the value does not exist within the allowed list, it will produce an empty string (""). The fact that empty strings are "falsy" means you can chain together this filter with the default filter in order to provide a fallback as well, which is demonstrated in the third example. Examples:

Note: You should not use this for input validation for security purposes (use the backend instead, since any frontend code can be altered by users) or input validation, for which you use should pattern= instead since it's built in to HTML.

<Template>
    Valid: {{ state.value|allow:"orange,apple,pear" }} <br />
    Invalid: {{ state.value|allow:"a,b,c" }} <br />
    Invalid + default: {{ state.value|allow:"a,b,c"|default:"Oops!" }}
</Template>

<State
    value="apple"
></State>

camelcase

Converts a kebab-case-style-string (like favored by HTML, or website URL slugs), among other formats, into a camelCase (like what's favored by JavaScript, others).

<Template>
    Original: {{ state.slug }} <br />
    Camel: {{ state.slug|camelcase }} <hr />
    Original: {{ state.filename }} <br />
    Camel: {{ state.filename|camelcase }}
</Template>
<State
    slug="no-more-sluggish-sites"
    filename="article-dir-index_2.html"
></State>

capfirst

Output given string with the first letter capitalized.

<Template>
    The {{ state.value|capfirst }} framework is my favorite
</Template>

<State
    value="modulo.js"
></State>

combine

Combine is for combining values, which results in a few different operations depending on type. For Arrays, it will combine them end-to-end. For Objects, it will attempt to "squash" them. See the following examples:

<Template>
    Arrays: {{ state.start|combine:state.end|json }}<br />
    Objects: {{ state.baseobj|combine:state.topobj|json }}
</Template>

<State
    start:='[1, 2, 3 ]'
    end:='[ "a", "b", "c" ]'
    baseobj:='{ "a": 1, "b": 2 }'
    topobj:='{ "b": 3, "c": 4 }'
></State>

default

If the given value is Falsy, use the given default. Otherwise, use the value.

<Template>
    Fave snack: {{ state.snack|default:"icecream" }} <br />
    Snack count: {{ state.count|default:"none" }} <br />
    Fave soda: {{ state.soda|default:"Cola" }}
</Template>
<State
    snack=""
    count:=0
    soda="guarana"
></State>

divisibleby

Returns true if the value is evenly divisible by the given argument.

<Template>
    Can {{ state.value }} divide by 3? <br />
    {{ state.value|divisibleby:3 }} <br />
    {% if state.value|divisibleby:2 %}
        {{ state.value }} is even
    {% endif %}
</Template>
<State
    value:=4
></State>

entries

Convert the entire Object an Array format. If you only want one part of it, see the related values and keys.

<Template>
    Entries: {{ state.obj|entries|json }}
</Template>

<State
    obj:='{
        "abc": 123,
        "def": 456
    }'
></State>

escapejs

Escape special characters in a given string using JavaScript (specifically, JSON) escaping rules. If you have a string like "Hello\nWorld!" (where \n is a single new-line character), it will output Hello\nWorld! (that is, as "backslash-n" or two characters). It will also "double-up" any backslashes it encounters.

Note that this is unrelated to the HTML autoescaping, meaning you may need to also mark as |safe if do not want it escaping for HTML rules as well (e.g. changing <, which is invalid for HTML text but valid for JavaScript, into <). Similarly, there is no need to use this for escaping for HTML attribute values (e.g. <input placeholder="{{ state.msg }}">), as the HTML escaping is sufficient. The only use is embedded JS strings.

<Template>
    Result: {{ state.value|escapejs }} <br />
</Template>

<State
    value="Just
trying
\stuff\
out"
></State>

first

Retrieve the first item in an Array:

<Template>
    <p>{{ state.athletes|first }}</p>
</Template>

<State
  athletes:='["Neymar", "Maradona"]'
></State>

join

Formats an array to be comma-separated. Optionally, a different separator can be specified as an argument.

<Template>
    <p>{{ state.athletes|join }}</p>
    <p>{{ state.athletes|join:" + " }}</p>
</Template>

<State
  athletes:='["Neymar", "Maradona"]'
></State>

json

Formats given data as a JSON string. It takes one optional argument, that if specified, will cause indentation by the given amount.

<Template>
    <pre>{{ state.athletes|json }}</pre>
    <pre>{{ state.athletes|json:2 }}</pre>
</Template>

<State
    athletes:='[
        {"name": "Devante Adams"},
        {"name": "Steph Curry"},
        {"name": "Megan Rapinoe"}
    ]'
></State>

<Style>
    :host {
        overflow: auto;
        display: block;
        height: 180px;
    }
</Style>

keys

Show only the keys of the given Object, converted into an Array format. See also the similar values and entries.

<Template>
    Keys: {{ state.obj|keys|json }}
</Template>

<State
    obj:='{
        "abc": 123,
        "def": 456
    }'
></State>

last

Retrieve the last item in an Array:

<Template>
    <p>{{ state.athletes|last }}</p>
</Template>

<State
  athletes:='["Neymar", "Maradona"]'
></State>

length

Determine the length of the given value. This supports Strings, Arrays, and Objects. For Objects, it will return the number of properties on the object.

<Template>
    <p>Sentence length: {{ state.sentence|length }}</p>
    <p>Flowers length: {{ state.flowers|length }}</p>
    <p>Flights length: {{ state.flights|length }}</p>
</Template>

<State
    sentence="The sweat wis lashing oafay Sick Boy; he wis trembling."
    flowers:='["Marigolds", "Sunflowers"]'
    flights:='{"SFO": "LAX", "BAI": "MEX", "MEX": "MVD"}'
></State>

lower

Display the given string in all lowercase letters.

<Template>
    <p>Without: {{ state.word }}</p>
    <p>Lower: {{ state.word|lower }}</p>
</Template>

<State
    word="rAndOm cAPitalS"
></State>

multiply

Performs the mathematical operation of "multiplication" of the given numbers.

<Template>
    {{ state.a }} x {{ state.b }} =
    {{ state.a|multiply:state.b }}
</Template>
<State
    a:=10
    b:=3
></State>

pluralize

Allows for convenient pluralization in many human languages. This is for words in languages where a plural form is used when there is "0" or "2+" items, and a singular form for exactly 1 item. This is useful for the majority of noun and verb conjugations in English, along with many other Indo-European languages.

To use, give it a number (typically, the length of a list), and a comma separated version of two forms of a word. If that number is exactly "1" it will output the second form (or nothing at all, if the second form is not specified), otherwise it will output the first form.

Below are some examples. Note that in the second example, it does not specify a singular form, but instead only specifies an "s" to append to the word "flower" to make it's plural "flowers".

<Template>
    We visited {{ state.citynames|length}} 
    {{ state.citynames|length|pluralize:"cities,city" }}

    and picked {{ state.flowers|length}} 
    flower{{ state.flowers|length|pluralize:"s" }}
</Template>

<State
    flowers:='["Marigolds", "Sunflowers"]'
    citynames:='["Oakland", "Berkeley", "Richmond", "Concord"]'
></State>

safe

By default, template variables automatically escape the output of every variable value. Specifically, >, <, ', ", and & are all turned into their "escaped" HTML equivalents, to prevent them from being interpreated as HTML tags.

|safe disables this feature. It "marks" the HTML as "safe" for inclusion, and thus allowed to be interpreted as HTML, and not just display the sourcecode to the user. Further reading on this topic is in the Templating section on "Escaping".

See below for example:

<Template>
    Escaped: {{ state.str }}<br />
    Marked safe: {{ state.str|safe }}
</Template>
<State
    str="Try to escape <em>this!</em>"
></State>

skipfirst

Does the opposite of "first" -- takes all except for the first element. It's useful for skipping over data you don't need to process.

You can skip more than one by specifying the optional argument. For example, with the syntax: |skipfirst:10, e.g. "skip the first 10".

<Template>
    {% for top in state.data|first %} <h5>{{ top }}</h5> {% endfor %}
    {% for row in state.data|skipfirst %}
        {% for cell in row %}
            <div>{{ cell }}</div>
        {% endfor %}
    {% endfor %}
</Template>

<State
    data:='[
        [ "Col 1", "Col 2", "Col 3" ],
        [ 1, 2, 3 ],
        [ 1, 2, 3 ],
        [ 1, 2, 3 ]
    ]'
></State>

<Style>
    :host {
        display: grid;
        grid-template-columns: 1fr 1fr 1fr;
    }
</Style>

subtract

Subtracts the argument from the value. Example:

<Template>
    {{ state.value|subtract:3 }} hacks <br />
    {{ state.value|subtract:state.another }} is the answer
</Template>

<State
    value:=1340
    another:=1298
></State>

truncate

Cut off the given string after a number of characters specified by the argument. If it has to cut off the string, it will append an "ellipsis" character.

<Template>
    <p>Long sentence: {{ state.sentence|truncate:20 }}</p>
    <p>Short word: {{ state.word|truncate:20 }}</p>
</Template>

<State
    sentence="The sweat wis lashing oafay Sick Boy; he wis trembling."
    word="Bird."
></State>

type

Attempts to figure out the JavaScript type of the given value, and returns the type, in all lowercase. Useful for acting differently when data, for example, is a Number, instead of a String.

<Template>
    {{ state.str|type }} <br />
    {{ state.num|type }} <br />
    {{ state.arr|type }} <br />
    {{ state.obj|type }} <br />
    {{ state.bool|type }} <br />
    {{ state.arr.reverse|type }} <br />
    {% if state.arr|type is "array" %}
        <hr /> It's an array!
    {% endif %}
</Template>

<State
    str="abc"
    num:=123
    arr:='[ 1, 2, 3 ]'
    obj:='{ "a": 3 }'
    bool:=false
></State>

renderas

A highly useful filter that allows use of re-usable template snippets.

Typically in the format of {{ state.data|renderas:trow }}, where state.data is some Object, and there exists a template like with the -name "trow" that renders that object. The typical usage of this is refactoring templates to conveniently render complex data. This allows you to take complicated bits of template code and refactor it into another smaller, helper, "child" template that is then used within the main template.

The "input" to renderas should always be an Object. The keys and values of that object will populate the "template variables" for that template, meaning you can access them directly as template variables within the child template. As an example, if we renderas with an Object like {altTitle: "Newest entry"}, then within the child template the "altTitle" becomes a "top-level" variable, and we can use syntax like {{ altTitle }} (no need for "." syntax).

Note that the child template will be isolated or "sandboxed" to only have access to properties of the specified object. State, props, script, etc will not be accessible as template variables. This sandboxing is usually good and helps reduce bugs and makes child templates much easier to read. However, sometimes you just want to quickly spit up and refactor a template, meaning you want the child template to behave just like the parent, and you want global variables available, just as they were available to the parent. To include another template without any sandboxing, consider using the include template-tag.

<Template -name="trow">
    <div><strong>{{ name }}</strong></div>
    <div><em>{{ type }}</em></div>
    <div><tt>{{ level }}</tt></div>
</Template>
<Template>
    <section>
        <h3>Name</h3> <h3>Type</h3> <h3>Level</h3>
        {% for info in state.pokemon %}
            {{ info|renderas:trow }}
        {% endfor %}
    </section>
</Template>
<State
    pokemon:='[
        {"name": "Jigglypuff", "type": "Normal", "level": 13},
        {"name": "Pikachu", "type": "Electric", "level": 10},
        {"name": "Ghastly", "type": "Ghost", "level": 8}
    ]'
></State>
<Style>
    section {
        display: grid;
        grid-template-columns: 2fr 2fr 1fr;
    }
</Style>

reversed

Reverses the given input. Typically, this is used to reverse Arrays, such as when you want to iterate over an Array in the opposite direction using a {% for %} template-tag. If the input is a String or another data type, it will attempt to first convert to an Array.

<Template>
    <p>{{ state.flowers|reversed|join }}</p>
    {% for city in state.cities|reversed %}
        <p>{{ city }}</p>
    {% endfor %}
</Template>

<State
    flowers:='["Marigolds", "Sunflowers"]'
    cities:='["Oakland", "Berkeley", "Richmond", "Concord"]'
></State>

upper

Display the given string in all uppercase letters.

<Template>
    <p>Without: {{ state.word }}</p>
    <p>Upper: {{ state.word|upper }}</p>
</Template>

<State
    word="rAndOm cAPitalS"
></State>

values

Show only the values of the given Object, converted into an Array format. See also the similar keys and entries.

<Template>
    Values: {{ state.obj|values|json }}
</Template>

<State
    obj:='{
        "abc": 123,
        "def": 456
    }'
></State>

yesno

The |yesno filter converts the data into a string. The |yesno filter is a handy shortcut with many practical uses when generating HTML and displaying values from the database.

By default, it will convert true and other true values into "yes", false and other false values, and the "placeholder" null type into a "" (blank), since that is often used to designate something that is not yet defined (such as a null value in a database).

When arguments are provided, these substitute these 3 options, as designated by commas.

If a single argument is provided, then both "no" and "null" options get combined into "", and only "truthy" values will cause the given argument to show. This is useful for optionally adding a class, and can end up being simpler than a full if statement. For example, you can quickly add an "active" class like: <div class="{{ state.visible|yesno:'active' }}">

With two arguments, the default behavior is replaced with the two alternaties. With 3 arguments, then a value is presented for the undefined third value as well.

<Template>
    <span></span> <h3>{{ state.a }}</h3>       <h3>{{ state.b }}</h3>       <h3>{{ state.c }}</h3>
    <span></span> <span>{{ state.a|yesno }}</span> <span>{{ state.b|yesno }}</span> <span>{{ state.c|yesno }}</span>
    <span>on</span> <span>{{ state.a|yesno:"on" }}</span> <span>{{ state.b|yesno:"on" }}</span> <span>{{ state.c|yesno:"on" }}</span>
    <span>on,off</span> <span>{{ state.a|yesno:"on,off" }}</span> <span>{{ state.b|yesno:"on,off" }}</span> <span>{{ state.c|yesno:"on,off" }}</span>
    <span>on,off,maybe</span> <span>{{ state.a|yesno:"on,off,maybe" }}</span> <span>{{ state.b|yesno:"on,off,maybe" }}</span> <span>{{ state.c|yesno:"on,off,maybe" }}</span>
</Template>
<State
    a:=true
    b:=false
    c:=null
></State>
<Style>
    :host {
        display: grid;
        grid-template-columns: 1fr 1fr 1fr 1fr;
        text-align: right;
    }
</Style>