Skip to content

Documented all form variables #3588

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 15 commits into from
Mar 9, 2014
Merged

Documented all form variables #3588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
d2b57be
Documented missing FormType variables
wouterj Feb 18, 2014
98e828f
Documented checked variable
wouterj Feb 18, 2014
c8a44ae
Documented choice variables
wouterj Feb 18, 2014
7d10315
Documented selectedchoice test
wouterj Feb 18, 2014
754da30
Added performance tip
wouterj Feb 18, 2014
3bfdc20
Documented CollectionType variables
wouterj Feb 18, 2014
95540ca
Documented Date(Time)Type variables
wouterj Feb 18, 2014
1a1497c
Extracted duplicated var tables
wouterj Feb 18, 2014
e5fded9
Documented date_pattern variable of DateType
wouterj Feb 18, 2014
a811833
Documented FileType variables
wouterj Feb 18, 2014
688409e
Documented MoneyType variables
wouterj Feb 18, 2014
8b5ecf9
Documented SubmitType variables
wouterj Feb 18, 2014
97d216d
Documented TimeType variables
wouterj Feb 18, 2014
398d23f
Applied comments by @xabbuh
wouterj Feb 19, 2014
7710429
Made full stop usage consistent
wouterj Feb 19, 2014
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
121 changes: 79 additions & 42 deletions reference/forms/twig_reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
7 changes: 7 additions & 0 deletions reference/forms/types/checkbox.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`_ |
+-------------+------------------------------------------------------------------------+
Expand Down Expand Up @@ -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
32 changes: 32 additions & 0 deletions reference/forms/types/choice.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
10 changes: 10 additions & 0 deletions reference/forms/types/collection.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
============ =========== ========================================
14 changes: 14 additions & 0 deletions reference/forms/types/date.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
+--------------+------------+----------------------------------------------------------------------+
12 changes: 12 additions & 0 deletions reference/forms/types/datetime.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
9 changes: 9 additions & 0 deletions reference/forms/types/file.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
======== ========== ===============================================================================
Loading