document how to render custom collection prototypes

daFish · xabbuh · commit c8dbd79d5540 · 2015-05-21T22:09:01.000+02:00
diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst
@@ -729,5 +729,75 @@ the relationship between the removed ``Tag`` and ``Task`` object.
     updated (whether you're adding new tags or removing existing tags) on
     each Tag object itself.
 
+.. _cookbook-form-collections-custom-prototype:
+
+Rendering a Custom Prototype
+----------------------------
+
+Most of the time the provided prototype will be sufficient for your needs
+and does not need to be changed. But if you are in the situation were you
+need to have a complete custom prototype, you can render it yourself.
+
+The Form component automatically looks for a block whose name follows a certain
+schema to decide how to render each entry of the form type collection. For
+example, if your form field is named ``tasks``, you will be able to change
+the widget for each task as follows:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {% form_theme form _self %}
+
+        {% block _tasks_entry_widget %}
+            <li>
+                {{ form_widget(task.task) }}
+                {{ form_widget(task.dueDate) }}
+            </li>
+        {% endblock %}
+
+    .. code-block:: html+php
+
+        <!-- src/AppBundle/Resources/views/Form/_tasks_entry_widget.html.php -->
+        <li>
+            <?php echo $view['form']->widget($form->task) ?>
+            <?php echo $view['form']->widget($form->dueDate) ?>
+        </li>
+
+Not only can you override the rendered widget, but you can also change the
+complete form row or the label as well. For the ``tasks`` field given above,
+the block names would be the following:
+
+================  =======================
+Part of the Form  Block Name
+================  =======================
+``label``         ``_tasks_entry_label``
+``widget``        ``_tasks_entry_widget``
+``row``           ``_tasks_entry_row``
+================  =======================
+
+Then, you only have to ensure to render the collection type's ``data-prototype``
+property with the proper prototype so that new entries will be rendered the
+same way as existing ones:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {% form_theme form _self %}
+
+        {% block _tasks_widget %}
+            {% set attr = attr|merge({ 'data-prototype': form_row(prototype) }) %}
+            <ul {{ block('widget_container_attributes') }}>
+                {% for child in form %}
+                    {{ form_row(child) }}
+                {% endfor %}
+            </ul>
+        {% endblock %}
+
+    .. code-block:: html+php
+
+        <!-- src/AppBundle/Resources/views/Form/_tasks_widget.html.php -->
+
 .. _`Owning Side and Inverse Side`: http://docs.doctrine-project.org/en/latest/reference/unitofwork-associations.html
 .. _`JSFiddle`: http://jsfiddle.net/847Kf/4/
