8000 feature #4486 Renamed empty_value to placeholder (WouterJ) · symfony/symfony-docs@48a5af3 · GitHub
[go: up one dir, main page]
Skip to content 8000

Commit 48a5af3

Browse files
weaverryanweaverryan
committed
feature #4486 Renamed empty_value to placeholder (WouterJ)
This PR was merged into the 2.6 branch. Discussion ---------- Renamed empty_value to placeholder | Q | A | --- | --- | Doc fix? | no | New docs? | yes (symfony/symfony#12003) | Applies to | 2.6+ | Fixed tickets | #4261 Commits ------- 54c44ea Renamed empty_value to placeholder
2 parents 3ecfcaf + 54c44ea commit 48a5af3

16 files changed

+55
-39
lines changed

‎cookbook/form/create_custom_field_type.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ new instance of the type in one of your forms::
240240
public function buildForm(FormBuilderInterface $builder, array $options)
241241
{
242242
$builder->add('gender_code', new GenderType(), array(
243-
'empty_value' => 'Choose a gender',
243+
'placeholder' => 'Choose a gender',
244244
));
245245
}
246246
}
@@ -249,6 +249,10 @@ But this only works because the ``GenderType()`` is very simple. What if
249249
the gender codes were stored in configuration or in a database? The next
250250
section explains how more complex field types solve this problem.
251251

252+
.. versionadded:: 2.6
253+
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
254+
``empty_value``, which is available prior to 2.6.
255+
252256
.. _form-cookbook-form-field-service:
253257

254258
Creating your Field Type as a Service
@@ -378,7 +382,7 @@ configuration, using the field is now much easier::
378382
public function buildForm(FormBuilderInterface $builder, array $options)
379383
{
380384
$builder->add('gender_code', 'gender', array(
381-
'empty_value' => 'Choose a gender',
385+
'placeholder' => 'Choose a gender',
382386
));
383387
}
384388
}

‎cookbook/form/dynamic_form_modification.rst

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -470,7 +470,7 @@ sport like this::
470470
$builder
471471
->add('sport', 'entity', array(
472472
'class' => 'AcmeDemoBundle:Sport',
473-
'empty_value' => '',
473+
'placeholder' => '',
474474
))
475475
;
476476

@@ -487,7 +487,7 @@ sport like this::
487487

488488
$form->add('position', 'entity', array(
489489
'class' => 'AcmeDemoBundle:Position',
490-
'empty_value' => '',
490+
'placeholder' => '',
491491
'choices' => $positions,
492492
));
493493
}
@@ -497,6 +497,10 @@ sport like this::
497497
// ...
498498
}
499499

500+
.. versionadded:: 2.6
501+
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
502+
``empty_value``, which is available prior to 2.6.
503+
500504
When you're building this form to display to the user for the first time,
501505
then this example works perfectly.
502506

@@ -537,7 +541,7 @@ The type would now look like::
537541
$builder
538542
->add('sport', 'entity', array(
539543
'class' => 'AcmeDemoBundle:Sport',
540-
'empty_value' => '',
544+
'placeholder' => '',
541545
));
542546
;
543547

@@ -546,7 +550,7 @@ The type would now look like::
546550

547551
$form->add('position', 'entity', array(
548552
'class' => 'AcmeDemoBundle:Position',
549-
'empty_value' => '',
553+
'placeholder' => '',
550554
'choices' => $positions,
551555
));
552556
};

‎reference/forms/types/birthday.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ option defaults to 120 years ago to the current year.
2525
| Inherited options | from the :doc:`date </reference/forms/types/date>` type: |
2626
| | |
2727
| | - `days`_ |
28-
| | - `empty_value`_ |
28+
| | - `placeholder`_ |
2929
| | - `format`_ |
3030
| | - `input`_ |
3131
| | - `model_timezone`_ |
@@ -66,7 +66,7 @@ These options inherit from the :doc:`date </reference/forms/types/date>` type:
6666

6767
.. include:: /reference/forms/types/options/days.rst.inc
6868

69-
.. include:: /reference/forms/types/options/empty_value.rst.inc
69+
.. include:: /reference/forms/types/options/placeholder.rst.inc
7070

7171
.. include:: /reference/forms/types/options/date_format.rst.inc
7272

‎reference/forms/types/choice.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ option.
1515
+-------------+------------------------------------------------------------------------------+
1616
| Options | - `choices`_ |
1717
| | - `choice_list`_ |
18-
| | - `empty_value`_ |
18+
| | - `placeholder`_ |
1919
| | - `expanded`_ |
2020
| | - `multiple`_ |
2121
| | - `preferred_choices`_ |
@@ -122,7 +122,7 @@ With this option you can also allow float values to be selected as data.
122122
'choice_list' => new ChoiceList(array(1, 0.5), array('Full', 'Half'))
123123
));
124124
125-
.. include:: /reference/forms/types/options/empty_value.rst.inc
125+
.. include:: /reference/forms/types/options/placeholder.rst.inc
126126

127127
.. include:: /reference/forms/types/options/expanded.rst.inc
128128

