From 77a5fbb6bbd1d4d0a8f88ff4ec8de22efcb82486 Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Fri, 12 Feb 2016 07:28:54 +0100 Subject: [PATCH 1/5] explicit differences between 'data' & 'empty_data' in FormType --- reference/forms/types/options/data.rst.inc | 14 +++++++------- reference/forms/types/options/empty_data.rst.inc | 9 +++++---- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc index c9bf76424c5..27bf52d3cdf 100644 --- a/reference/forms/types/options/data.rst.inc +++ b/reference/forms/types/options/data.rst.inc @@ -1,12 +1,12 @@ data ~~~~ -**type**: ``mixed`` **default**: Defaults to field of the underlying object (if there is one) +**type**: ``mixed`` **default**: Defaults to field of the underlying structure. -When you create a form, each field initially displays the value of the -corresponding property of the form's domain object (if an object is bound -to the form). If you want to override the initial value for the form or -just an individual field, you can set it in the data option:: +When you attach a form type to a form, it becomes a field that initially maps +the value of the corresponding property or key of the form's domain data. If +you want to override the initial value which will be rendered in the view for +the form or any field, you can set it in the data option:: $builder->add('token', 'hidden', array( 'data' => 'abcdef', @@ -15,5 +15,5 @@ just an individual field, you can set it in the data option:: .. note:: The default values for form fields are taken directly from the underlying - data structure (e.g. an entity or an array). The ``data`` option overrides - this default value. + data structure matching the field name with a property of an object or a + key of an array. The ``data`` option overrides this default value. diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index f856d8d73fe..79955fd9a23 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -10,11 +10,12 @@ empty_data DEFAULT_PLACEHOLDER This option determines what value the field will return when the submitted -value is empty. +value is empty. It does not set an initial value if none is provided when +the form is rendered in a view (see `Data` or `Placeholder` options). -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:: +It helps you handling form submission and 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:: $builder->add('gender', 'choice', array( 'choices' => array( From 8fa74d9200c0b2ea2c1e142bd87689d0f0c06b11 Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Fri, 12 Feb 2016 08:08:38 +0100 Subject: [PATCH 2/5] fix typo --- reference/forms/types/options/empty_data.rst.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index 79955fd9a23..deaa885cef6 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -11,7 +11,7 @@ DEFAULT_PLACEHOLDER This option determines what value the field will return when the submitted value is empty. It does not set an initial value if none is provided when -the form is rendered in a view (see `Data` or `Placeholder` options). +the form is rendered in a view (see ``data`` or ``placeholder`` options). It helps you handling form submission and you can customize this to your needs. For example, if you want the ``gender`` choice field to be explicitly set to ``null`` From f5f9c1e370c6aee196b2d0eab505805a8a1e32e7 Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Mon, 25 Apr 2016 16:50:49 +0200 Subject: [PATCH 3/5] improved accuracy --- reference/forms/types/options/data.rst.inc | 7 +++++-- .../forms/types/options/empty_data.rst.inc | 19 +++++++++++++++---- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc index 27bf52d3cdf..fe825c1273e 100644 --- a/reference/forms/types/options/data.rst.inc +++ b/reference/forms/types/options/data.rst.inc @@ -6,14 +6,17 @@ data When you attach a form type to a form, it becomes a field that initially maps the value of the corresponding property or key of the form's domain data. If you want to override the initial value which will be rendered in the view for -the form or any field, you can set it in the data option:: +the form or any nested field, you can set it in the data option:: $builder->add('token', 'hidden', array( 'data' => 'abcdef', )); + // Is the same as + $resolver->setDefault('data' => array('token' => 'abcdef')); + .. note:: The default values for form fields are taken directly from the underlying - data structure matching the field name with a property of an object or a + data structure matching the field's name with a property of an object or a key of an array. The ``data`` option overrides this default value. diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index deaa885cef6..162b11ee4f4 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -1,7 +1,7 @@ empty_data ~~~~~~~~~~ -**type**: ``mixed`` +**type**: ``string`` or ``array`` when the form is compound .. This file should only be included with start-after or end-before that's set to this placeholder value. Its purpose is to let us include only @@ -14,19 +14,30 @@ value is empty. It does not set an initial value if none is provided when the form is rendered in a view (see ``data`` or ``placeholder`` options). It helps you handling form submission and you can customize this to your needs. -For example, if you want the ``gender`` choice field to be explicitly set to ``null`` +For example, if you want the ``gender`` choice field to be explicitly set to ``Male`` when no value is selected, you can do it like this:: $builder->add('gender', 'choice', array( 'choices' => array( 'm' => 'Male', - 'f' => 'Female' + 'f' => 'Female', ), 'required' => false, 'empty_value' => 'Choose your gender', - 'empty_data' => null + 'empty_data' => 'm', )); +If a form is compound, you can set ``empty_data`` as an array with fields names +as keys and submitted values as string values (or arrays if nested fields are +also compound). + +.. caution:: + + In this example, the choice field is not set as ``multiple``. If it was + ``empty_data`` option should be an array of submitted string values:: + + 'empty_data' => array('m'), + .. note:: If you want to set the ``empty_data`` option for your entire form class, From 60c88930605a0ab261e0c5bfbee7b99dc814ceeb Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Sat, 21 May 2016 12:26:07 +0200 Subject: [PATCH 4/5] Addressed @stof's comment --- reference/forms/types/options/data.rst.inc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc index fe825c1273e..5ada8c077f9 100644 --- a/reference/forms/types/options/data.rst.inc +++ b/reference/forms/types/options/data.rst.inc @@ -20,3 +20,5 @@ the form or any nested field, you can set it in the data option:: The default values for form fields are taken directly from the underlying data structure matching the field's name with a property of an object or a key of an array. The ``data`` option overrides this default value. + It means that when the data passed to the form is an object you want to + edit, the `data` option will also override the value already set. From 133a77c3f832e4ccef3aa91a89b4e72207a333fc Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Sat, 21 May 2016 13:15:44 +0200 Subject: [PATCH 5/5] Updated the example add added a caution --- .../forms/types/options/empty_data.rst.inc | 32 ++++++++----------- 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index 162b11ee4f4..72480144e95 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -10,35 +10,31 @@ empty_data DEFAULT_PLACEHOLDER This option determines what value the field will return when the submitted -value is empty. It does not set an initial value if none is provided when -the form is rendered in a view (see ``data`` or ``placeholder`` options). +value is empty (or missing). It does not set an initial value if none is +provided when the form is rendered in a view (see ``data`` or ``placeholder`` +options). It helps you handling form submission and you can customize this to your needs. -For example, if you want the ``gender`` choice field to be explicitly set to ``Male`` +For example, if you want the ``name`` field to be explicitly set to ``John Doe`` when no value is selected, you can do it like this:: - $builder->add('gender', 'choice', array( - 'choices' => array( - 'm' => 'Male', - 'f' => 'Female', - ), + $builder->add('name', null, array( 'required' => false, - 'empty_value' => 'Choose your gender', - 'empty_data' => 'm', + 'empty_data' => 'John Doe', )); -If a form is compound, you can set ``empty_data`` as an array with fields names +If a form is compound, you can set ``empty_data`` as an array with field names as keys and submitted values as string values (or arrays if nested fields are also compound). -.. caution:: - - In this example, the choice field is not set as ``multiple``. If it was - ``empty_data`` option should be an array of submitted string values:: - - 'empty_data' => array('m'), - .. note:: If you want to set the ``empty_data`` option for your entire form class, see the cookbook article :doc:`/cookbook/form/use_empty_data`. + +.. caution:: + + When using `empty_data` as an empty string, the form will always return + ``null``. If you need to get an empty string to be returned, you should + use a data transformer, see the cookbook article + :doc:`cookbook/form/data_transformers`.