Permalink
Browse files

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
  • Loading branch information...
weaverryan committed Mar 9, 2014
2 parents 4ef746a + 7710429 commit d881181f88d090f86627a9dd7b5278a36087a63a
@@ -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
@@ -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
@@ -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.
@@ -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.
============ =========== ========================================
@@ -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. |
+--------------+------------+----------------------------------------------------------------------+
@@ -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
@@ -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.
======== ========== ===============================================================================
Oops, something went wrong.

0 comments on commit d881181

Please sign in to comment.