Merge branch '2.4'

Author: weaverryan

reference/forms/types/collection.rst

@@ -26,6 +26,7 @@ forms, which is useful when creating forms that expose one-to-many relationships
 |             | - `error_mapping`_                                                          |
 |             | - `by_reference`_                                                           |
 |             | - `empty_data`_                                                             |
+|             | - `required`_                                                               |
 |             | - `mapped`_                                                                 |
 +-------------+-----------------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                                   |
@@ -359,4 +360,6 @@ error_bubbling
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
 
+.. include:: /reference/forms/types/options/required.rst.inc
+
 .. include:: /reference/forms/types/options/mapped.rst.inc

reference/forms/types/entity.rst

@@ -13,6 +13,7 @@ objects from the database.
 | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`)     |
 +-------------+------------------------------------------------------------------+
 | Options     | - `class`_                                                       |
+|             | - `data_class`_                                                  |
 |             | - `property`_                                                    |
 |             | - `group_by`_                                                    |
 |             | - `query_builder`_                                               |
@@ -105,6 +106,8 @@ The class of your entity (e.g. ``AcmeStoreBundle:Category``). This can be
 a fully-qualified class name (e.g. ``Acme\StoreBundle\Entity\Category``)
 or the short alias name (as shown prior).
 
+.. include:: /reference/forms/types/options/data_class.rst.inc
+
 property
 ~~~~~~~~
 

reference/forms/types/form.rst

@@ -13,6 +13,8 @@ on all fields.
 
 .. include:: /reference/forms/types/options/data.rst.inc
 
+.. include:: /reference/forms/types/options/data_class.rst.inc
+
 .. include:: /reference/forms/types/options/required.rst.inc
 
 .. include:: /reference/forms/types/options/label.rst.inc

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

@@ -0,0 +1,14 @@
+.. versionadded:: 2.4
+    The ``data_class`` option was introduced in Symfony 2.4.
+
+data_class
+~~~~~~~~~~
+
+**type**: ``string``
+
+This option is used to set the appropriate data mapper to be used by the form,
+so you can use it for any form field type which requires an object.
+
+    $builder->add('media', 'sonata_media_type', array(
+        'data_class' => 'Acme\DemoBundle\Entity\Media',
+    ));

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

@@ -8,17 +8,13 @@ choice is selected.
 
 The true default value of this option depends on the field options:
 
-* If ``compound`` is ``true`` and ``data_class`` is set, then ``new $data_class()``;
-* If ``compound`` is ``true`` and no ``data_class`` is set, then ``array()``;
-* If ``compound`` is ``false``, then ``null``.
+* If ``data_class`` is set and  ``required`` is  ``true``, then ``null``;
+* If ``data_class`` is set and  ``required`` is  ``false``, then ``new $data_class()``;
+* If ``data_class`` is not set and  ``compound`` is  ``true``, then ``array()``;
+* If ``data_class`` is not set and  ``compound`` is  ``false``, then ``null``.
 
-.. tip::
-
-    The ``compound`` option is set to ``true`` when the field actually represents
-    a collection of fields (e.g. a form of fields).
-
-For example, if you want the ``gender`` field to be set to ``null`` when no
-value is selected, you can do it like this:
+But you can customize this to your needs. For example, if you want the ``gender`` field to be
+explicitly set to ``null`` when no value is selected, you can do it like this:
 
 .. code-block:: php
 

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

@@ -10,4 +10,9 @@ This is superficial and independent from validation. At best, if you let Symfony
 guess your field type, then the value of this option will be guessed from
 your validation information.
 
-.. _`HTML5 required attribute`: http://diveintohtml5.info/forms.html
+.. note::
+
+    The required option does also affect the way how empty data of your form is
+    being handled. For further details check the `empty_data`_ option.
+
+.. _`HTML5 required attribute`: http://diveintohtml5.info/forms.html