Filters

The rendering of variables can be modified by filters. Filters are special functions that are applied after any object token in a variable block using the pipe character, for example: {{ names|join(', ') }}.

Filters can also be chained together, one after another. In this case, we have a list of names in HTML tags that we want to remove, output together, and make title-cased:

// names = ['paul
', 'jim'];
{{ names|striptags|join(', ')|title }}
// => Paul, Jim

Swig comes pre-loaded with a set of useful filters:

addslashes

Source: lib/filters.js#L40

Backslash-escape characters that need to be escaped.

Returns

*: Backslash-escaped string.

Examples

{{ "\"quoted string\""|addslashes }}
// => \"quoted string\"

capitalize

Source: lib/filters.js#L59

Upper-case the first letter of the input and lower-case the rest.

Returns

*: Returns the same type as the input.

Examples

{{ "i like Burritos"|capitalize }}
// => I like burritos

date(format, offset, abbr)

Source: lib/filters.js#L86

Format a date or Date-compatible string.

Parameters

Name	Type	Optional	Default	Description
`format`	`string`		`undefined`	PHP-style date format compatible string. Escape characters with `\` for string literals.
`offset`	`number`	✔	`undefined`	Timezone offset from GMT in minutes.
`abbr`	`string`	✔	`undefined`	Timezone abbreviation. Used for output only.

Returns

string: Formatted date string.

Examples

// now = new Date();
{{ now|date('Y-m-d') }}
// => 2013-08-14

// now = new Date();
{{ now|date('jS \o\f F') }}
// => 4th of July

default(def)

Source: lib/filters.js#L126

If the input is `undefined`, `null`, or `false`, a default return value can be specified.

Parameters

Name	Type	Optional	Default	Description
`def`	`*`		`undefined`	Value to return if `input` is `undefined`, `null`, or `false`.

Returns

*: `input` or `def` value.

Examples

{{ null_value|default('Tacos') }}
// => Tacos

{{ "Burritos"|default("Tacos") }}
// => Burritos

escape(type)

Source: lib/filters.js#L145

Force escape the output of the variable. Optionally use `e` as a shortcut filter name. This filter will be applied by default if autoescape is turned on.

Parameters

Name	Type	Optional	Default	Description
`type`	`string`	✔	`'html'`	If you pass the string js in as the type, output will be escaped so that it is safe for JavaScript execution.

Returns

string: Escaped string.

Examples

{{ "<blah>"|escape }}
// => <blah>

{{ "<blah>"|e("js") }}
// => \u003Cblah\u003E

first

Source: lib/filters.js#L209

Get the first item in an array or character in a string. All other objects will attempt to return the first value available.

Returns

*: The first item of the array or first character of the string input.

Examples

// my_arr = ['a', 'b', 'c']
{{ my_arr|first }}
// => a

// my_val = 'Tacos'
{{ my_val|first }}
// T

groupBy(key)

Source: lib/filters.js#L240

Group an array of objects by a common key. If an array is not provided, the input value will be returned untouched.

Parameters

Name	Type	Optional	Default	Description
`key`	`string`		`undefined`	Key to group by.

Returns

object: Grouped arrays by given key.

Examples

// people = [{ age: 23, name: 'Paul' }, { age: 26, name: 'Jane' }, { age: 23, name: 'Jim' }];
{% for agegroup in people|groupBy('age') %}
  <h2>{{ loop.key }}</h2>
  <ul>
    {% for person in agegroup %}
    <li>{{ person.name }}</li>
    {% endfor %}
  </ul>
{% endfor %}

join(glue)

Source: lib/filters.js#L283

Join the input with a string.

Parameters

Name	Type	Optional	Default	Description
`glue`	`string`		`undefined`	String value to join items together.

Returns

string:

Examples

// my_array = ['foo', 'bar', 'baz']
{{ my_array|join(', ') }}
// => foo, bar, baz

// my_key_object = { a: 'foo', b: 'bar', c: 'baz' }
{{ my_key_object|join(' and ') }}
// => foo and bar and baz

json(indent)

Source: lib/filters.js#L319

Return a string representation of an JavaScript object.

Backwards compatible with swig@0.x.x using `json_encode`.

Parameters

Name	Type	Optional	Default	Description
`indent`	`number`	✔	`undefined`	Number of spaces to indent for pretty-formatting.

Returns

string: A valid JSON string.

Examples

// val = { a: 'b' }
{{ val|json }}
// => {"a":"b"}

// val = { a: 'b' }
{{ val|json(4) }}
// => {
//        "a": "b"
//    }

last

Source: lib/filters.js#L340

Get the last item in an array or character in a string. All other objects will attempt to return the last value available.

Returns

*: The last item of the array or last character of the string.input.

Examples

// my_arr = ['a', 'b', 'c']
{{ my_arr|last }}
// => c

// my_val = 'Tacos'
{{ my_val|last }}
// s

length

Source: lib/filters.js#L374

Get the number of items in an array, string, or object.

Returns

*: The length of the input

Examples

// my_arr = ['a', 'b', 'c']
{{ my_arr|length }}
// => 3

// my_str = 'Tacos'
{{ my_str|length }}
// => 5

// my_obj = {a: 5, b: 20}
{{ my_obj|length }}
// => 2

lower

Source: lib/filters.js#L400

Return the input in all lowercase letters.

Returns

*: Returns the same type as the input.

Examples

{{ "FOOBAR"|lower }}
// => foobar

// myObj = { a: 'FOO', b: 'BAR' }
{{ myObj|lower|join('') }}
// => foobar

raw

Source: lib/filters.js#L412

Deprecated in favor of safe.

replace(search, replacement, flags)

Source: lib/filters.js#L441

Returns a new string with the matched search pattern replaced by the given replacement string. Uses JavaScript's built-in String.replace() method.

Parameters

Name	Type	Optional	Default	Description
`search`	`string`		`undefined`	String or pattern to replace from the input.
`replacement`	`string`		`undefined`	String to replace matched pattern.
`flags`	`string`	✔	`undefined`	Regular Expression flags. 'g': global match, 'i': ignore case, 'm': match over multiple lines

Returns

string: Replaced string.

Examples

// my_var = 'foobar';
{{ my_var|replace('o', 'e', 'g') }}
// => feebar

// my_var = "farfegnugen";
{{ my_var|replace('^f', 'p') }}
// => parfegnugen

// my_var = 'a1b2c3';
{{ my_var|replace('\w', '0', 'g') }}
// => 010203

reverse

Source: lib/filters.js#L457

Reverse sort the input. This is an alias for {{ input|sort(true) }}.

Returns

array: Reversed array. The original input object is returned if it was not an array.

Examples

// val = [1, 2, 3];
{{ val|reverse }}
// => 3,2,1

safe

Source: lib/filters.js#L472

Forces the input to not be auto-escaped. Use this only on content that you know is safe to be rendered on your page.

Returns

*: The input exactly how it was given, regardless of autoescaping status.

Examples

// my_var = "<p>Stuff</p>";
{{ my_var|safe }}
// => <p>Stuff</p>

sort(reverse)

Source: lib/filters.js#L502

Sort the input in an ascending direction.

If given an object, will return the keys as a sorted array.

If given a string, each character will be sorted individually.

Parameters

Name	Type	Optional	Default	Description
`reverse`	`boolean`	✔	`false`	Output is given reverse-sorted if true.

Returns

*: Sorted array;

Examples

// val = [2, 6, 4];
{{ val|sort }}
// => 2,4,6

// val = 'zaq';
{{ val|sort }}
// => aqz

// val = { bar: 1, foo: 2 }
{{ val|sort(true) }}
// => foo,bar

striptags

Source: lib/filters.js#L539

Strip HTML tags.

Returns

*: Returns the same object as the input, but with all string values stripped of tags.

Examples

// stuff = '<p>foobar</p>';
{{ stuff|striptags }}
// => foobar

title

Source: lib/filters.js#L564

Capitalizes every word given and lower-cases all other letters.

Returns

*: Returns the same object as the input, but with all words in strings title-cased.

Examples

// my_str = 'this is soMe text';
{{ my_str|title }}
// => This Is Some Text

// my_arr = ['hi', 'this', 'is', 'an', 'array'];
{{ my_arr|title|join(' ') }}
// => Hi This Is An Array

uniq

Source: lib/filters.js#L586

Remove all duplicate items from an array.

Returns

array: Array with unique items. If input was not an array, the original item is returned untouched.

Examples

// my_arr = [1, 2, 3, 4, 4, 3, 2, 1];
{{ my_arr|uniq|join(',') }}
// => 1,2,3,4

upper

Source: lib/filters.js#L618

Convert the input to all uppercase letters. If an object or array is provided, all values will be uppercased.

Returns

*: Returns the same type as the input, with all strings upper-cased.

Examples

// my_str = 'tacos';
{{ my_str|upper }}
// => TACOS

// my_arr = ['tacos', 'burritos'];
{{ my_arr|upper|join(' & ') }}
// => TACOS & BURRITOS

url_encode

Source: lib/filters.js#L638

URL-encode a string. If an object or array is passed, all values will be URL-encoded.

Returns

*: URL-encoded string.

Examples

// my_str = 'param=1&anotherParam=2';
{{ my_str|url_encode }}
// => param%3D1%26anotherParam%3D2

url_decode

Source: lib/filters.js#L657

URL-decode a string. If an object or array is passed, all values will be URL-decoded.

Returns

*: URL-decoded string.

Examples

// my_str = 'param%3D1%26anotherParam%3D2';
{{ my_str|url_decode }}
// => param=1&anotherParam=2