Refactored docs to use adders/removers

Author: wouterj

cookbook/form/form_collections.rst

@@ -53,11 +53,6 @@ objects. Start by creating a simple ``Task`` class::
  {
  return $this->tags;
  }
-
- public function setTags(ArrayCollection $tags)
- {
- $this->tags = $tags;
- }
  }
 
 .. note::
@@ -240,9 +235,9 @@ zero tags when first created).
 
  <!-- ... -->
 
-When the user submits the form, the submitted data for the ``Tags`` fields
-are used to construct an ArrayCollection of ``Tag`` objects, which is then
-set on the ``tag`` field of the ``Task`` instance.
+When the user submits the form, the submitted data for the ``Tags`` fields are
+used to construct an ``ArrayCollection`` of ``Tag`` objects, which is then set
+on the ``tag`` field of the ``Task`` instance.
 
 The ``Tags`` collection is accessible naturally via ``$task->getTags()``
 and can be persisted to the database or used however you need.
@@ -286,7 +281,6 @@ add the ``allow_add`` option to your collection field::
  // src/Acme/TaskBundle/Form/Type/TaskType.php
 
  // ...
- 
  use Symfony\Component\Form\FormBuilderInterface;
 
  public function buildForm(FormBuilderInterface $builder, array $options)
@@ -296,18 +290,59 @@ add the ``allow_add`` option to your collection field::
  $builder->add('tags', 'collection', array(
  'type' => new TagType(),
  'allow_add' => true,
- 'by_reference' => false,
  ));
  }
 
-Note that ``'by_reference' => false`` was also added. Normally, the form
-framework would modify the tags on a `Task` object *without* actually
-ever calling `setTags`. By setting :ref:`by_reference<reference-form-types-by-reference>`
-to `false`, `setTags` will be called. This will be important later as you'll
-see.
+Now that the form type knows tags can be added, the ``Tasks`` class needs to
+add methods to make editing the tags possible. This is done by creating an
+"adder". In this case, the adder will be ``addTag``::
+
+ // src/Acme/TaskBundle/Entity/Task.php
+ namespace Acme\TaskBundle\Entity;
+
+ // ...
+ class Task
+ {
+ // ...
+
+ public function addTag($tag)
+ {
+ $this->tags->add($tag);
+ }
+
+ public function removeTag($tag)
+ {
+ // ...
+ }
+ }
+
+But, the form type will still use ``getTags`` now. You need to set the
+``by_reference`` option to ``false``, otherwise the form type will get the
+object by using the getter and change that object.
+
+.. caution::
+
+ If no ``addTag`` **and** ``removeTag`` method is found, the form will
+ still ``setTag`` when setting ``by_reference`` to ``false``. You'll learn
+ more about the ``removeTag`` method later in this article.
+
+.. code-block:: php
+
+ // src/Acme/TaskBundle/Form/Type/TaskType.php
+
+ // ...
+ public function buildForm(FormBuilderInterface $builder, array $options)
+ {
+ // ...
+
+ $builder->add('tags', 'collection', array(
+ // ...
+ 'by_reference' => false,
+ ));
+ }
 
 In addition to telling the field to accept any number of submitted objects, the
-``allow_add`` also makes a "prototype" variable available to you. This "prototype"
+``allow_add`` also makes a *"prototype"* variable available to you. This "prototype"
 is a little "template" that contains all the HTML to be able to render any
 new "tag" forms. To render it, make the following change to your template:
 
@@ -321,7 +356,9 @@ new "tag" forms. To render it, make the following change to your template:
 
  .. code-block:: html+php
 
- <ul class="tags" data-prototype="<?php echo $view->escape($view['form']->row($form['tags']->vars['prototype'])) ?>">
+ <ul class="tags" data-prototype="<?php
+ echo $view->escape($view['form']->row($form['tags']->vars['prototype']))
+ ?>">
  ...
  </ul>
 
@@ -430,13 +467,14 @@ into new ``Tag`` objects and added to the ``tags`` property of the ``Task`` obje
 
 .. sidebar:: Doctrine: Cascading Relations and saving the "Inverse" side
 
