Permalink
Browse files

minor #3445 [Reference][Form Types] Add missing (but existing) option…

…s to "form" type (bicpi)

This PR was merged into the 2.3 branch.

Discussion
----------

[Reference][Form Types] Add missing (but existing) options to "form" type

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.3+
| Fixed tickets | #3410

* The removed link to `/cookbook/form/inherit_data_option` for the `inherit_data` option is contained in the existing and now referenced `options/inherit_data.rst.inc`.
* Fixed some formatting issues.
* I've tweaked the `empty_data` description to be a bit more generic as it was focused on the `choice` field only.

Commits
-------

dc22276 [Reference][Form Types] Add missing (but existing) form options to "form" type
  • Loading branch information...
weaverryan committed Jan 21, 2014
2 parents ea5816f + dc22276 commit 65efcc4f64365acf5895597bb32e9b611f9bbfcd
@@ -45,8 +45,17 @@ on all fields.
.. include:: /reference/forms/types/options/max_length.rst.inc
inherit_data
------------
.. include:: /reference/forms/types/options/empty_data.rst.inc
.. include:: /reference/forms/types/options/by_reference.rst.inc
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
.. include:: /reference/forms/types/options/inherit_data.rst.inc
.. include:: /reference/forms/types/options/error_mapping.rst.inc
.. include:: /reference/forms/types/options/invalid_message.rst.inc
See :doc:`/cookbook/form/inherit_data_option`.
.. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
@@ -1,3 +1,3 @@
If true, any errors for this field will be passed to the parent field
or form. For example, if set to true on a normal field, any errors for
If ``true``, any errors for this field will be passed to the parent field
or form. For example, if set to ``true`` on a normal field, any errors for
that field will be attached to the main form, not to the specific field.
@@ -3,8 +3,8 @@ by_reference
**type**: ``Boolean`` **default**: ``true``
In most cases, if you have a ``name`` field, then you expect ``setName``
to be called on the underlying object. In some cases, however, ``setName``
In most cases, if you have a ``name`` field, then you expect ``setName()``
to be called on the underlying object. In some cases, however, ``setName()``
may *not* be called. Setting ``by_reference`` ensures that the setter is
called in all cases.
@@ -20,13 +20,13 @@ To explain this further, here's a simple example::
)
If ``by_reference`` is true, the following takes place behind the scenes
when you call ``submit`` (or ``handleRequest``) on the form::
when you call ``submit()`` (or ``handleRequest()``) on the form::
$article->setTitle('...');
$article->getAuthor()->setName('...');
$article->getAuthor()->setEmail('...');
Notice that ``setAuthor`` is not called. The author is modified by reference.
Notice that ``setAuthor()`` is not called. The author is modified by reference.
If you set ``by_reference`` to false, submitting looks like this::
@@ -42,4 +42,4 @@ call the setter on the parent object.
Similarly, if you're using the :doc:`collection</reference/forms/types/collection>`
form type where your underlying collection data is an object (like with Doctrine's
``ArrayCollection``), then ``by_reference`` must be set to ``false`` if you
need the setter (e.g. ``setAuthors``) to be called.
need the setter (e.g. ``setAuthors()``) to be called.
@@ -1,20 +1,23 @@
empty_data
~~~~~~~~~~
**type**: ``mixed`` **default**: ``array()`` if ``multiple`` or ``expanded``, ``''`` otherwise
**type**: ``mixed`` **default**: depends on other field options, see below
This option determines what value the field will return when the ``empty_value``
choice is selected.
This option determines what value the field will return when the submitted
value is empty. This may happen when the ``empty_value`` choice in a
``choice`` field is selected or when an ``input`` field of some type is not
required and left empty by the user.
The true default value of this option depends on the field options:
The true default value of this option depends on other field options:
* If ``data_class`` is set and ``required`` is ``true``, then ``new $data_class()``;
* If ``data_class`` is set and ``required`` is ``false``, then ``null``;
* If ``data_class`` is not set and ``compound`` is ``true``, then ``array()``;
* If ``data_class`` is not set and ``compound`` is ``false``, then ``null``.
* If ``data_class`` is set and ``required`` is ``true``, then ``new $data_class()``;
* If ``data_class`` is set and ``required`` is ``false``, then ``null``;
* If ``data_class`` is not set and ``compound`` is ``true``, then ``array()``;
* If ``data_class`` is not set and ``compound`` is ``false``, then ``''`` (empty string).
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:
But you can customize this to your needs. For example, if you want the
``gender`` choice field to be explicitly set to ``null`` when no value is
selected, you can do it like this:
.. code-block:: php
@@ -27,14 +27,14 @@ field so that it displays above it::
Here are the rules for the left and the right side of the mapping:
* The left side contains property paths.
* The left side contains property paths;
* If the violation is generated on a property or method of a class, its path
is simply "propertyName".
is simply ``propertyName``;
* If the violation is generated on an entry of an ``array`` or ``ArrayAccess``
object, the property path is ``[indexName]``.
object, the property path is ``[indexName]``;
* You can construct nested property paths by concatenating them, separating
properties by dots. For example: ``addresses[work].matchingCityAndZipCode``
properties by dots. For example: ``addresses[work].matchingCityAndZipCode``;
* The left side of the error mapping also accepts a dot ``.``, which refers
to the field itself. That means that any error added to the field is added
to the given nested field instead.
to the given nested field instead;
* The right side contains simply the names of fields in the form.

0 comments on commit 65efcc4

Please sign in to comment.