@@ -204,13 +204,13 @@ Field Variables
204204
+------------------------+--------------+-------------------------------------------------------------------+
205205
| separator | ``string`` | The separator to use between choice groups. |
206206
+------------------------+--------------+-------------------------------------------------------------------+
207-
| empty_value | ``mixed`` | The empty value if not already in the list, otherwise |
207+
| placeholder | ``mixed`` | The empty value if not already in the list, otherwise |
208208
| | | ``null``. |
209209
+------------------------+--------------+-------------------------------------------------------------------+
210210
| is_selected | ``callable`` | A callable which takes a ``ChoiceView`` and the selected value(s) |
211211
| | | and returns whether the choice is in the selected value(s). |
212212
+------------------------+--------------+-------------------------------------------------------------------+
213-
| empty_value_in_choices | ``Boolean`` | Whether the empty value is in the choice list. |
213+
| placeholder_in_choices | ``Boolean`` | Whether the empty value is in the choice list. |
214214
+------------------------+--------------+-------------------------------------------------------------------+
215215

216216
.. tip::

‎reference/forms/types/country.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ you should just use the ``choice`` type directly.
2727
+-------------+-----------------------------------------------------------------------+
2828
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
2929
| options | |
30-
| | - `empty_value`_ |
30+
| | - `placeholder`_ |
3131
| | - `error_bubbling`_ |
3232
| | - `error_mapping`_ |
3333
| | - `expanded`_ |
@@ -66,7 +66,7 @@ Inherited Options
6666

6767
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
6868

69-
.. include:: /reference/forms/types/options/empty_value.rst.inc
69+
.. include:: /reference/forms/types/options/placeholder.rst.inc
7070

7171
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
7272

‎reference/forms/types/currency.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ should just use the ``choice`` type directly.
2121
+-------------+------------------------------------------------------------------------+
2222
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
2323
| options | |
24-
| | - `empty_value`_ |
24+
| | - `placeholder`_ |
2525
| | - `error_bubbling`_ |
2626
| | - `expanded`_ |
2727
| | - `multiple`_ |
@@ -58,7 +58,7 @@ Inherited Options
5858

5959
These options inherit from the :doc:`choice</reference/forms/types/choice>` type:
6060

61-
.. include:: /reference/forms/types/options/empty_value.rst.inc
61+
.. include:: /reference/forms/types/options/placeholder.rst.inc
6262

6363
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
6464

‎reference/forms/types/date.rst

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ day, and year) or three select boxes (see the `widget`_ option).
2020
| Rendered as | single text box or three select fields |
2121
+----------------------+-----------------------------------------------------------------------------+
2222
| Options | - `days`_ |
23-
| | - `empty_value`_ |
23+
| | - `placeholder`_ |
2424
| | - `format`_ |
2525
| | - `input`_ |
2626
| | - `model_timezone`_ |
@@ -82,23 +82,27 @@ Field Options
8282

8383
.. include:: /reference/forms/types/options/days.rst.inc
8484

85-
empty_value
85+
placeholder
8686
~~~~~~~~~~~
8787

88+
.. versionadded:: 2.6
89+
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
90+
``empty_value``, which is available prior to 2.6.
91+
8892
**type**: ``string`` or ``array``
8993

9094
If your widget option is set to ``choice``, then this field will be represented
91-
as a series of ``select`` boxes. The ``empty_value`` option can be used to
95+
as a series of ``select`` boxes. The ``placeholder`` option can be used to
9296
add a "blank" entry to the top of each select box::
9397

9498
$builder->add('dueDate', 'date', array(
95-
'empty_value' => '',
99+
'placeholder' => '',
96100
));
97101

98102
Alternatively, you can specify a string to be displayed for the "blank" value::
99103

100104
$builder->add('dueDate', 'date', array(
101-
'empty_value' => array('year' => 'Year', 'month' => 'Month', 'day' => 'Day')
105+
'placeholder' => array('year' => 'Year', 'month' => 'Month', 'day' => 'Day')
102106
));
103107

104108
.. _reference-forms-type-date-format:

‎reference/forms/types/datetime.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ data can be a ``DateTime`` object, a string, a timestamp or an array.
1818
| Options | - `date_format`_ |
1919
| | - `date_widget`_ |
2020
| | - `days`_ |
21-
| | - `empty_value`_ |
21+
| | - `placeholder`_ |
2222
| | - `format`_ |
2323
| | - `hours`_ |
2424
| | - `input`_ |
@@ -67,7 +67,7 @@ Defines the ``widget`` option for the :doc:`date </reference/forms/types/date>`
6767

6868
.. include:: /reference/forms/types/options/days.rst.inc
6969

70-
.. include:: /reference/forms/types/options/empty_value.rst.inc
70+
.. include:: /reference/forms/types/options/placeholder.rst.inc
7171

7272
format
7373
~~~~~~

‎reference/forms/types/entity.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ objects from the database.
2424
+-------------+------------------------------------------------------------------+
2525
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type: |
2626
| options | |
27-
| | - `empty_value`_ |
27+
| | - `placeholder`_ |
2828
| | - `expanded`_ |
2929
| | - `multiple`_ |
3030
| | - `preferred_choices`_ |
@@ -194,7 +194,7 @@ Inherited Options
194194

