some tweaks

cookbook/form/form_collections.rst

@@ -729,79 +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
+.. _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:
+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
 
-        <!-- src/Acme/TaskBundle/Resources/views/Task/prototypeTask.html.twig -->
-        data-prototype="{% filter escape %}
-            {% include 'AcmeTaskBundle:Task:prototypeTask.html.twig'
-                with { 'task': form.task.get('prototype') }
-            %}
-        {% endfilter %}"
-
-    .. code-block:: html+php
-
-        <!-- src/Acme/TaskBundle/Resources/views/Task/prototypeTask.html.php -->
-        data-prototype="<?php
-            $prototype = $view->render(
-                'AcmeTaskBundle:Task:prototypeTask.html.php',
-                array('task' => $form->task->get('prototype'))
-            );
+        {% form_theme form _self %}
 
-            echo $view->escape($prototype);
-        ?>"
-
-To be not confused let's have a look how the prototype-template might look like.
-
-.. configuration-block::
+        {% block _tasks_entry_widget %}
+            <li>
+                {{ form_widget(task.task) }}
+                {{ form_widget(task.dueDate) }}
+            </li>
+        {% endblock %}
 
-    .. code-block:: html+jinja
+    .. code-block:: html+php
 
-        <tr>
-            <td>{{ form_widget(task.task) }}</td>
-            <td>{{ form_widget(task.dueDate) }}</td>
-        </tr>
+        <!-- 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>
 
-    .. code-block:: html+php
+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:
 
-        <tr>
-            <td><?php echo $view['form']->widget($task->getTask()) ?></td>
-            <td><?php echo $view['form']->widget($task->getDueDate()) ?></td>
-        </tr>
+================  =======================
+Part of the Form  Block Name
+================  =======================
+``label``         ``_tasks_entry_label``
+``widget``        ``_tasks_entry_widget``
+``row``           ``_tasks_entry_row``
+================  =======================
 
-The included template contains the markup used for the prototype.
-This way you can not only easily structure your prototype-markup,
-you can also use this markup to render the
-contents of the collection when it already holds items:
+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
 
-        {% for task in tasks %}
-            {% include 'AcmeTaskBundle:Task:prototypeTask.html.twig'
-                with { 'form': form.task.vars.form }
-            %}
-        {% endfor %}
+        {% form_theme form _self %}
 
-    .. code-block:: html+php
+        {% 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 %}
 
-        <?php foreach ($tasks as $task) ?>
-            <?php echo $view->render('AcmeTaskBundle:Task:prototypeTask.html.php', array('form' => $form->task->vars->form)); ?>
-        <?php endforeach; ?>
+    .. code-block:: html+php
 
-This makes sure the displayed items are the same as the newly inserted
-from the prototype.
+        <!-- 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/