docs: document correct unicorn:model pattern for {% for %} loops

Author: JohananOppongAmoateng

docs/source/templates.md

@@ -65,6 +65,57 @@ class HelloWorldView(UnicornView):
 [Django models](django-models.md) has many more details about using Django models in `Unicorn`.
 ```
 
+## Models inside `{% for %}` loops
+
+When iterating over a list with a Django `{% for %}` loop, the loop variable is **not** the same as the component attribute that holds the list. Unicorn syncs `<input>` values by looking up the `unicorn:model` name in the component's serialised data, so the model name must use the **component attribute path** (e.g. `items.0.name`), not the loop variable name (e.g. `item.name`).
+
+Use `{{ forloop.counter0 }}` to build the correct index-based path:
+
+```python
+# line_items.py
+from django_unicorn.components import UnicornView
+
+class LineItemsView(UnicornView):
+    items: list = []
+
+    def mount(self):
+        self.items = [{"name": "Widget", "qty": 1}, {"name": "Gadget", "qty": 3}]
+
+    def add_item(self):
+        self.items.append({"name": "", "qty": 0})
+```
+
+```html
+<!-- unicorn/line-items.html -->
+<div>
+  {% for item in items %}
+  <div>
+    <input
+      unicorn:model="items.{{ forloop.counter0 }}.name"
+      type="text"
+    />
+    <input
+      unicorn:model="items.{{ forloop.counter0 }}.qty"
+      type="number"
+    />
+  </div>
+  {% endfor %}
+  <button unicorn:click="add_item">Add row</button>
+</div>
+```
+
+The key is `items.{{ forloop.counter0 }}.name` this renders to `items.0.name`, `items.1.name`, etc., which Unicorn can resolve directly against the component data.
+
+```{warning}
+Using the **loop variable name** in `unicorn:model` (e.g. `unicorn:model="item.name"`)
+will **not** work correctly after a re-render.  When the component re-renders,
+Unicorn tries to look up `item` in the component's data, but `item` is only a
+Django template loop variable — it has no corresponding key in the serialised
+component state.  As a result morphdom will clear the input's value.
+
+Use `items.{{ forloop.counter0 }}.name` instead.
+```
+
 ## Model modifiers
 
 ### Lazy