From 70852c8b75f50aa82998d04a3933cac8883df451 Mon Sep 17 00:00:00 2001
From: Henry Snoek <snoek09@gmail.com>
Date: Sat, 30 Jan 2016 19:59:43 +0100
Subject: [PATCH] add separate placeholder examples for birthday, datetime and
 time type

---
 reference/forms/types/birthday.rst | 26 +++++++++++++++++++++++++-
 reference/forms/types/date.rst     | 15 +++++++++------
 reference/forms/types/datetime.rst | 27 ++++++++++++++++++++++++++-
 reference/forms/types/time.rst     | 26 +++++++++++++++++++++++++-
 4 files changed, 85 insertions(+), 9 deletions(-)

diff --git a/reference/forms/types/birthday.rst b/reference/forms/types/birthday.rst
index 380d99a3747..cb1e28cedad 100644
--- a/reference/forms/types/birthday.rst
+++ b/reference/forms/types/birthday.rst
@@ -67,7 +67,31 @@ type:
 
 .. include:: /reference/forms/types/options/days.rst.inc
 
-.. include:: /reference/forms/types/options/placeholder.rst.inc
+placeholder
+~~~~~~~~~~~
+
+.. versionadded:: 2.6
+    The ``placeholder`` option was introduced in Symfony 2.6 and replaces
+    ``empty_value``, which is available prior to 2.6.
+
+**type**: ``string`` | ``array``
+
+If your widget option is set to ``choice``, then this field will be represented
+as a series of ``select`` boxes. When the placeholder value is a string,
+it will be used as the **blank value** of all select boxes::
+
+    $builder->add('birthdate', 'birthday', array(
+        'placeholder' => 'Select a value',
+    ));
+
+Alternatively, you can use an array that configures different placeholder
+values for the year, month and day fields::
+
+    $builder->add('birthdate', 'birthday', array(
+        'placeholder' => array(
+            'year' => 'Year', 'month' => 'Month', 'day' => 'Day',
+        )
+    ));
 
 .. include:: /reference/forms/types/options/date_format.rst.inc
 
diff --git a/reference/forms/types/date.rst b/reference/forms/types/date.rst
index 2efa97662ce..86df6afaee8 100644
--- a/reference/forms/types/date.rst
+++ b/reference/forms/types/date.rst
@@ -88,20 +88,23 @@ placeholder
     The ``placeholder`` option was introduced in Symfony 2.6 and replaces
     ``empty_value``, which is available prior to 2.6.
 
-**type**: ``string`` or ``array``
+**type**: ``string`` | ``array``
 
 If your widget option is set to ``choice``, then this field will be represented
-as a series of ``select`` boxes. The ``placeholder`` option can be used
-to add a "blank" entry to the top of each select box::
+as a series of ``select`` boxes. When the placeholder value is a string,
+it will be used as the **blank value** of all select boxes::
 
     $builder->add('dueDate', 'date', array(
-        'placeholder' => '',
+        'placeholder' => 'Select a value',
     ));
 
-Alternatively, you can specify a string to be displayed for the "blank" value::
+Alternatively, you can use an array that configures different placeholder
+values for the year, month and day fields::
 
     $builder->add('dueDate', 'date', array(
-        'placeholder' => array('year' => 'Year', 'month' => 'Month', 'day' => 'Day')
+        'placeholder' => array(
+            'year' => 'Year', 'month' => 'Month', 'day' => 'Day'
+        )
     ));
 
 .. _reference-forms-type-date-format:
diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst
index da352ec00cf..fade67e2c89 100644
--- a/reference/forms/types/datetime.rst
+++ b/reference/forms/types/datetime.rst
@@ -71,7 +71,32 @@ date_widget
 
 .. include:: /reference/forms/types/options/days.rst.inc
 
-.. include:: /reference/forms/types/options/placeholder.rst.inc
+placeholder
+~~~~~~~~~~~
+
+.. versionadded:: 2.6
+    The ``placeholder`` option was introduced in Symfony 2.6 and replaces
+    ``empty_value``, which is available prior to 2.6.
+
+**type**: ``string`` | ``array``
+
+If your widget option is set to ``choice``, then this field will be represented
+as a series of ``select`` boxes. When the placeholder value is a string,
+it will be used as the **blank value** of all select boxes::
+
+    $builder->add('startDateTime', 'datetime', array(
+        'placeholder' => 'Select a value',
+    ));
+
+Alternatively, you can use an array that configures different placeholder
+values for the year, month, day, hour, minute and second fields::
+
+    $builder->add('startDateTime', 'datetime', array(
+        'placeholder' => array(
+            'year' => 'Year', 'month' => 'Month', 'day' => 'Day',
+            'hour' => 'Hour', 'minute' => 'Minute', 'second' => 'Second',
+        )
+    ));
 
 format
 ~~~~~~
diff --git a/reference/forms/types/time.rst b/reference/forms/types/time.rst
index cc03943b183..227cbd75ec5 100644
--- a/reference/forms/types/time.rst
+++ b/reference/forms/types/time.rst
@@ -76,7 +76,31 @@ values.
 Field Options
 -------------
 
-.. include:: /reference/forms/types/options/placeholder.rst.inc
+placeholder
+~~~~~~~~~~~
+
+.. versionadded:: 2.6
+    The ``placeholder`` option was introduced in Symfony 2.6 and replaces
+    ``empty_value``, which is available prior to 2.6.
+
+**type**: ``string`` | ``array``
+
+If your widget option is set to ``choice``, then this field will be represented
+as a series of ``select`` boxes. When the placeholder value is a string,
+it will be used as the **blank value** of all select boxes::
+
+    $builder->add('startTime', 'time', array(
+        'placeholder' => 'Select a value',
+    ));
+
+Alternatively, you can use an array that configures different placeholder
+values for the hour, minute and second fields::
+
+    $builder->add('startTime', 'time', array(
+        'placeholder' => array(
+            'hour' => 'Hour', 'minute' => 'Minute', 'second' => 'Second',
+        )
+    ));
 
 .. include:: /reference/forms/types/options/hours.rst.inc