vendor/twig/twig/doc/tags/for.rst

   1 ``for``
   2 =======
   3
   4 Loop over each item in a sequence. For example, to display a list of users
   5 provided in a variable called ``users``:
   6
   7 .. code-block:: jinja
   8
   9     <h1>Members</h1>
  10     <ul>
  11         {% for user in users %}
  12             <li>{{ user.username|e }}</li>
  13         {% endfor %}
  14     </ul>
  15
  16 .. note::
  17
  18     A sequence can be either an array or an object implementing the
  19     ``Traversable`` interface.
  20
  21 If you do need to iterate over a sequence of numbers, you can use the ``..``
  22 operator:
  23
  24 .. code-block:: jinja
  25
  26     {% for i in 0..10 %}
  27         * {{ i }}
  28     {% endfor %}
  29
  30 The above snippet of code would print all numbers from 0 to 10.
  31
  32 It can be also useful with letters:
  33
  34 .. code-block:: jinja
  35
  36     {% for letter in 'a'..'z' %}
  37         * {{ letter }}
  38     {% endfor %}
  39
  40 The ``..`` operator can take any expression at both sides:
  41
  42 .. code-block:: jinja
  43
  44     {% for letter in 'a'|upper..'z'|upper %}
  45         * {{ letter }}
  46     {% endfor %}
  47
  48 .. tip:
  49
  50     If you need a step different from 1, you can use the ``range`` function
  51     instead.
  52
  53 The `loop` variable
  54 -------------------
  55
  56 Inside of a ``for`` loop block you can access some special variables:
  57
  58 ===================== =============================================================
  59 Variable              Description
  60 ===================== =============================================================
  61 ``loop.index``        The current iteration of the loop. (1 indexed)
  62 ``loop.index0``       The current iteration of the loop. (0 indexed)
  63 ``loop.revindex``     The number of iterations from the end of the loop (1 indexed)
  64 ``loop.revindex0``    The number of iterations from the end of the loop (0 indexed)
  65 ``loop.first``        True if first iteration
  66 ``loop.last``         True if last iteration
  67 ``loop.length``       The number of items in the sequence
  68 ``loop.parent``       The parent context
  69 ===================== =============================================================
  70
  71 .. code-block:: jinja
  72
  73     {% for user in users %}
  74         {{ loop.index }} - {{ user.username }}
  75     {% endfor %}
  76
  77 .. note::
  78
  79     The ``loop.length``, ``loop.revindex``, ``loop.revindex0``, and
  80     ``loop.last`` variables are only available for PHP arrays, or objects that
  81     implement the ``Countable`` interface. They are also not available when
  82     looping with a condition.
  83
  84 .. versionadded:: 1.2
  85     The ``if`` modifier support has been added in Twig 1.2.
  86
  87 Adding a condition
  88 ------------------
  89
  90 Unlike in PHP, it's not possible to ``break`` or ``continue`` in a loop. You
  91 can however filter the sequence during iteration which allows you to skip
  92 items. The following example skips all the users which are not active:
  93
  94 .. code-block:: jinja
  95
  96     <ul>
  97         {% for user in users if user.active %}
  98             <li>{{ user.username|e }}</li>
  99         {% endfor %}
 100     </ul>
 101
 102 The advantage is that the special loop variable will count correctly thus not
 103 counting the users not iterated over. Keep in mind that properties like
 104 ``loop.last`` will not be defined when using loop conditions.
 105
 106 .. note::
 107
 108     Using the ``loop`` variable within the condition is not recommended as it
 109     will probably not be doing what you expect it to. For instance, adding a
 110     condition like ``loop.index > 4`` won't work as the index is only
 111     incremented when the condition is true (so the condition will never
 112     match).
 113
 114 The `else` Clause
 115 -----------------
 116
 117 If no iteration took place because the sequence was empty, you can render a
 118 replacement block by using ``else``:
 119
 120 .. code-block:: jinja
 121
 122     <ul>
 123         {% for user in users %}
 124             <li>{{ user.username|e }}</li>
 125         {% else %}
 126             <li><em>no user found</em></li>
 127         {% endfor %}
 128     </ul>
 129
 130 Iterating over Keys
 131 -------------------
 132
 133 By default, a loop iterates over the values of the sequence. You can iterate
 134 on keys by using the ``keys`` filter:
 135
 136 .. code-block:: jinja
 137
 138     <h1>Members</h1>
 139     <ul>
 140         {% for key in users|keys %}
 141             <li>{{ key }}</li>
 142         {% endfor %}
 143     </ul>
 144
 145 Iterating over Keys and Values
 146 ------------------------------
 147
 148 You can also access both keys and values:
 149
 150 .. code-block:: jinja
 151
 152     <h1>Members</h1>
 153     <ul>
 154         {% for key, user in users %}
 155             <li>{{ key }}: {{ user.username|e }}</li>
 156         {% endfor %}
 157     </ul>
 158
 159 Iterating over a Subset
 160 -----------------------
 161
 162 You might want to iterate over a subset of values. This can be achieved using
 163 the :doc:`slice <../filters/slice>` filter:
 164
 165 .. code-block:: jinja
 166
 167     <h1>Top Ten Members</h1>
 168     <ul>
 169         {% for user in users|slice(0, 10) %}
 170             <li>{{ user.username|e }}</li>
 171         {% endfor %}
 172     </ul>