Skip to content

Renamed empty_value to placeholder #4486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 24, 2014
Merged

Renamed empty_value to placeholder #4486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions cookbook/form/create_custom_field_type.rst
View file
Open in desktop
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this included in many files, it'll better fit in its own file.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's usefull here, since we don't want to change these small versionadded messages

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, I think for the moment we should at least link to the reference of the placeholder option. But maybe later on someone writes a nice article about the placeholder and what else you can do with that (no matter how likely that is, there might be other reasons to change this later).

However, moving this to it's own file is not that important. But please add a link to the option's reference section.


.. _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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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