diff options
Diffstat (limited to 'vendor/twig/twig/doc/tags/for.rst')
-rw-r--r-- | vendor/twig/twig/doc/tags/for.rst | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/vendor/twig/twig/doc/tags/for.rst b/vendor/twig/twig/doc/tags/for.rst new file mode 100644 index 00000000..0673b551 --- /dev/null +++ b/vendor/twig/twig/doc/tags/for.rst | |||
@@ -0,0 +1,172 @@ | |||
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> | ||