Merge branch '4.4' into 5.1

* 4.4:
  addressed issue #11786
  Add array example on ChoiceType choice_attr option
  [#14340] Some minor textual changes
  [Collection forms] Make javascript generic
  Updating the Installer Related Instructions

Author: wouterj

components/serializer.rst

@@ -815,8 +815,20 @@ The ``XmlEncoder`` will encode this object like that::
         <bar>1</bar>
     </response>
 
-Be aware that this encoder will consider keys beginning with ``@`` as attributes, and will use
-the key  ``#comment`` for encoding XML comments::
+The special ``#`` key can be used to define the data of a node::
+
+    ['foo' => ['@bar' => 'value', '#' => 'baz']];
+
+    // is encoded as follows:
+    // <?xml version="1.0"?>
+    // <response>
+    //     <foo bar="value">
+    //        baz
+    //     </foo>
+    // </response>
+
+Furthermore, keys beginning with ``@`` will be considered attributes, and
+the key  ``#comment`` can be used for encoding XML comments::
 
     $encoder = new XmlEncoder();
     $encoder->encode([
@@ -842,6 +854,34 @@ always as a collection.
     changed with the optional ``$encoderIgnoredNodeTypes`` argument of the
     ``XmlEncoder`` class constructor.
 
+The ``XmlEncoder`` Context Options
+..................................
+
+The ``encode()`` method defines a third optional parameter called ``context``
+which defines the configuration options for the XmlEncoder an associative array::
+
+    $xmlEncoder->encode($array, 'xml', $context);
+
+These are the options available:
+
+``xml_format_output``
+    If set to true, formats the generated XML with line breaks and indentation.
+
+``xml_version``
+    Sets the XML version attribute (default: ``1.1``).
+
+``xml_encoding``
+    Sets the XML encoding attribute (default: ``utf-8``).
+
+``xml_standalone``
+    Adds standalone attribute in the generated XML (default: ``true``).
+
+``xml_root_node_name``
+    Sets the root node name (default: ``response``).
+
+``remove_empty_tags``
+    If set to true, removes all empty tags in the generated XML (default: ``false``).
+
 The ``YamlEncoder``
 ~~~~~~~~~~~~~~~~~~~
 
@@ -1153,72 +1193,6 @@ you indicate that you're expecting an array instead of a single object::
     $data = ...; // The serialized data from the previous example
     $persons = $serializer->deserialize($data, 'Acme\Person[]', 'json');
 
-The ``XmlEncoder``
-------------------
-
-This encoder transforms arrays into XML and vice versa. For example, take an
-object normalized as following::
-
-    ['foo' => [1, 2], 'bar' => true];
-
-The ``XmlEncoder`` encodes this object as follows:
-
-.. code-block:: xml
-
-    <?xml version="1.0"?>
-    <response>
-        <foo>1</foo>
-        <foo>2</foo>
-        <bar>1</bar>
-    </response>
-
-The array keys beginning with ``@`` are considered XML attributes::
-
-    ['foo' => ['@bar' => 'value']];
-
-    // is encoded as follows:
-    // <?xml version="1.0"?>
-    // <response>
-    //     <foo bar="value"/>
-    // </response>
-
-Use the special ``#`` key to define the data of a node::
-
-    ['foo' => ['@bar' => 'value', '#' => 'baz']];
-
-    // is encoded as follows:
-    // <?xml version="1.0"?>
-    // <response>
-    //     <foo bar="value">baz</foo>
-    // </response>
-
-Context
-~~~~~~~
-
-The ``encode()`` method defines a third optional parameter called ``context``
-which defines the configuration options for the XmlEncoder an associative array::
-
-    $xmlEncoder->encode($array, 'xml', $context);
-
-These are the options available:
-
-``xml_format_output``
-    If set to true, formats the generated XML with line breaks and indentation.
-
-``xml_version``
-    Sets the XML version attribute (default: ``1.1``).
-
-``xml_encoding``
-    Sets the XML encoding attribute (default: ``utf-8``).
-
-``xml_standalone``
-    Adds standalone attribute in the generated XML (default: ``true``).
-
-``xml_root_node_name``
-    Sets the root node name (default: ``response``).
-
-``remove_empty_tags``
-    If set to true, removes all empty tags in the generated XML (default: ``false``).
 
 The ``CsvEncoder``
 ------------------

form/form_collections.rst

@@ -242,7 +242,13 @@ the following ``data-prototype`` attribute to the existing ``<ul>`` in your temp
 
 .. code-block:: html+twig
 
-    <ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e('html_attr') }}">
+    <ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e('html_attr') }}"></ul>
+
+Now add a button just next to the ``<ul>`` to dynamically add a new tag
+
+.. code-block:: html+twig
+
+    <button type="button" class="add_item_link" data-collection-holder-class="tags">Add a tag</button>
 
 On the rendered page, the result will look something like this:
 
