.. _template_filters:

#####################
Default Filters
#####################

.. highlight:: html+jinja

**Usage:**

Filters must be embedded in double curly brackets {{ ... }}. The filter must be appended after the content / placeholder to apply to with a pipe (|).

**Example:**

.. code::

    {{ "[post_title]"|trim|upper }}

This example uses two filters. The first trims the post title and the second transforms it to upper case.

.. note::

    You can combine multiple filters.


.. note::

    You can use all default `Twig filters <https://twig.symfony.com/doc/filters/index.html>`_.


batch
~~~~~

The batch filter is very useful if you are working with a HTML template and want to show list data in a table. The batch filter divides the list in smaller parts of lists. The size of the lists is defined by the first parameter. The second parameter can be used to fill missing items.

Let's assume [post_tags_array] contains this list data: Array("Butter", "Milk", "Sugar", "Eggs", "Salt", "Oil", "Vanilla")

.. code::

    <table>
    {% for row in [post_tags_array]|batch(3, 'No tag') %}
        <tr>
            {% for column in row %}
                <td>{{ column }}</td>
            {% endfor %}
        </tr>
    {% endfor %}
    </table>

The example will be rendered as:

.. code::

    <table>
        <tr>
            <td>Butter</td>
            <td>Milk</td>
            <td>Sugar</td>
        </tr>
        <tr>
            <td>Eggs</td>
            <td>Salt</td>
            <td>Oil</td>
        </tr>
        <tr>
            <td>Vanilla</td>
            <td>No tag</td>
            <td>No tag</td>
        </tr>
    </table>

capitalize
~~~~~~~~~~

The capitalize filter capitalizes a placeholder string. The first value will be uppercase, the others lowercase.

.. code::

    {{ "[post_title]"|capitalize }}

convert_encoding
~~~~~~~~~~~~~~~~

If you are sending HTML mails, the convert_encoding filter can be useful if you have issues with character encodings. This filter converts a string from one encoding to another. The first argument is the expected output charset, the second argument is the input charset.

.. code::

    {{ "[post_title]"|convert_encoding('UTF-8', 'iso-2022-jp') }}

.. note::

    This filter relies on the `iconv <http://php.net/iconv>`_ or `mbstring <http://php.net/mbstring>`_ extension, so one of them must be installed.

date
~~~~

Formats the post date to a given format:

.. code::

    {{ "[post_date]"|date("m/d/Y") }}

The format specifier is the same as supported by the PHP function `date <http://php.net/manual/de/function.date.php>`_.

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 <http://www.php.net/strtotime>`_ function) or `DateTime <http://www.php.net/DateTime>`_ instances. You can combine it with the date filter.

.. code::

    {{ "[post_date]2|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::

    {{ "[post_excerpt]"|default('excerpt is not defined') }}

escape
~~~~~~

The ``escape`` filter can be used to escape a placeholder's value for safe insertion into the message. By default, it uses the HTML escaping strategy. An optional argument defines the escaping strategy to use.

.. code::

    {{ "[author_display_name]"|escape }}
    {{ "[author_display_name]"|escape('js') }}
    {{ "[author_display_name]"|escape('css') }}
    {{ "[author_display_name]"|escape('url') }}
    {{ "[author_display_name]"|escape('html_attr') }}

first
~~~~~

The first filter returns the first "element" of a sequence, a mapping, or a string.

Let's assume [post_tags_array] contains this list data: Array("Butter", "Milk", "Sugar")

.. code::

    {{ [post_tags_array]|first }}

This example will retrieve "Butter".

format
~~~~~~

The ``format`` filter formats a given string by replacing the placeholders which follow the `sprintf <http://www.php.net/sprintf>`_ notation.

.. code::

    {{ "I like %s and %s."|format("WordPress", "Post Status Notifier") }}

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 [post_tags_array] contains this list data: Array("Butter", "Milk", "Sugar")

.. code::

    {{ [post_tags_array]|join('::') }}


This example results in:
Butter::Milk::Sugar

json_encode
~~~~~~~~~~~

The ``json_encode`` filter uses the PHP function ``json_encode`` and returns the JSON represantation of a string.

.. code::

    {{ "[post_tags]"|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 [post_tags_array]|keys %}
    ...
    {% endfor %}

last
~~~~

The ``last`` filter returns the last element of a list.

Let's assume [post_tags_array] contains this list data: Array("Butter", "Milk", "Sugar")

.. code::

    {{ [post_tags_array]|last }}

This example will retrieve "Sugar".

length
~~~~~~

The ``length`` filter returns the length of a list.

Let's assume [post_tags_array] contains this list data: Array("Butter", "Milk", "Sugar")

.. code::

    {{ [post_tags_array]|length }}

This example will retrieve "3".

lower
~~~~~

The ``lower`` filter converts a value to lowercase.

.. code::

    {{ "[post_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::

    {{ "[post_content]"|nl2br }}

number_format
~~~~~~~~~~~~~

The ``number_format`` formats numbers. It uses the PHP function `number_format <http://php.net/number_format>`_. Using additional arguments you can set the number of decimal places, decimal point, and thousands separator.

.. code::

    {{ 9800.333|number_format(2, '.', ',') }}

merge
~~~~~

With the ``merge`` filter you can merge two arrays.

.. code::

    {{ [post_tags_array]|merge([post_categories_array])) }}

This example joins the post tags and categories into one array.

upper
~~~~~

The ``upper`` filter converts a value to uppercase.

.. code::

    {{ "[post_title]"|upper }}

replace
~~~~~~~

This will replace the strings "iPhone" and "Galaxy S5" in the post title to "Smartphone":

.. code::

    {{ "[post_title]"|replace({'iPhone': 'Smartphone', 'Galaxy S5': 'Smartphone'}) }}


reverse
~~~~~~~

The ``reverse`` filter reverses a list.

Let's assume [post_tags] contains this information: Array("Butter", "Milk", "Sugar")

.. code::

    {{ [post_tags_array]|reverse|join(',') }}

This example will retrieve "Sugar,Milk,Butter".

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.

.. code::

    {{ '12345'|slice(1, 2) }}

Outputs: 23

sort
~~~~

The ``sort`` filter sorts an array.

Let's assume [post_tags_array] contains this information: Array("Sugar", "Butter", "Milk")

.. code::

    {{ [post_tags_array]|sort }}

The result will be: Array("Butter", "Milk", "Sugar")

split
~~~~~

The ``split`` filter splits a string by the given delimiter and returns a list of strings.

.. code::

    <ul>{% for key in "[post_custom_fields]"|split(',') %}
      <li>{{ key|trim }}</li>
    {% endfor %}</ul>

title
~~~~~

The ``title`` filter returns a titlecased version of the value. Words will start with uppercase letters, all remaining characters are lowercase.

.. code::

    {{ "[post_title]"|title }}

If [post_title] contains ``my cool new post``, this filter would return ``My Cool New Post``.

trim
~~~~

The ``trim`` filter strips whitespace (or other characters) from the beginning and end of a string.

.. code::

    {{ "[post_title]"|trim }}

.. |nbsp| unicode:: 0xA0
    :trim:

If [post_title] contains "|nbsp| |nbsp| |nbsp| my cool new post |nbsp| |nbsp| |nbsp|" this filter would return "my cool new post".

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(true) }}
    # outputs "string%20with%20spaces"
    {{ {'param': 'value', 'foo': 'bar'}|url_encode }}
    # outputs "param=value&foo=bar"


.. note::

    Check out the `Twig documentation page <https://twig.symfony.com/doc/filters/index.html>`_ for more details about filters.