mirror of
https://github.com/twigphp/Twig.git
synced 2026-09-14 19:36:43 +00:00
minor #4159 Reorganize the for tag docs (fabpot)
This PR was merged into the 4.x branch.
Discussion
----------
Reorganize the for tag docs
Commits
-------
d6add5eb Reorganize the for tag docs
This commit is contained in:
Fabien Potencier
+103
-86
@@ -50,92 +50,6 @@ The ``..`` operator can take any expression at both sides:
|
||||
If you need a step different from 1, you can use the ``range`` function
|
||||
instead.
|
||||
|
||||
The ``loop`` variable
|
||||
---------------------
|
||||
|
||||
Inside of a ``for`` loop block you can access some special variables:
|
||||
|
||||
===================== ========================================================================
|
||||
Variable Description
|
||||
===================== ========================================================================
|
||||
``loop.index`` The current iteration of the loop. (1 indexed)
|
||||
``loop.index0`` The current iteration of the loop. (0 indexed)
|
||||
``loop.revindex`` The number of iterations from the end of the loop (1 indexed)
|
||||
``loop.revindex0`` The number of iterations from the end of the loop (0 indexed)
|
||||
``loop.first`` True if first iteration
|
||||
``loop.last`` True if last iteration
|
||||
``loop.length`` The number of items in the sequence
|
||||
``loop.parent`` The parent context
|
||||
``loop.cycle`` Cycle over a sequence of values
|
||||
``loop.changed`` True if previously called with a different value or if not called yet
|
||||
``loop.previous`` The value from the previous iteration (``null`` for the first iteration)
|
||||
``loop.next`` The value from the next iteration (``null`` for the last iteration)
|
||||
===================== ========================================================================
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% for user in users %}
|
||||
{{ loop.index }} - {{ user.username }}
|
||||
{% endfor %}
|
||||
|
||||
Use ``loop.cycle`` to cycle among a list of values:
|
||||
|
||||
.. code-block:: html+twig
|
||||
|
||||
{% for row in rows %}
|
||||
<li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
|
||||
{% endfor %}
|
||||
|
||||
Use ``loop.previous`` and ``loop.next`` to access the previous or next values:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% for value in values %}
|
||||
{% if not loop.first and value > loop.previous %}
|
||||
The value just increased!
|
||||
{% endif %}
|
||||
{{ value }}
|
||||
{% if not loop.last and loop.next > value %}
|
||||
The value will increase even more!
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
``loop.previous`` is ``null`` when called at the first item, and ``loop.next``
|
||||
is ``null`` when called at the last item.
|
||||
|
||||
Use ``loop.changed`` to check if the value has changed since the last call:
|
||||
|
||||
.. code-block:: html+twig
|
||||
|
||||
{% for entry in entries %}
|
||||
{% if loop.changed(entry.category) %}
|
||||
<h2>{{ entry.category }}</h2>
|
||||
{% endif %}
|
||||
<p>{{ entry.message }}</p>
|
||||
{% endfor %}
|
||||
|
||||
.. note::
|
||||
|
||||
When the underlying PHP iterator is not countable, the ``loop.length``,
|
||||
``loop.revindex``, and ``loop.revindex0`` variables are not available and a
|
||||
``RuntimeException`` is thrown if you try to use them.
|
||||
|
||||
The ``else`` Clause
|
||||
-------------------
|
||||
|
||||
If no iteration took place because the sequence was empty, you can render a
|
||||
replacement block by using ``else``:
|
||||
|
||||
.. code-block:: html+twig
|
||||
|
||||
<ul>
|
||||
{% for user in users %}
|
||||
<li>{{ user.username|e }}</li>
|
||||
{% else %}
|
||||
<li><em>no user found</em></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
|
||||
Iterating over Keys
|
||||
-------------------
|
||||
|
||||
@@ -179,3 +93,106 @@ the :doc:`slice <../filters/slice>` filter:
|
||||
<li>{{ user.username|e }}</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
|
||||
The ``else`` Clause
|
||||
-------------------
|
||||
|
||||
If no iteration took place because the sequence was empty, you can render a
|
||||
replacement block by using ``else``:
|
||||
|
||||
.. code-block:: html+twig
|
||||
|
||||
<ul>
|
||||
{% for user in users %}
|
||||
<li>{{ user.username|e }}</li>
|
||||
{% else %}
|
||||
<li><em>no user found</em></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
|
||||
The ``loop`` Object
|
||||
-------------------
|
||||
|
||||
Inside of a ``for`` loop block, a ``loop`` object exposes some information
|
||||
about the current loop iteration.
|
||||
|
||||
``loop`` Variables
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
===================== ========================================================================
|
||||
Variable Description
|
||||
===================== ========================================================================
|
||||
``loop.index`` The current iteration of the loop (1 indexed)
|
||||
``loop.index0`` The current iteration of the loop (0 indexed)
|
||||
``loop.revindex``* The number of iterations from the end of the loop (1 indexed)
|
||||
``loop.revindex0``* The number of iterations from the end of the loop (0 indexed)
|
||||
``loop.first`` True if first iteration
|
||||
``loop.last`` True if last iteration
|
||||
``loop.length``* The number of items in the sequence
|
||||
``loop.parent`` The parent context
|
||||
``loop.previous`` The value from the previous iteration (``null`` for the first iteration)
|
||||
``loop.next`` The value from the next iteration (``null`` for the last iteration)
|
||||
===================== ========================================================================
|
||||
|
||||
.. note::
|
||||
|
||||
When the underlying PHP iterator is not countable, the ``loop.length``,
|
||||
``loop.revindex``, and ``loop.revindex0`` variables are not available and a
|
||||
``RuntimeException`` is thrown if you try to use them.
|
||||
|
||||
Here is an example on how to use the ``index`` variable:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% for user in users %}
|
||||
{{ loop.index }} - {{ user.username }}
|
||||
{% endfor %}
|
||||
|
||||
Use ``loop.previous`` and ``loop.next`` to access the previous or next values:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{% for value in values %}
|
||||
{% if not loop.first and value > loop.previous %}
|
||||
The value just increased!
|
||||
{% endif %}
|
||||
{{ value }}
|
||||
{% if not loop.last and loop.next > value %}
|
||||
The value will increase even more!
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
``loop.previous`` is ``null`` when called at the first item, and ``loop.next``
|
||||
is ``null`` when called at the last item.
|
||||
|
||||
``loop`` Functions
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ``loop`` object also exposes some functions:
|
||||
|
||||
===================== ========================================================================
|
||||
Function Description
|
||||
===================== ========================================================================
|
||||
``loop.cycle()`` Cycle over a sequence of values
|
||||
``loop.changed()`` True if previously called with a different value or if not called yet
|
||||
``loop()`` Allows to iterate over a nested sequence/mapping
|
||||
===================== ========================================================================
|
||||
|
||||
Use ``loop.cycle()`` to cycle among a list of values:
|
||||
|
||||
.. code-block:: html+twig
|
||||
|
||||
{% for row in rows %}
|
||||
<li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
|
||||
{% endfor %}
|
||||
|
||||
Use ``loop.changed()`` to check if the value has changed since the last call:
|
||||
|
||||
.. code-block:: html+twig
|
||||
|
||||
{% for entry in entries %}
|
||||
{% if loop.changed(entry.category) %}
|
||||
<h2>{{ entry.category }}</h2>
|
||||
{% endif %}
|
||||
<p>{{ entry.message }}</p>
|
||||
{% endfor %}
|
||||
|
||||
Reference in New Issue
Block a user