[#3782] Deprecating the read_only option

snoob · weaverryan · commit c9e86341a6c3 · 2015-06-26T17:38:16.000-04:00
(committed by weaverryan, original credit to the author on this commit)
diff --git a/reference/forms/twig_reference.rst b/reference/forms/twig_reference.rst
@@ -340,8 +340,6 @@ object:
 +------------------------+-------------------------------------------------------------------------------------+
 | ``value``              | The value that will be used when rendering (commonly the ``value`` HTML attribute). |
 +------------------------+-------------------------------------------------------------------------------------+
-| ``read_only``          | If ``true``, ``readonly="readonly"`` is added to the field.                         |
-+------------------------+-------------------------------------------------------------------------------------+
 | ``disabled``           | If ``true``, ``disabled="disabled"`` is added to the field.                         |
 +------------------------+-------------------------------------------------------------------------------------+
 | ``required``           | If ``true``, a ``required`` attribute is added to the field to activate HTML5       |
diff --git a/reference/forms/types/birthday.rst b/reference/forms/types/birthday.rst
@@ -41,7 +41,7 @@ option defaults to 120 years ago to the current year.
 |                      | - `invalid_message`_                                                          |
 |                      | - `invalid_message_parameters`_                                               |
 |                      | - `mapped`_                                                                   |
-|                      | - `read_only`_                                                                |
+|                      | - `read_only`_ (deprecated as of 2.8)                                         |
 +----------------------+-------------------------------------------------------------------------------+
 | Parent type          | :doc:`date </reference/forms/types/date>`                                     |
 +----------------------+-------------------------------------------------------------------------------+
diff --git a/reference/forms/types/checkbox.rst b/reference/forms/types/checkbox.rst
@@ -23,7 +23,7 @@ if the box is unchecked, the value will be set to false.
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `mapped`_                                                            |
-|             | - `read_only`_                                                         |
+|             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                              |
diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
@@ -32,7 +32,7 @@ option.
 |             | - `label`_                                                                   |
 |             | - `label_attr`_                                                              |
 |             | - `mapped`_                                                                  |
-|             | - `read_only`_                                                               |
+|             | - `read_only`_ (deprecated as of 2.8)                                        |
 |             | - `required`_                                                                |
 +-------------+------------------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                                    |
diff --git a/reference/forms/types/country.rst b/reference/forms/types/country.rst
@@ -42,7 +42,7 @@ you should just use the ``choice`` type directly.
 |             | - `label`_                                                            |
 |             | - `label_attr`_                                                       |
 |             | - `mapped`_                                                           |
-|             | - `read_only`_                                                        |
+|             | - `read_only`_ (deprecated as of 2.8)                                 |
 |             | - `required`_                                                         |
 +-------------+-----------------------------------------------------------------------+
 | Parent type | :doc:`choice </reference/forms/types/choice>`                         |
diff --git a/reference/forms/types/currency.rst b/reference/forms/types/currency.rst
@@ -35,7 +35,7 @@ you should just use the ``choice`` type directly.
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `mapped`_                                                            |
-|             | - `read_only`_                                                         |
+|             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`choice </reference/forms/types/choice>`                          |
diff --git a/reference/forms/types/date.rst b/reference/forms/types/date.rst
@@ -40,7 +40,7 @@ day and year) or three select boxes (see the `widget`_ option).
 |                      | - `invalid_message`_                                                        |
 |                      | - `invalid_message_parameters`_                                             |
 |                      | - `mapped`_                                                                 |
-|                      | - `read_only`_                                                              |
+|                      | - `read_only`_ (deprecated as of 2.8)                                       |
 +----------------------+-----------------------------------------------------------------------------+
 | Parent type          | :doc:`form </reference/forms/types/form>`                                   |
 +----------------------+-----------------------------------------------------------------------------+
diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst
@@ -40,7 +40,7 @@ the data can be a ``DateTime`` object, a string, a timestamp or an array.
 |                      | - `invalid_message`_                                                        |
 |                      | - `invalid_message_parameters`_                                             |
 |                      | - `mapped`_                                                                 |
