1``for`` 2======= 3 4Loop over each item in a sequence. For example, to display a list of users 5provided 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 21If you do need to iterate over a sequence of numbers, you can use the ``..`` 22operator: 23 24.. code-block:: jinja 25 26 {% for i in 0..10 %} 27 * {{ i }} 28 {% endfor %} 29 30The above snippet of code would print all numbers from 0 to 10. 31 32It can be also useful with letters: 33 34.. code-block:: jinja 35 36 {% for letter in 'a'..'z' %} 37 * {{ letter }} 38 {% endfor %} 39 40The ``..`` 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 53The `loop` variable 54------------------- 55 56Inside of a ``for`` loop block you can access some special variables: 57 58===================== ============================================================= 59Variable 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 87Adding a condition 88------------------ 89 90Unlike in PHP, it's not possible to ``break`` or ``continue`` in a loop. You 91can however filter the sequence during iteration which allows you to skip 92items. 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 102The advantage is that the special loop variable will count correctly thus not 103counting 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 114The `else` Clause 115----------------- 116 117If no iteration took place because the sequence was empty, you can render a 118replacement 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 130Iterating over Keys 131------------------- 132 133By default, a loop iterates over the values of the sequence. You can iterate 134on 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 145Iterating over Keys and Values 146------------------------------ 147 148You 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 159Iterating over a Subset 160----------------------- 161 162You might want to iterate over a subset of values. This can be achieved using 163the :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> 173