.. include:: _include.rst
.. highlight:: html+jinja
.. _template_filters:
#####################
Default Filters
#####################
With filters you can manipulate the contents of :ref:`placeholders`. Filters must be appended to a placeholder with a pipe (|).
This example will output the product title in upper case:
.. code::
{{ Title|upper }}
This example shows how to **combine multiple filters**. First the title will be changed to upper case and then the :ref:`filter_replace` filter will be processed:
.. code::
{{ Title|upper|replace({'SEARCH': 'REPLACE'}) }}
.. note::
You can combine multiple filters.
.. note::
You can use all default `Twig filters `_.
batch
~~~~~
This filter is very useful if you want to show data in columns. The ```batch`` filter divides the list into smaller parts. The size of the lists is defined by the first parameter. The second parameter can be used to fill missing items.
Let's assume {{ FeaturesArray }} contains this list data: Array("Butter", "Milk", "Sugar", "Eggs", "Salt", "Oil", "Vanilla")
.. code::
{% for row in FeaturesArray|batch(3, 'No tag') %}
{% for column in row %}
{{ column }} |
{% endfor %}
{% endfor %}
The output would be:
.. code::
Butter |
Milk |
Sugar |
Eggs |
Salt |
Oil |
Vanilla |
No tag |
No tag |
capitalize
~~~~~~~~~~
The capitalize filter capitalizes a placeholder string. The first value will be uppercase, the others lowercase.
.. code::
{{ Title|capitalize }}
convert_encoding
~~~~~~~~~~~~~~~~
The filter ``convert_encoding`` can be useful if you have issues with character encodings. It converts a string from one encoding to another. The first argument is the expected output charset, the second argument is the input charset.
.. code::
{{ EditorialReviewsContent|convert_encoding('UTF-8', 'iso-2022-jp') }}
.. note::
This filter relies on the `iconv `_ or `mbstring `_ extension, so one of them must be installed.
.. _filter_date:
date
~~~~
Formats a date to a given format:
.. code::
{{ PublicationDate|date("m/d/Y") }}
{{ RequestTimestamp|date("d.m.Y") }}
date_modify
~~~~~~~~~~~
With the ``date_modify`` filter you can modify dates with a given modifier string. It accepts strings (it must be in a format supported by the `strtotime `_ function) or `DateTime `_ instances. You can combine it with the date filter.
.. code::
{{ RequestTimestamp|date_modify("+1 day")|date("m/d/Y") }}
default
~~~~~~~
The ``default`` filter returns the passed default value if the placeholder value is undefined or empty.
.. code::
{{ repo_excerpt|default('excerpt is not defined') }}
escape
~~~~~~
The ``escape`` filter can be used to escape a placeholder's value for safe insertion. By default, it uses the HTML escaping strategy. An optional argument defines the escaping strategy to use.
.. code::
{{ repo_custom_field_my_comment|escape }}
{{ repo_custom_field_my_comment|escape('js') }}
{{ repo_custom_field_my_comment|escape('css') }}
{{ repo_custom_field_my_comment|escape('url') }}
{{ repo_custom_field_my_comment|escape('html_attr') }}
first
~~~~~
The first filter returns the first "element" of a sequence, a mapping, or a string.
Let's assume {{ Languages }} contains this list data: Array("English", "German", "Dutch"). Then this example will retrieve "English":
.. code::
{{ Languages|first }}
format
~~~~~~
The ``format`` filter formats a given string by replacing the placeholders which follow the `sprintf `_ notation.
.. code::
{{ "I like %s and %s."|format("WordPress", "ASA 2") }}
.. _template_filter_join:
join
~~~~
The ``join`` filter returns a string which is the concatenation of the items of a list. You can define the separator between the elements which is an empty string by default.
Let's assume {{ Languages }} contains this list data: Array("English", "German", "Dutch"). Then this example would create the output: English::German::Dutch
.. code::
{{ Languages|join('::') }}
json_encode
~~~~~~~~~~~
The ``json_encode`` filter uses the PHP function ``json_encode`` and returns the JSON represantation of a string.
.. code::
{{ Languages|json_encode() }}
keys
~~~~
The ``keys`` filter returns the keys of an array. It is useful when you want to iterate over the keys of an array.
.. code::
{% for key in repo_custom_field_my_assoc_array|keys %}
...
{% endfor %}
last
~~~~
The ``last`` filter returns the last element of a list.
Let's assume {{ Languages }} contains this list data: Array("English", "German", "Dutch"). Then this example will retrieve "Dutch":
.. code::
{{ Languages|last }}
length
~~~~~~
The ``length`` filter returns the length of a list.
Let's assume {{ Languages }} contains this list data: Array("English", "German", "Dutch"). Then this example would retrieve "3".
.. code::
{{ Languages|length }}
lower
~~~~~
The ``lower`` filter converts a value to lowercase.
.. code::
{{ Title|lower }}
nl2br
~~~~~
The ``nl2br`` filter can be useful if you work with HTML templates. It inserts HTML line breaks before newlines in a string.
.. code::
{{ FeaturesHTML|nl2br }}
number_format
~~~~~~~~~~~~~
The ``number_format`` formats numbers. It uses the PHP function `number_format `_. Using additional arguments you can set the number of decimal places, decimal point, and thousands separator.
.. code::
{{ 9800.333|number_format(2, '.', ',') }} // -> 9800,333
.. code::
{{ OffersMainPriceAmount|number_format(2, '.', ',') }}
merge
~~~~~
With the ``merge`` filter you can merge two arrays. This example joins the post tags and categories into one array.
.. code::
{{ FeaturesArray|merge(repo_custom_field_my_features)) }}
.. _filter_replace:
replace
~~~~~~~
The ``replace`` filter formats a given string by replacing the placeholders.
.. code::
{{ "I like %this% and %that%."|replace({'%this%': "WordPress", '%that%': "ASA 2"}) }
This example will replace the strings "wordpress" and "Wordpress" to "WordPress" in the product title:
.. code::
{{ Title|replace({'wordpress': 'WordPress', 'Wordpress': 'WordPress'}) }}
You can also use variables for replacements:
.. code::
{% set asa2 = 'ASA 2' %}
{{ "I like %this%."|replace({'%this%': asa2}) }
reverse
~~~~~~~
The ``reverse`` filter reverses a list.
Let's assume {{ Languages }} contains this list data: Array("English", "German", "Dutch"). Then this example would output: "Dutch,German,English"
.. code::
{{ Languages|reverse|join(',') }}
round
~~~~~
The ``round`` filter rounds a number to a given precision. It takes two optional arguments; the first one specifies the precision (default is 0) and the second the rounding method. Available methods are "floor", "ceil" and "common" (default is common):
.. code::
{{ 45.68|round }}
{{ 45.68|round(1, 'floor') }}
slice
~~~~~
The ``slice`` filter extracts a slice of a sequence, a mapping, or a string. You can use it for example to extract a certain part of a text.
.. code::
{{ '12345'|slice(1, 2) }}
// Output: 23
The next example will check if the Amazon product description contains more than 250 characters and if so, cut the text at this point and append three dots.
.. highlight:: bbcode
.. code::
{{ EditorialReviewsContent|length > 250 ? EditorialReviewsContent|slice(0, 250) ~ '...' : EditorialReviewsContent }}
.. highlight:: html+jinja
sort
~~~~
The ``sort`` filter sorts an array.
Let's assume {{ Languages }} contains this list data: Array("English", "German", "Dutch"). Then this example would sort {{ Languages }} to: Array("Dutch", "English", "German")
.. code::
{{ Languages|sort }}
split
~~~~~
The ``split`` filter splits a string by the given delimiter and returns a list of strings.
.. code::
{% set my_tackingids = "tracking-1,tracking-2,tracking-3"|split(',') %}
{# my_tackingids contains ['tracking-1', 'tracking-2', 'tracking-3'] #}
title
~~~~~
The ``title`` filter returns a titlecased version of the value. Words will start with uppercase letters, all remaining characters are lowercase.
.. code::
{{ Title|title }}
If Title contains ``lego star wars minifigure``, this filter would return ``Lego Star Wars Minifigure``.
trim
~~~~
The ``trim`` filter strips whitespace (or other characters) from the beginning and end of a string.
.. code::
{{ Title|trim }}
.. |nbsp| unicode:: 0xA0
:trim:
If Title contains "|nbsp| |nbsp| |nbsp| Lego Star Wars Minifigure |nbsp| |nbsp| |nbsp|" this filter would return "Lego Star Wars Minifigure".
.. _filter_upper:
upper
~~~~~
The ``upper`` filter converts a value to uppercase.
.. code::
{{ Title|upper }}
url_encode
~~~~~~~~~~
The ``url_encode`` filter encodes a given string as URL segment or an array as query string.
.. code-block:: jinja
{{ "path-seg*ment"|url_encode }}
# outputs "path-seg%2Ament"
{{ "string with spaces"|url_encode }}
# outputs "string%20with%20spaces"
{{ {'param': 'value', 'foo': 'bar'}|url_encode }}
# outputs "param=value&foo=bar"