- To get the new tags to save in Doctrine, you need to consider a couple
- more things. First, unless you iterate over all of the new ``Tag`` objects
- and call ``$em->persist($tag)`` on each, you'll receive an error from
+ To save the new tags with Doctrine, you need to consider a couple more
+ things. First, unless you iterate over all of the new ``Tag`` objects and
+ call ``$em->persist($tag)`` on each, you'll receive an error from
  Doctrine:
 
- A new entity was found through the relationship `Acme\TaskBundle\Entity\Task#tags`
- that was not configured to cascade persist operations for entity...
+ A new entity was found through the relationship
+ ``Acme\TaskBundle\Entity\Task#tags`` that was not configured to
+ cascade persist operations for entity...
 
  To fix this, you may choose to "cascade" the persist operation automatically
  from the ``Task`` object to any related tags. To do this, add the ``cascade``
@@ -492,29 +530,25 @@ into new ``Tag`` objects and added to the ``tags`` property of the ``Task`` obje
  of the relationship is modified.
 
  The trick is to make sure that the single "Task" is set on each "Tag".
- One easy way to do this is to add some extra logic to ``setTags()``,
- which is called by the form framework since :ref:`by_reference<reference-form-types-by-reference>`
- is set to ``false``::
+ One easy way to do this is to add some extra logic to ``addTag()``,
+ which is called by the form type since ``by_reference`` is set to
+ ``false``::
 
  // src/Acme/TaskBundle/Entity/Task.php
 
  // ...
-
- public function setTags(ArrayCollection $tags)
+ public function addTag(ArrayCollection $tag)
  {
- foreach ($tags as $tag) {
- $tag->addTask($this);
- }
+ $tag->addTask($this);
 
- $this->tags = $tags;
+ $this->tags->add($tag);
  }
 
  Inside ``Tag``, just make sure you have an ``addTask`` method::
 
  // src/Acme/TaskBundle/Entity/Tag.php
 
  // ...
-
  public function addTask(Task $task)
  {
  if (!$this->tasks->contains($task)) {
@@ -523,7 +557,7 @@ into new ``Tag`` objects and added to the ``tags`` property of the ``Task`` obje
  }
 
  If you have a ``OneToMany`` relationship, then the workaround is similar,
- except that you can simply call ``setTask`` from inside ``setTags``.
+ except that you can simply call ``setTask`` from inside ``addTag``.
 
 .. _cookbook-form-collections-remove:
 
@@ -538,20 +572,31 @@ Start by adding the ``allow_delete`` option in the form Type::
  // src/Acme/TaskBundle/Form/Type/TaskType.php
 
  // ...
- use Symfony\Component\Form\FormBuilderInterface;
-
  public function buildForm(FormBuilderInterface $builder, array $options)
  {
- $builder->add('description');
+ // ...
 
  $builder->add('tags', 'collection', array(
- 'type' => new TagType(),
- 'allow_add' => true,
+ // ...
  'allow_delete' => true,
- 'by_reference' => false,
  ));
  }
 
+Now, you need to put some code into the ``removeTag`` method of ``Task``::
+
+ // src/Acme/TaskBundle/Entity/Task.php
+
+ // ...
+ class Task
+ {
+ // ...
+
+ public function removeTag($tag)
+ {
+ $this->tags->removeElement($tag);
+ }
+ }
+
 Templates Modifications
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -604,11 +649,11 @@ the relationship between the removed ``Tag`` and ``Task`` object.
 .. sidebar:: Doctrine: Ensuring the database persistence
 
  When removing objects in this way, you may need to do a little bit more
- work to ensure that the relationship between the Task and the removed Tag
- is properly removed.
+ work to ensure that the relationship between the ``Task`` and the removed
+ ``Tag`` is properly removed.
 
  In Doctrine, you have two side of the relationship: the owning side and the
- inverse side. Normally in this case you'll have a ManyToMany relation
+ inverse side. Normally in this case you'll have a ``ManyToMany`` relation
  and the deleted tags will disappear and persist correctly (adding new
  tags also works effortlessly).
 
@@ -623,7 +668,6 @@ the relationship between the removed ``Tag`` and ``Task`` object.
  // src/Acme/TaskBundle/Controller/TaskController.php
 
  // ...
-
  public function editAction($id, Request $request)
  {
  $em = $this->getDoctrine()->getManager();