Skip to content

Commit

Permalink
feature #4486 Renamed empty_value to placeholder (WouterJ)
Browse files Browse the repository at this point in the history 
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
weaverryan committed Nov 24, 2014
2 parents 3ecfcaf + 54c44ea commit 48a5af3
Show file tree
Hide file tree
Showing 16 changed files with 55 additions and 39 deletions.
8 changes: 6 additions & 2 deletions cookbook/form/create_custom_field_type.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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',
));
}
}
Expand All @@ -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
Expand Down Expand Up @@ -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',
));
}
}
Expand Down
12 changes: 8 additions & 4 deletions cookbook/form/dynamic_form_modification.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -470,7 +470,7 @@ sport like this::
$builder
->add('sport', 'entity', array(
'class' => 'AcmeDemoBundle:Sport',
'empty_value' => '',
'placeholder' => '',
))
;

Expand All @@ -487,7 +487,7 @@ sport like this::

$form->add('position', 'entity', array(
'class' => 'AcmeDemoBundle:Position',
'empty_value' => '',
'placeholder' => '',
'choices' => $positions,
));
}
Expand All @@ -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.

Expand Down Expand Up @@ -537,7 +541,7 @@ The type would now look like::
$builder
->add('sport', 'entity', array(
'class' => 'AcmeDemoBundle:Sport',
'empty_value' => '',
'placeholder' => '',
));
;

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

$form->add('position', 'entity', array(
'class' => 'AcmeDemoBundle:Position',
'empty_value' => '',
'placeholder' => '',
'choices' => $positions,
));
};
Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/birthday.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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

Expand Down
8 changes: 4 additions & 4 deletions reference/forms/types/choice.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ option.
+-------------+------------------------------------------------------------------------------+
| Options | - `choices`_ |
| | - `choice_list`_ |
| | - `empty_value`_ |
| | - `placeholder`_ |
| | - `expanded`_ |
| | - `multiple`_ |
| | - `preferred_choices`_ |
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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::
Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/country.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/currency.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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

Expand Down
14 changes: 9 additions & 5 deletions reference/forms/types/date.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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:
Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/datetime.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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
~~~~~~
Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/entity.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/language.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/locale.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion reference/forms/types/options/checkbox_empty_data.rst.inc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
2 changes: 1 addition & 1 deletion reference/forms/types/options/empty_data.rst.inc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
));

Expand Down
12 changes: 8 additions & 4 deletions ...e/forms/types/options/empty_value.rst.inc → ...e/forms/types/options/placeholder.rst.inc
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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::

Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/time.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions reference/forms/types/timezone.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 48a5af3

Please sign in to comment.