195195
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
196196

197-
.. include:: /reference/forms/types/options/empty_value.rst.inc
197+
.. include:: /reference/forms/types/options/placeholder.rst.inc
198198

199199
.. include:: /reference/forms/types/options/expanded.rst.inc
200200

‎reference/forms/types/language.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ you should just use the ``choice`` type directly.
2828
+-------------+------------------------------------------------------------------------+
2929
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
3030
| options | |
31-
| | - `empty_value`_ |
31+
| | - `placeholder`_ |
3232
| | - `error_bubbling`_ |
3333
| | - `error_mapping`_ |
3434
| | - `expanded`_ |
@@ -67,7 +67,7 @@ Inherited Options
6767

6868
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
6969

70-
.. include:: /reference/forms/types/options/empty_value.rst.inc
70+
.. include:: /reference/forms/types/options/placeholder.rst.inc
7171

7272
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
7373

‎reference/forms/types/locale.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ you should just use the ``choice`` type directly.
3030
+-------------+------------------------------------------------------------------------+
3131
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
3232
| options | |
33-
| | - `empty_value`_ |
33+
| | - `placeholder`_ |
3434
| | - `error_bubbling`_ |
3535
| | - `error_mapping`_ |
3636
| | - `expanded`_ |
@@ -69,7 +69,7 @@ Inherited Options
6969

7070
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
7171

72-
.. include:: /reference/forms/types/options/empty_value.rst.inc
72+
.. include:: /reference/forms/types/options/placeholder.rst.inc
7373

7474
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
7575

‎reference/forms/types/options/checkbox_empty_data.rst.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,6 @@ empty_data
33

44
**type**: ``string`` **default**: ``mixed``
55

6-
This option determines what value the field will return when the ``empty_value``
6+
This option determines what value the field will return when the ``placeholder``
77
choice is selected. In the checkbox and the radio type, the value of ``empty_data``
88
is overriden by the value returned by the data transformer (see :doc:`/cookbook/form/data_transformers`).

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ selected, you can do it like this:
2323
'f' => 'Female'
2424
),
2525
'required' => false,
26-
'empty_value' => 'Choose your gender',
26+
'placeholder' => 'Choose your gender',
2727
'empty_data' => null
2828
));
2929

‎reference/forms/types/options/empty_value.rst.inc renamed to ‎reference/forms/types/options/placeholder.rst.inc

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1-
empty_value
1+
placeholder
22
~~~~~~~~~~~
33

4+
.. versionadded:: 2.6
5+
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
6+
``empty_value``, which is available prior to 2.6.
7+
48
.. versionadded:: 2.3
59
Since Symfony 2.3, empty values are also supported if the ``expanded``
610
option is set to true.
@@ -14,16 +18,16 @@ will appear at the top of a select widget. This option only applies if the
1418
* Add an empty value with "Choose an option" as the text::
1519

1620
$builder->add('states', 'choice', array(
17-
'empty_value' => 'Choose an option',
21+
'placeholder' => 'Choose an option',
1822
));
1923

2024
* Guarantee that no "empty" value option is displayed::
2125

2226
$builder->add('states', 'choice', array(
23-
'empty_value' => false,
27+
'placeholder' => false,
2428
));
2529

26-
If you leave the ``empty_value`` option unset, then a blank (with no text)
30+
If you leave the ``placeholder`` option unset, then a blank (with no text)
2731
option will automatically be added if and only if the ``required`` option
2832
is false::
2933

‎reference/forms/types/time.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ as a ``DateTime`` object, a string, a timestamp or an array.
1515
+----------------------+-----------------------------------------------------------------------------+
1616
| Rendered as | can be various tags (see below) |
1717
+----------------------+-----------------------------------------------------------------------------+
18-
| Options | - `empty_value`_ |
18+
| Options | - `placeholder`_ |
1919
| | - `hours`_ |
2020
| | - `input`_ |
2121
| | - `minutes`_ |
@@ -77,7 +77,7 @@ values.
7777
Field Options
7878
-------------
7979

80-
.. include:: /reference/forms/types/options/empty_value.rst.inc
80+
.. include:: /reference/forms/types/options/placeholder.rst.inc
8181

8282
.. include:: /reference/forms/types/options/hours.rst.inc
8383

‎reference/forms/types/timezone.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ you should just use the ``choice`` type directly.
2323
+-------------+------------------------------------------------------------------------+
2424
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
2525
| options | |
26-
| | - `empty_value`_ |
26+
| | - `placeholder`_ |
2727
| | - `expanded`_ |
2828
| | - `multiple`_ |
2929
| | - `preferred_choices`_ |
@@ -62,7 +62,7 @@ Inherited Options
6262

6363
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
6464

65-
.. include:: /reference/forms/types/options/empty_value.rst.inc
65+
.. include:: /reference/forms/types/options/placeholder.rst.inc
6666

6767
.. include:: /reference/forms/types/options/expanded.rst.inc
6868

0 commit comments

Comments
 (0)
0