.. 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 %} {% endfor %} {% endfor %}
{{ column }}
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"