-|                      | - `read_only`_                                                              |
+|                      | - `read_only`_ (deprecated as of 2.8)                                       |
 +----------------------+-----------------------------------------------------------------------------+
 | Parent type          | :doc:`form </reference/forms/types/form>`                                   |
 +----------------------+-----------------------------------------------------------------------------+
diff --git a/reference/forms/types/email.rst b/reference/forms/types/email.rst
@@ -19,7 +19,7 @@ The ``email`` field is a text field that is rendered using the HTML5
 |             | - `label_attr`_                                                     |
 |             | - `mapped`_                                                         |
 |             | - `max_length`_ (deprecated as of 2.5)                              |
-|             | - `read_only`_                                                      |
+|             | - `read_only`_ (deprecated as of 2.8)                               |
 |             | - `required`_                                                       |
 |             | - `trim`_                                                           |
 +-------------+---------------------------------------------------------------------+
diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst
@@ -39,7 +39,7 @@ objects from the database.
 |             | - `label`_                                                       |
 |             | - `label_attr`_                                                  |
 |             | - `mapped`_                                                      |
-|             | - `read_only`_                                                   |
+|             | - `read_only`_ (deprecated as of 2.8)                            |
 |             | - `required`_                                                    |
 +-------------+------------------------------------------------------------------+
 | Parent type | :doc:`choice </reference/forms/types/choice>`                    |
diff --git a/reference/forms/types/file.rst b/reference/forms/types/file.rst
@@ -18,7 +18,7 @@ The ``file`` type represents a file input in your form.
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `mapped`_                                                         |
-|             | - `read_only`_                                                      |
+|             | - `read_only`_ (deprecated as of 2.8)                               |
 |             | - `required`_                                                       |
 +-------------+---------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                           |
diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst
@@ -30,7 +30,7 @@ on all types for which ``form`` is the parent type.
 |           | - `pattern`_ (deprecated as of 2.5)                                |
 |           | - `post_max_size_message`_                                         |
 |           | - `property_path`_                                                 |
-|           | - `read_only`_                                                     |
+|           | - `read_only`_ (deprecated as of 2.8)                              |
 |           | - `required`_                                                      |
 |           | - `trim`_                                                          |
 +-----------+--------------------------------------------------------------------+
diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst
@@ -30,7 +30,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down
 |             | - `label`_                                                            |
 |             | - `label_attr`_                                                       |
 |             | - `mapped`_                                                           |
-|             | - `read_only`_                                                        |
+|             | - `read_only`_ (deprecated as of 2.8)                                 |
 |             | - `required`_                                                         |
 +-------------+-----------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                             |
diff --git a/reference/forms/types/language.rst b/reference/forms/types/language.rst
@@ -43,7 +43,7 @@ you should just use the ``choice`` type directly.
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `mapped`_                                                            |
-|             | - `read_only`_                                                         |
+|             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`choice </reference/forms/types/choice>`                          |
diff --git a/reference/forms/types/locale.rst b/reference/forms/types/locale.rst
@@ -45,7 +45,7 @@ you should just use the ``choice`` type directly.
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `mapped`_                                                            |
-|             | - `read_only`_                                                         |
+|             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`choice </reference/forms/types/choice>`                          |
diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst
@@ -29,7 +29,7 @@ how the input and output of the data is handled.
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `mapped`_                                                         |
-|             | - `read_only`_                                                      |
+|             | - `read_only`_ (deprecated as of 2.8)                               |
 |             | - `required`_                                                       |
 +-------------+---------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                           |
diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst
@@ -25,7 +25,7 @@ that you want to use for your number.
 |             | - `label`_                                                           |
 |             | - `label_attr`_                                                      |
 |             | - `mapped`_                                                          |
-|             | - `read_only`_                                                       |
+|             | - `read_only`_ (deprecated as of 2.8)                                |
 |             | - `required`_                                                        |
 +-------------+----------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                            |
diff --git a/reference/forms/types/options/read_only.rst.inc b/reference/forms/types/options/read_only.rst.inc
@@ -1,6 +1,11 @@
 read_only
 ~~~~~~~~~
 
