feature #3588 Documented all form variables (WouterJ)

This PR was merged into the 2.3 branch. Discussion ---------- Documented all form variables | Q | A | --- | --- | Doc fix? | no | New docs? | yes | Applies to | 2.3+ | Fixed tickets | #2372 This PR adds all missing global form variables to the twig reference. Besides that, it also introduces a new section for form types: Form Variables. This explains what kind of variables are available for that particular field. This is usefull if you want to create a custom theme. At last, it also adds the missing docs for the `selectedchoice` Twig test. Commits ------- 7710429 Made full stop usage consistent 398d23f Applied comments by @xabbuh 97d216d Documented TimeType variables 8b5ecf9 Documented SubmitType variables 688409e Documented MoneyType variables a811833 Documented FileType variables e5fded9 Documented date_pattern variable of DateType 1a1497c Extracted duplicated var tables 95540ca Documented Date(Time)Type variables 3bfdc20 Documented CollectionType variables 754da30 Added performance tip 7d10315 Documented selectedchoice test c8a44ae Documented choice variables 98e828f Documented checked variable d2b57be Documented missing FormType variables
symfony · Mar 9, 2014 · d881181 · d881181
2 parents 4ef746a + 7710429
commit d881181
Show file tree

Hide file tree

Showing 12 changed files with 209 additions and 42 deletions.
diff --git a/reference/forms/twig_reference.rst b/reference/forms/twig_reference.rst
@@ -192,6 +192,24 @@ good idea to include this in your form tag:
 
     <form action="{{ path('form_submit') }}" method="post" {{ form_enctype(form) }}>
 
+Form Tests Reference
+--------------------
+
+Tests can be executed by using the ``is`` operator in Twig to create a
+condition. Read `the Twig documentation`_ for more information.
+
+.. _form-twig-selectedchoice:
+
+selectedchoice(selected_value)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This test will check if the current choice is equal to the ``selected_value``
+or if the current choice is in the array (when ``selected_value`` is an array).
+
+.. code-block:: jinja
+
+    <option {% if choice is selectedchoice(value) %} selected="selected"{% endif %} ...>
+
 .. _`twig-reference-form-variables`:
 
 More about Form Variables
@@ -295,47 +313,66 @@ object:
             <?php echo $view['form']->get('name')->vars['label'] ?>
         </label>
 
