From 7a124d827f45784b911a50878bd94527c201e1bc Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Mon, 18 Feb 2013 20:35:32 -0600 Subject: [PATCH 1/2] [#1039] Adding a reference section for the global twig variables --- reference/forms/twig_reference.rst | 67 ++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 4 deletions(-) diff --git a/reference/forms/twig_reference.rst b/reference/forms/twig_reference.rst index d37123a4249..1301d85b24b 100644 --- a/reference/forms/twig_reference.rst +++ b/reference/forms/twig_reference.rst @@ -1,8 +1,23 @@ .. index:: single: Forms; Twig form function reference -Twig Template Form Function Reference -===================================== +Twig Template Form Function and Variable Reference +================================================== + +When working with forms in a template, there are two powerful things at your +disposal: + +* :ref:`Functions` for rendering each part of a form +* :ref:`Variables` for getting *any* information about any field + +You'll use functions often to render your fields. Variables, on the other +hand, are less commonly-used, but infinitely powerful since you can access +a fields label, id attribute, errors, and anything else about the field. + +.. _reference-form-twig-functions: + +Form Rendering Functions +------------------------ This reference manual covers all the possible Twig functions available for rendering forms. There are several different functions available, and each @@ -114,8 +129,10 @@ good idea to include this in your form tag: .. _`twig-reference-form-variables`: -More about Form "Variables" ---------------------------- +More about Form Variables +------------------------- + +For a full list of variables, see: :ref:`reference-form-twig-variables`. In almost every Twig function above, the final argument is an array of "variables" that are used when rendering that one part of the form. For example, the @@ -174,4 +191,46 @@ to see what options you have available. {# does **not** work - the variables are not recursive #} {{ form_widget(form, { 'attr': {'class': 'foo'} }) }} +.. _reference-form-twig-variables: + +Form Variables Reference +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following variables are common to every field type. Certain field types +may have even more variables and some variables here only really apply to +certain types. + ++-----------------+-----------------------------------------------------------------------------------------+ +| 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 | ++-----------------+-----------------------------------------------------------------------------------------+ +| ``value`` | The value that will be used when rendering (commonly the ``value`` HTML attribute) | ++-----------------+-----------------------------------------------------------------------------------------+ +| ``read_only`` | 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 parent form element. | ++-----------------+-----------------------------------------------------------------------------------------+ +| ``attr`` | A key-value array that will be rendered as HTML attributes on the field | ++-----------------+-----------------------------------------------------------------------------------------+ + .. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/2.0/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig From b774bc2fa471a1d9acb8f8378b25de6114e37d29 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 23 Feb 2013 07:35:07 -0800 Subject: [PATCH 2/2] [#1039] Tweaks thanks to @stof and @WouterJ --- reference/forms/twig_reference.rst | 27 +++++++++++++++++++++++++-- reference/map.rst.inc | 2 +- 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/reference/forms/twig_reference.rst b/reference/forms/twig_reference.rst index 1301d85b24b..ba8d8fa88ef 100644 --- a/reference/forms/twig_reference.rst +++ b/reference/forms/twig_reference.rst @@ -132,7 +132,9 @@ good idea to include this in your form tag: More about Form Variables ------------------------- -For a full list of variables, see: :ref:`reference-form-twig-variables`. +.. tip:: + + For a full list of variables, see: :ref:`reference-form-twig-variables`. In almost every Twig function above, the final argument is an array of "variables" that are used when rendering that one part of the form. For example, the @@ -200,6 +202,27 @@ The following variables are common to every field type. Certain field types may have even more variables and some variables here only really apply to certain types. +Assuming you have a ``form`` variable in your template, and you want to reference +the variables on the ``name`` field, accessing the variables is done by using +a public ``vars`` property on the :class:`Symfony\\Component\\Form\\FormView` +object: + +.. configuration-block:: + + .. code-block:: html+jinja + + + + .. code-block:: html+php + + + +-----------------+-----------------------------------------------------------------------------------------+ | Variable | Usage | +=================+=========================================================================================+ @@ -228,7 +251,7 @@ certain types. | ``label`` | The string label that will be rendered | +-----------------+-----------------------------------------------------------------------------------------+ | ``multipart`` | If ``true``, ``form_enctype`` will render ``enctype="multipart/form-data"``. | -| | This only applies to the parent form element. | +| | This only applies to the root form element. | +-----------------+-----------------------------------------------------------------------------------------+ | ``attr`` | A key-value array that will be rendered as HTML attributes on the field | +-----------------+-----------------------------------------------------------------------------------------+ diff --git a/reference/map.rst.inc b/reference/map.rst.inc index 9801e7991b8..d037c1216bb 100755 --- a/reference/map.rst.inc +++ b/reference/map.rst.inc @@ -18,7 +18,7 @@ * :doc:`Form Field Type Reference` * :doc:`Validation Constraints Reference ` - * :doc:`Twig Template Function Reference` + * :doc:`Twig Template Function and Variable Reference` * :doc:`Twig Extensions (forms, filters, tags, etc) Reference`