+.. caution::
+
+    The ``read_only`` option has been deprecated and will be removed in 3.0.
+    Instead, use the ``attr`` option by setting it to an array with a ``readonly`` key.
+
 **type**: ``boolean`` **default**: ``false``
 
 If this option is true, the field will be rendered with the ``readonly``
diff --git a/reference/forms/types/password.rst b/reference/forms/types/password.rst
@@ -19,7 +19,7 @@ The ``password`` field renders an input password text box.
 |             | - `label_attr`_                                                        |
 |             | - `mapped`_                                                            |
 |             | - `max_length`_ (deprecated as of 2.5)                                 |
-|             | - `read_only`_                                                         |
+|             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
 |             | - `trim`_                                                              |
 +-------------+------------------------------------------------------------------------+
diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst
@@ -28,7 +28,7 @@ This field adds a percentage sign "``%``" after the input box.
 |             | - `label`_                                                            |
 |             | - `label_attr`_                                                       |
 |             | - `mapped`_                                                           |
-|             | - `read_only`_                                                        |
+|             | - `read_only`_ (deprecated as of 2.8)                                 |
 |             | - `required`_                                                         |
 +-------------+-----------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                             |
diff --git a/reference/forms/types/radio.rst b/reference/forms/types/radio.rst
@@ -30,7 +30,7 @@ If you want to have a boolean field, use :doc:`checkbox </reference/forms/types/
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `mapped`_                                                         |
-|             | - `read_only`_                                                      |
+|             | - `read_only`_ (deprecated as of 2.8)                               |
 |             | - `required`_                                                       |
 +-------------+---------------------------------------------------------------------+
 | Parent type | :doc:`checkbox </reference/forms/types/checkbox>`                   |
diff --git a/reference/forms/types/search.rst b/reference/forms/types/search.rst
@@ -20,7 +20,7 @@ Read about the input search field at `DiveIntoHTML5.info`_
 |             | - `label_attr`_                                                      |
 |             | - `mapped`_                                                          |
 |             | - `max_length`_ (deprecated as of 2.5)                               |
-|             | - `read_only`_                                                       |
+|             | - `read_only`_ (deprecated as of 2.8)                                |
 |             | - `required`_                                                        |
 |             | - `trim`_                                                            |
 +-------------+----------------------------------------------------------------------+
diff --git a/reference/forms/types/text.rst b/reference/forms/types/text.rst
@@ -18,7 +18,7 @@ The text field represents the most basic input text field.
 |             | - `label_attr`_                                                    |
 |             | - `mapped`_                                                        |
 |             | - `max_length`_ (deprecated as of 2.5)                             |
-|             | - `read_only`_                                                     |
+|             | - `read_only`_ (deprecated as of 2.8)                              |
 |             | - `required`_                                                      |
 |             | - `trim`_                                                          |
 +-------------+--------------------------------------------------------------------+
diff --git a/reference/forms/types/textarea.rst b/reference/forms/types/textarea.rst
@@ -19,7 +19,7 @@ Renders a ``textarea`` HTML element.
 |             | - `label_attr`_                                                        |
 |             | - `mapped`_                                                            |
 |             | - `max_length`_ (deprecated as of 2.5)                                 |
-|             | - `read_only`_                                                         |
+|             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
 |             | - `trim`_                                                              |
 +-------------+------------------------------------------------------------------------+
diff --git a/reference/forms/types/time.rst b/reference/forms/types/time.rst
@@ -37,7 +37,7 @@ stored as a ``DateTime`` object, a string, a timestamp or an array.
 |                      | - `invalid_message`_                                                        |
 |                      | - `invalid_message_parameters`_                                             |
 |                      | - `mapped`_                                                                 |
-|                      | - `read_only`_                                                              |
+|                      | - `read_only`_ (deprecated as of 2.8)                                       |
 +----------------------+-----------------------------------------------------------------------------+
 | Parent type          | form                                                                        |
 +----------------------+-----------------------------------------------------------------------------+
diff --git a/reference/forms/types/timezone.rst b/reference/forms/types/timezone.rst
diff --git a/reference/forms/types/url.rst b/reference/forms/types/url.rst
