finishing docs

Author: weaverryan

src/LiveComponent/src/Resources/doc/index.rst

@@ -1073,10 +1073,10 @@ section above) is to add:
 Using Actions to Change your Form: CollectionType
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Have you ever used Symfony's `CollectionType`_? If you want to be able
-to dynamically add or remove embedded forms, you need to write some
-JavaScript. Well, that's true, unless you render your form inside a
-live component.
+Symfony's `CollectionType`_ can be used to embed a collection of
+embedded forms including allowing the user to dynamically add or remove
+them. Live components can accomplish make this all possible while
+writing zero JavaScript.
 
 For example, imagine a "Blog Post" form with an embedded "Comment" forms
 via the ``CollectionType``::
@@ -1100,6 +1100,7 @@ via the ``CollectionType``::
                     'entry_type' => CommentFormType::class,
                     'allow_add' => true,
                     'allow_delete' => true,
+                    'by_reference' => false,
                 ])
             ;
         }
@@ -1144,14 +1145,76 @@ Now, create a Twig component to render the form::
             // "formValues" represents the current data in the form
             // this modifies the form to add an extra comment
             // the result: another embedded comment form!
+            // change "comments" to the name of the field that uses CollectionType
             $this->formValues['comments'][] = [];
         }
+
+        #[LiveAction]
+        public function removeComment(#[LiveArg] int $index)
+        {
+            unset($this->formValues['comments'][$index]);
+        }
     }
 
-Finally, render the form in the component's template like normal, but
-with a live action that points to ``addComment()``:
+The template for this component has two jobs: (1) render the form
+like normal and (2) include links that trigger the ``addComment()``
+and ``removeComment()`` actions:
+
+.. code-block:: twig
+
+    <div{{ attributes }}>
+        {{ form_start(this.form) }}
+            {{ form_row(this.form.title) }}
+
+            <h3>Comments:</h3>
+            {% for key, commentForm in this.form.comments %}
+                <button
+                    data-action="live#action"
+                    data-action-name="removeComment(index={{ key }})"
+                    type="button"
+                >X</button>
+
+                {{ form_widget(commentForm) }}
+            {% endfor %}
+            </div>
+
+            {# avoid an extra label for this field #}
+            {% do this.form.comments.setRendered %}
+
+            <button
+                data-action="live#action"
+                data-action-name="addComment"
+                type="button"
+            >+ Add Comment</button>
+
+            <button type="submit" >Save</button>
+        {{ form_end(this.form) }}
+    </div>
+
+Done! Behind the scenes, it works like this:
+
+A) When the user clicks "+ Add Comment", an Ajax request is sent that
+triggers the ``addComment()`` action.
+
+B) ``addComment()`` modifies ``formValues``, which you can think of as
+the raw "POST" data of your form.
+
+C) Still during the Ajax request, the ``formValues`` are "submitted"
+into your form. The new key inside of ``$this->formValues['comments']``
+tells the ``CollectionType`` that you want a new, embedded form.
+
+D) The form is rendered - now with another embedded form! - and the
+Ajax call returns with the form (with the new embedded form).
+
+When the user clicks ``removeComment()``, a similar process happens.
+
+.. note::
 
-TODO
+    When working with Doctrine entities, add ``orphanRemoval: true``
+    and ``cascade={"persist"}`` to your ``OneToMany`` relationship.
+    In this example, these options would be added to the ``OneToMany``
+    attribute above the ``Post.comments`` property. These help new
+    items save and deletes any items whose embedded forms are removed.
 
 Modifying Embedded Properties with the "exposed" Option
 -------------------------------------------------------
@@ -1636,3 +1699,4 @@ bound to Symfony's BC policy for the moment.
 .. _`dependent form fields`: https://symfony.com/doc/current/form/dynamic_form_modification.html#dynamic-generation-for-submitted-forms
 .. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
 .. _`Component attributes`: https://symfony.com/bundles/ux-twig-component/current/index.html#component-attributes
+.. _`CollectionType`: https://symfony.com/doc/current/form/form_collections.html