@@ -274,38 +280,27 @@ On the rendered page, the result will look something like this:
     and you need to adjust the following JavaScript accordingly.
 
 The goal of this section will be to use JavaScript to read this attribute
-and dynamically add new tag forms when the user clicks a "Add a tag" link.
+and dynamically add new tag forms when the user clicks the "Add a tag" button.
 This example uses jQuery and assumes you have it included somewhere on your page.
 
-Add a ``script`` tag somewhere on your page so you can start writing some JavaScript.
-
-First, add a link to the bottom of the "tags" list via JavaScript. Second,
-bind to the "click" event of that link so you can add a new tag form (``addTagForm()``
-will be show next):
+Add a ``script`` tag somewhere on your page so you can start writing some
+JavaScript. In this script, bind to the "click" event of the "Add a tag"
+button so you can add a new tag form (``addFormToCollection()`` will be show next):
 
 .. code-block:: javascript
 
-    var $collectionHolder;
-
-    // setup an "add a tag" link
-    var $addTagButton = $('<button type="button" class="add_tag_link">Add a tag</button>');
-    var $newLinkLi = $('<li></li>').append($addTagButton);
-
     jQuery(document).ready(function() {
         // Get the ul that holds the collection of tags
-        $collectionHolder = $('ul.tags');
-
-        // add the "add a tag" anchor and li to the tags ul
-        $collectionHolder.append($newLinkLi);
-
+        var $tagsCollectionHolder = $('ul.tags');
         // count the current form inputs we have (e.g. 2), use that as the new
         // index when inserting a new item (e.g. 2)
-        $collectionHolder.data('index', $collectionHolder.find('input').length);
+        $tagsCollectionHolder.data('index', $tagsCollectionHolder.find('input').length);
 
-        $addTagButton.on('click', function(e) {
+        $('body').on('click', '.add_item_link', function(e) {
+            var $collectionHolderClass = $(e.currentTarget).data('collectionHolderClass');
             // add a new tag form (see next code block)
-            addTagForm($collectionHolder, $newLinkLi);
-        });
+            addFormToCollection($collectionHolderClass);
+        })
     });
 
 The ``addTagForm()`` function's job will be to use the ``data-prototype`` attribute
@@ -319,7 +314,10 @@ one example:
 
 .. code-block:: javascript
 
-    function addTagForm($collectionHolder, $newLinkLi) {
+    function addFormToCollection($collectionHolderClass) {
+        // Get the ul that holds the collection of tags
+        var $collectionHolder = $('.' + $collectionHolderClass);
+
         // Get the data-prototype explained earlier
         var prototype = $collectionHolder.data('prototype');
 
@@ -341,7 +339,8 @@ one example:
 
         // Display the form in the page in an li, before the "Add a tag" link li
         var $newFormLi = $('<li></li>').append(newForm);
-        $newLinkLi.before($newFormLi);
+        // Add the new form at the end of the list
+        $collectionHolder.append($newFormLi)
     }
 
 .. note::

reference/forms/types/options/choice_attr.rst.inc

@@ -13,6 +13,20 @@ If an array, the keys of the ``choices`` array must be used as keys::
     use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
     // ...
 
+    $builder->add('fruits', ChoiceType::class, [
+        'choices' => [
+            'Apple' => 1,
+            'Banana' => 2,
+            'Durian' => 3,
+        ],
+        'choice_attr' => [
+            'Apple' => ['data-color' => 'Red'],
+            'Banana' => ['data-color' => 'Yellow'],
+            'Durian' => ['data-color' => 'Green'],
+        ],
+    ]);
+
+    // or use a callable
     $builder->add('attending', ChoiceType::class, [
         'choices' => [
             'Yes' => true,