From 87b354271b0f2b6fb01d240a684cb9555ac982ea Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Fri, 12 Feb 2016 07:28:54 +0100 Subject: [PATCH 01/10] 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 031167b2526..afaa8fe41b6 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 67c93b676f2f5f1ab02381a35e6417be5df52ceb Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Fri, 12 Feb 2016 08:08:38 +0100 Subject: [PATCH 02/10] 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 afaa8fe41b6..c9146c346c9 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 242941a9c4abd20cbd3ff6faa144cb8ad3f47118 Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Mon, 25 Apr 2016 16:50:49 +0200 Subject: [PATCH 03/10] 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 c9146c346c9..4ce096e2dad 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, 'placeholder' => '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 4fd2d965e59fdde06c97b67ffec87f515c1ce3cd Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Sat, 21 May 2016 12:26:07 +0200 Subject: [PATCH 04/10] 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 5f3813dec87ffe2010676efa9513a8d45813ee1f Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Sat, 21 May 2016 13:15:44 +0200 Subject: [PATCH 05/10] Updated the example add added a caution --- .../forms/types/options/empty_data.rst.inc | 31 ++++++++----------- 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index 4ce096e2dad..39e63a8bd24 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -10,35 +10,30 @@ 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, - 'placeholder' => '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 :doc:`/form/use_empty_data` article. + +.. 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 :doc:`/form/data_transformers` article. From 188f0abb078e591320473edb136341f8d789b5fe Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 15 Apr 2017 15:47:08 +0200 Subject: [PATCH 06/10] Tried to write the important points more explicitly --- reference/forms/types/options/data.rst.inc | 23 ++++++++---------- .../forms/types/options/empty_data.rst.inc | 24 +++++++++++-------- 2 files changed, 24 insertions(+), 23 deletions(-) diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc index 5ada8c077f9..1b8578ca352 100644 --- a/reference/forms/types/options/data.rst.inc +++ b/reference/forms/types/options/data.rst.inc @@ -3,22 +3,19 @@ data **type**: ``mixed`` **default**: Defaults to field of the underlying structure. -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 nested field, you can set it in the data option:: +When you create a form, each field initially displays the value of the +corresponding property of the form's domain data (e.g. if you bind an object to +the form). If you want to override this initial value for the form or +an individual 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:: +.. caution:: - 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. + The ``data`` option *always* overrides the value taken from the domain data + (object) when rendering. This means the object value is also overriden when + the form edits an already persisted object, causing it to loose it's + persisted value when the form is submitted. diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index 39e63a8bd24..b32e25372e6 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -9,20 +9,23 @@ empty_data DEFAULT_PLACEHOLDER -This option determines what value the field will return when the submitted +This option determines what value the field will *return* when the submitted 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). +provided when the form is rendered in a view. -It helps you handling form submission and you can customize this to your needs. -For example, if you want the ``name`` field to be explicitly set to ``John Doe`` +This means it helps you handling form submission with blank fields. 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('name', null, array( - 'required' => false, - 'empty_data' => 'John Doe', + 'required' => false, + 'empty_data' => 'John Doe', )); +This will still render an empty text box, but upon submission the ``John Doe`` +value will be set. Use the ``data`` or ``placeholder`` options to show this +initial value in the rendered form. + 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). @@ -34,6 +37,7 @@ also compound). .. 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 :doc:`/form/data_transformers` article. + :doc:`Form data transformers ` will still be + applied to the ``empty_data`` value. This means that an empty string will + be casted to ``null``. Use a custom data transformer if you explicitly want + to return the empty string. From d552ea36e201ba2d6055f267bd94fa82cc4704fd Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 15 Apr 2017 15:53:06 +0200 Subject: [PATCH 07/10] Readd mixed type for empty_data, it can be string, array or object --- 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 b32e25372e6..194cebf8e94 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**: ``string`` or ``array`` when the form is compound +**type**: ``mixed`` .. 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 From f37548947d5ec8a54d81e586e147616d225a65cf Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 15 Apr 2017 16:09:38 +0200 Subject: [PATCH 08/10] Better explain empty_data values --- form/use_empty_data.rst | 9 ++++++++- reference/forms/types/options/empty_data.rst.inc | 6 +++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/form/use_empty_data.rst b/form/use_empty_data.rst index 342341e5b7a..0bc1068ed90 100644 --- a/form/use_empty_data.rst +++ b/form/use_empty_data.rst @@ -27,7 +27,14 @@ a ``data_class`` option for your form class, it will default to a new instance of that class. That instance will be created by calling the constructor with no arguments. -If you want to override this default behavior, there are two ways to do this. +If you want to override this default behavior, there are two ways to do this: + +* `Option 1: Instantiate a new Class`_ +* `Option 2: Provide a Closure`_ + +If you didn't set the ``data_class`` option, you can pass the initial data as +string or pass an array of strings (where the key matches the field name) when +the form type is compound. Option 1: Instantiate a new Class --------------------------------- diff --git a/reference/forms/types/options/empty_data.rst.inc b/reference/forms/types/options/empty_data.rst.inc index 194cebf8e94..9758fab2ede 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -26,9 +26,9 @@ This will still render an empty text box, but upon submission the ``John Doe`` value will be set. Use the ``data`` or ``placeholder`` options to show this initial value in the rendered form. -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). +If a form is compound, you can set ``empty_data`` as an array, object or +closure. See the :doc:`/form/use_empty_data` article for more details about +these options. .. note:: From df9b8785697a5ce314b2c20894f9d781d6708cb1 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 May 2017 09:24:40 +0200 Subject: [PATCH 09/10] Fixed a minor typo --- reference/forms/types/options/data.rst.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc index 1b8578ca352..3cf3504851a 100644 --- a/reference/forms/types/options/data.rst.inc +++ b/reference/forms/types/options/data.rst.inc @@ -17,5 +17,5 @@ an individual field, you can set it in the data option:: The ``data`` option *always* overrides the value taken from the domain data (object) when rendering. This means the object value is also overriden when - the form edits an already persisted object, causing it to loose it's + the form edits an already persisted object, causing it to lose it's persisted value when the form is submitted. From 64e3984950e431e6e6b9bd4a6fc1f87690e3ddad Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 May 2017 09:25:07 +0200 Subject: [PATCH 10/10] Fixed a minor 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 9758fab2ede..bec4fdc3cd5 100644 --- a/reference/forms/types/options/empty_data.rst.inc +++ b/reference/forms/types/options/empty_data.rst.inc @@ -39,5 +39,5 @@ these options. :doc:`Form data transformers ` will still be applied to the ``empty_data`` value. This means that an empty string will - be casted to ``null``. Use a custom data transformer if you explicitly want + be cast to ``null``. Use a custom data transformer if you explicitly want to return the empty string.