Permalink
Browse files

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
  • Loading branch information...
weaverryan committed Nov 24, 2014
2 parents 3ecfcaf + 54c44ea commit 48a5af3a057c075e3d86639857ecaaed561984c7
@@ -240,7 +240,7 @@ new instance of the type in one of your forms::
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder->add('gender_code', new GenderType(), array(
'empty_value' => 'Choose a gender',
'placeholder' => 'Choose a gender',
));
}
}
@@ -249,6 +249,10 @@ But this only works because the ``GenderType()`` is very simple. What if
the gender codes were stored in configuration or in a database? The next
section explains how more complex field types solve this problem.
.. versionadded:: 2.6
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
``empty_value``, which is available prior to 2.6.
.. _form-cookbook-form-field-service:
Creating your Field Type as a Service
@@ -378,7 +382,7 @@ configuration, using the field is now much easier::
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder->add('gender_code', 'gender', array(
'empty_value' => 'Choose a gender',
'placeholder' => 'Choose a gender',
));
}
}
@@ -470,7 +470,7 @@ sport like this::
$builder
->add('sport', 'entity', array(
'class' => 'AcmeDemoBundle:Sport',
'empty_value' => '',
'placeholder' => '',
))
;
@@ -487,7 +487,7 @@ sport like this::
$form->add('position', 'entity', array(
'class' => 'AcmeDemoBundle:Position',
'empty_value' => '',
'placeholder' => '',
'choices' => $positions,
));
}
@@ -497,6 +497,10 @@ sport like this::
// ...
}
.. versionadded:: 2.6
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
``empty_value``, which is available prior to 2.6.
When you're building this form to display to the user for the first time,
then this example works perfectly.
@@ -537,7 +541,7 @@ The type would now look like::
$builder
->add('sport', 'entity', array(
'class' => 'AcmeDemoBundle:Sport',
'empty_value' => '',
'placeholder' => '',
));
;
@@ -546,7 +550,7 @@ The type would now look like::
$form->add('position', 'entity', array(
'class' => 'AcmeDemoBundle:Position',
'empty_value' => '',
'placeholder' => '',
'choices' => $positions,
));
};
@@ -25,7 +25,7 @@ option defaults to 120 years ago to the current year.
| Inherited options | from the :doc:`date </reference/forms/types/date>` type: |
| | |
| | - `days`_ |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `format`_ |
| | - `input`_ |
| | - `model_timezone`_ |
@@ -66,7 +66,7 @@ These options inherit from the :doc:`date </reference/forms/types/date>` type:
.. include:: /reference/forms/types/options/days.rst.inc
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/date_format.rst.inc
@@ -15,7 +15,7 @@ option.
+-------------+------------------------------------------------------------------------------+
| Options | - `choices`_ |
| | - `choice_list`_ |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `expanded`_ |
| | - `multiple`_ |
| | - `preferred_choices`_ |
@@ -122,7 +122,7 @@ With this option you can also allow float values to be selected as data.
'choice_list' => new ChoiceList(array(1, 0.5), array('Full', 'Half'))
));
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/expanded.rst.inc
@@ -204,13 +204,13 @@ Field Variables
+------------------------+--------------+-------------------------------------------------------------------+
| separator | ``string`` | The separator to use between choice groups. |
+------------------------+--------------+-------------------------------------------------------------------+
| empty_value | ``mixed`` | The empty value if not already in the list, otherwise |
| placeholder | ``mixed`` | The empty value if not already in the list, otherwise |
| | | ``null``. |
+------------------------+--------------+-------------------------------------------------------------------+
| is_selected | ``callable`` | A callable which takes a ``ChoiceView`` and the selected value(s) |
| | | and returns whether the choice is in the selected value(s). |
+------------------------+--------------+-------------------------------------------------------------------+
| empty_value_in_choices | ``Boolean`` | Whether the empty value is in the choice list. |
| placeholder_in_choices | ``Boolean`` | Whether the empty value is in the choice list. |
+------------------------+--------------+-------------------------------------------------------------------+
.. tip::
@@ -27,7 +27,7 @@ you should just use the ``choice`` type directly.
+-------------+-----------------------------------------------------------------------+
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
| options | |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `error_bubbling`_ |
| | - `error_mapping`_ |
| | - `expanded`_ |
@@ -66,7 +66,7 @@ Inherited Options
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
@@ -21,7 +21,7 @@ should just use the ``choice`` type directly.
+-------------+------------------------------------------------------------------------+
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
| options | |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `error_bubbling`_ |
| | - `expanded`_ |
| | - `multiple`_ |
@@ -58,7 +58,7 @@ Inherited Options
These options inherit from the :doc:`choice</reference/forms/types/choice>` type:
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
@@ -20,7 +20,7 @@ day, and year) or three select boxes (see the `widget`_ option).
| Rendered as | single text box or three select fields |
+----------------------+-----------------------------------------------------------------------------+
| Options | - `days`_ |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `format`_ |
| | - `input`_ |
| | - `model_timezone`_ |
@@ -82,23 +82,27 @@ Field Options
.. include:: /reference/forms/types/options/days.rst.inc
empty_value
placeholder
~~~~~~~~~~~
.. versionadded:: 2.6
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
``empty_value``, which is available prior to 2.6.
**type**: ``string`` or ``array``
If your widget option is set to ``choice``, then this field will be represented
as a series of ``select`` boxes. The ``empty_value`` option can be used to
as a series of ``select`` boxes. The ``placeholder`` option can be used to
add a "blank" entry to the top of each select box::
$builder->add('dueDate', 'date', array(
'empty_value' => '',
'placeholder' => '',
));
Alternatively, you can specify a string to be displayed for the "blank" value::
$builder->add('dueDate', 'date', array(
'empty_value' => array('year' => 'Year', 'month' => 'Month', 'day' => 'Day')
'placeholder' => array('year' => 'Year', 'month' => 'Month', 'day' => 'Day')
));
.. _reference-forms-type-date-format:
@@ -18,7 +18,7 @@ data can be a ``DateTime`` object, a string, a timestamp or an array.
| Options | - `date_format`_ |
| | - `date_widget`_ |
| | - `days`_ |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `format`_ |
| | - `hours`_ |
| | - `input`_ |
@@ -67,7 +67,7 @@ Defines the ``widget`` option for the :doc:`date </reference/forms/types/date>`
.. include:: /reference/forms/types/options/days.rst.inc
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
format
~~~~~~
@@ -24,7 +24,7 @@ objects from the database.
+-------------+------------------------------------------------------------------+
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type: |
| options | |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `expanded`_ |
| | - `multiple`_ |
| | - `preferred_choices`_ |
@@ -194,7 +194,7 @@ Inherited Options
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/expanded.rst.inc
@@ -28,7 +28,7 @@ you should just use the ``choice`` type directly.
+-------------+------------------------------------------------------------------------+
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
| options | |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `error_bubbling`_ |
| | - `error_mapping`_ |
| | - `expanded`_ |
@@ -67,7 +67,7 @@ Inherited Options
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
@@ -30,7 +30,7 @@ you should just use the ``choice`` type directly.
+-------------+------------------------------------------------------------------------+
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
| options | |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `error_bubbling`_ |
| | - `error_mapping`_ |
| | - `expanded`_ |
@@ -69,7 +69,7 @@ Inherited Options
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
@@ -3,6 +3,6 @@ empty_data
**type**: ``string`` **default**: ``mixed``
This option determines what value the field will return when the ``empty_value``
This option determines what value the field will return when the ``placeholder``
choice is selected. In the checkbox and the radio type, the value of ``empty_data``
is overriden by the value returned by the data transformer (see :doc:`/cookbook/form/data_transformers`).
@@ -23,7 +23,7 @@ selected, you can do it like this:
'f' => 'Female'
),
'required' => false,
'empty_value' => 'Choose your gender',
'placeholder' => 'Choose your gender',
'empty_data' => null
));
@@ -1,6 +1,10 @@
empty_value
placeholder
~~~~~~~~~~~
.. versionadded:: 2.6
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
``empty_value``, which is available prior to 2.6.
.. versionadded:: 2.3
Since Symfony 2.3, empty values are also supported if the ``expanded``
option is set to true.
@@ -14,16 +18,16 @@ will appear at the top of a select widget. This option only applies if the
* Add an empty value with "Choose an option" as the text::
$builder->add('states', 'choice', array(
'empty_value' => 'Choose an option',
'placeholder' => 'Choose an option',
));
* Guarantee that no "empty" value option is displayed::
$builder->add('states', 'choice', array(
'empty_value' => false,
'placeholder' => false,
));
If you leave the ``empty_value`` option unset, then a blank (with no text)
If you leave the ``placeholder`` option unset, then a blank (with no text)
option will automatically be added if and only if the ``required`` option
is false::
@@ -15,7 +15,7 @@ as a ``DateTime`` object, a string, a timestamp or an array.
+----------------------+-----------------------------------------------------------------------------+
| Rendered as | can be various tags (see below) |
+----------------------+-----------------------------------------------------------------------------+
| Options | - `empty_value`_ |
| Options | - `placeholder`_ |
| | - `hours`_ |
| | - `input`_ |
| | - `minutes`_ |
@@ -77,7 +77,7 @@ values.
Field Options
-------------
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/hours.rst.inc
@@ -23,7 +23,7 @@ you should just use the ``choice`` type directly.
+-------------+------------------------------------------------------------------------+
| Inherited | from the :doc:`choice </reference/forms/types/choice>` type |
| options | |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `expanded`_ |
| | - `multiple`_ |
| | - `preferred_choices`_ |
@@ -62,7 +62,7 @@ Inherited Options
These options inherit from the :doc:`choice </reference/forms/types/choice>` type:
.. include:: /reference/forms/types/options/empty_value.rst.inc
.. include:: /reference/forms/types/options/placeholder.rst.inc
.. include:: /reference/forms/types/options/expanded.rst.inc

0 comments on commit 48a5af3

Please sign in to comment.