-+-----------------+-----------------------------------------------------------------------------------------+
-| Variable        | Usage                                                                                   |
-+=================+=========================================================================================+
-| ``id``          | The ``id`` HTML attribute to be rendered                                                |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``name``        | The name of the field (e.g. ``title``) - but not the ``name``                           |
-|                 | HTML attribute, which is ``full_name``                                                  |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``full_name``   | The ``name`` HTML attribute to be rendered                                              |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``errors``      | An array of any errors attached to *this* specific field (e.g. ``form.title.errors``).  |
-|                 | Note that you can't use ``form.errors`` to determine if a form is valid,                |
-|                 | since this only returns "global" errors: some individual fields may have errors         |
-|                 | Instead, use the ``valid`` option                                                       |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``valid``       | Returns ``true`` or ``false`` depending on whether the whole form is valid              |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``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           |
-|                 | validation. Additionally, a ``required`` class is added to the label.                   |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``max_length``  | Adds a ``maxlength`` HTML attribute to the element                                      |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``pattern``     | Adds a ``pattern`` HTML attribute to the element                                        |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``label``       | The string label that will be rendered                                                  |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``multipart``   | If ``true``, ``form_enctype`` will render ``enctype="multipart/form-data"``.            |
-|                 | This only applies to the root form element.                                             |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``attr``        | A key-value array that will be rendered as HTML attributes on the field                 |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``label_attr``  | A key-value array that will be rendered as HTML attributes on the label                 |
-+-----------------+-----------------------------------------------------------------------------------------+
-| ``compound``    | Whether or not a field is actually a holder for a group of children fields              |
-|                 | (for example, a ``choice`` field, which is actually a group of checkboxes               |
-+-----------------+-----------------------------------------------------------------------------------------+
+.. versionadded:: 2.3
+    The ``method`` and ``action`` variables were introduced in Symfony 2.3.
+
++------------------------+-------------------------------------------------------------------------------------+
+| Variable               | Usage                                                                               |
++========================+=====================================================================================+
+| ``form``               | The current ``FormView`` instance.                                                  |
++------------------------+-------------------------------------------------------------------------------------+
+| ``id``                 | The ``id`` HTML attribute to be rendered.                                           |
++------------------------+-------------------------------------------------------------------------------------+
+| ``name``               | The name of the field (e.g. ``title``) - but not the ``name``                       |
+|                        | HTML attribute, which is ``full_name``.                                             |
++------------------------+-------------------------------------------------------------------------------------+
+| ``full_name``          | The ``name`` HTML attribute to be rendered.                                         |
++------------------------+-------------------------------------------------------------------------------------+
+| ``errors``             | An array of any errors attached to *this* specific field                            |
+|                        | (e.g. ``form.title.errors``).                                                       |
+|                        | Note that you can't use ``form.errors`` to determine if a form is valid,            |
+|                        | since this only returns "global" errors: some individual fields may have errors.    |
+|                        | Instead, use the ``valid`` option.                                                  |
++------------------------+-------------------------------------------------------------------------------------+
+| ``valid``              | Returns ``true`` or ``false`` depending on whether the whole form is valid.         |
++------------------------+-------------------------------------------------------------------------------------+
+| ``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       |
+|                        | validation. Additionally, a ``required`` class is added to the label.               |
++------------------------+-------------------------------------------------------------------------------------+
+| ``max_length``         | Adds a ``maxlength`` HTML attribute to the element.                                 |
++------------------------+-------------------------------------------------------------------------------------+
+| ``pattern``            | Adds a ``pattern`` HTML attribute to the element.                                   |
++------------------------+-------------------------------------------------------------------------------------+
+| ``label``              | The string label that will be rendered.                                             |
++------------------------+-------------------------------------------------------------------------------------+
+| ``multipart``          | If ``true``, ``form_enctype`` will render ``enctype="multipart/form-data"``.        |
+|                        | This only applies to the root form element.                                         |
++------------------------+-------------------------------------------------------------------------------------+
+| ``attr``               | A key-value array that will be rendered as HTML attributes on the field.            |
++------------------------+-------------------------------------------------------------------------------------+
+| ``label_attr``         | A key-value array that will be rendered as HTML attributes on the label.            |
++------------------------+-------------------------------------------------------------------------------------+
+| ``compound``           | Whether or not a field is actually a holder for a group of children fields          |
+|                        | (for example, a ``choice`` field, which is actually a group of checkboxes.          |
++------------------------+-------------------------------------------------------------------------------------+
+| ``block_prefixes``     | An array of all the names of the parent types.                                      |
++------------------------+-------------------------------------------------------------------------------------+
+| ``translation_domain`` | The domain of the translations for this form.                                       |
++------------------------+-------------------------------------------------------------------------------------+
+| ``cache_key``          | A unique key which is used for caching.                                             |
++------------------------+-------------------------------------------------------------------------------------+
+| ``data``               | The normalized data of the type.                                                    |
++------------------------+-------------------------------------------------------------------------------------+
+| ``method``             | The method of the current form (POST, GET, etc.).                                   |
++------------------------+-------------------------------------------------------------------------------------+
+| ``action``             | The action of the current form.                                                     |
++------------------------+-------------------------------------------------------------------------------------+
 
 .. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
+.. _`the Twig documentation`: http://twig.sensiolabs.org/doc/templates.html#test-operator
diff --git a/reference/forms/types/checkbox.rst b/reference/forms/types/checkbox.rst
@@ -13,6 +13,8 @@ if the box is unchecked, the value will be set to false.
 +-------------+------------------------------------------------------------------------+
 | Options     | - `value`_                                                             |
 +-------------+------------------------------------------------------------------------+
+| Variables   | - `checked`_                                                           |
++-------------+------------------------------------------------------------------------+
 | Overridden  | - `empty_data`_                                                        |
 | options     | - `compound`_                                                          |
 +-------------+------------------------------------------------------------------------+
@@ -75,3 +77,8 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/error_mapping.rst.inc
 
 .. include:: /reference/forms/types/options/mapped.rst.inc
+
+Form Variables
+--------------
+
+.. include:: /reference/forms/types/variables/check_or_radio_table.rst.inc
diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
@@ -156,3 +156,35 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/by_reference.rst.inc
+
+Field Variables
+---------------
+
++------------------------+--------------+-------------------------------------------------------------------+
+| Variable               | Type         | Usage                                                             |
++========================+==============+===================================================================+
+| multiple               | ``Boolean``  | The value of the `multiple`_ option.                              |
++------------------------+--------------+-------------------------------------------------------------------+
+| expanded               | ``Boolean``  | The value of the `expanded`_ option.                              |
++------------------------+--------------+-------------------------------------------------------------------+
+| preferred_choices      | ``array``    | A nested array containing the ``ChoiceView`` objects of           |
+|                        |              | choices which should be presented to the user with priority.      |
++------------------------+--------------+-------------------------------------------------------------------+
+| choices                | ``array``    | A nested array containing the ``ChoiceView`` objects of           |
+|                        |              | the remaining choices.                                            |
++------------------------+--------------+-------------------------------------------------------------------+
+| separator              | ``string``   | The seperator to use between choice groups.                       |
++------------------------+--------------+-------------------------------------------------------------------+
+| empty_value            | ``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.                    |
++------------------------+--------------+-------------------------------------------------------------------+
+
+.. tip::
+
+    It's significantly faster to use the :ref:`form-twig-selectedchoice` test
+    instead when using Twig.
diff --git a/reference/forms/types/collection.rst b/reference/forms/types/collection.rst
@@ -366,3 +366,13 @@ error_bubbling
 .. include:: /reference/forms/types/options/mapped.rst.inc
 
 .. include:: /reference/forms/types/options/cascade_validation.rst.inc
+
+Field Variables
+---------------
+
+============ =========== ========================================
+Variable     Type        Usage
+============ =========== ========================================
+allow_add    ``Boolean`` The value of the `allow_add`_ option.
+allow_delete ``Boolean`` The value of the `allow_delete`_ option.
+============ =========== ========================================
diff --git a/reference/forms/types/date.rst b/reference/forms/types/date.rst
@@ -154,3 +154,17 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/error_mapping.rst.inc
+
+Field Variables
+---------------
+
++--------------+------------+----------------------------------------------------------------------+
+| Variable     | Type       | Usage                                                                |
++==============+============+======================================================================+
+| widget       | ``mixed``  | The value of the `widget`_ option.                                   |
++--------------+------------+----------------------------------------------------------------------+
+| type         | ``string`` | Only present when widget is ``single_text`` and HTML5 is activated,  |
+|              |            | contains the input type to use (``datetime``, ``date`` or ``time``). |
++--------------+------------+----------------------------------------------------------------------+
+| date_pattern | ``string`` | A string with the date format to use.                                |
++--------------+------------+----------------------------------------------------------------------+
diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst
@@ -151,4 +151,16 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
+Field Variables
+---------------
+
++----------+------------+----------------------------------------------------------------------+
+| Variable | Type       | Usage                                                                |
++==========+============+======================================================================+
+| widget   | ``mixed``  | The value of the `widget`_ option.                                   |
++----------+------------+----------------------------------------------------------------------+
+| type     | ``string`` | Only present when widget is ``single_text`` and HTML5 is activated,  |
+|          |            | contains the input type to use (``datetime``, ``date`` or ``time``). |
++----------+------------+----------------------------------------------------------------------+
+
 .. _`RFC 3339`: http://tools.ietf.org/html/rfc3339
diff --git a/reference/forms/types/file.rst b/reference/forms/types/file.rst
@@ -100,3 +100,12 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 .. include:: /reference/forms/types/options/error_mapping.rst.inc
 
 .. include:: /reference/forms/types/options/mapped.rst.inc
+
+Form Variables
+--------------
+
+======== ========== ===============================================================================
+Variable Type       Usage                                       
+======== ========== ===============================================================================
+type     ``string`` The type variable is set to ``file``, in order to render as a file input field.
+======== ========== ===============================================================================