[forms] Adding sections talking about form variables

Also changing the form block template to be specific to 2.0 - which will be a pain to keep up, but it's quite a bit different between the versions

Author: weaverryan

book/forms.rst

@@ -1528,6 +1528,6 @@ Learn more from the Cookbook
 .. _`Symfony2 Form Component`: https://github.com/symfony/Form
 .. _`DateTime`: http://php.net/manual/en/class.datetime.php
 .. _`Twig Bridge`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig
-.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
+.. _`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
 .. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery
 .. _`view on GitHub`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form

cookbook/form/form_customization.rst

@@ -907,4 +907,28 @@ To render a help message below a field, pass in a ``help`` variable:
 .. tip::
     See :ref:`cookbook-form-theming-methods` for how to apply this customization.
 
-.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
+Using Form Variables
+--------------------
+
+Most of the functions available for rendering different parts of a form (e.g.
+the form widget, form label, form widget, etc) also allow you to make certain
+customizations directly. Look at the following example:
+
+.. configuration-block::
+
+    .. code-block:: jinja
+
+        {# render a widget, but add a "foo" class to it #}
+        {{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}
+
+    .. code-block:: php
+
+        <!-- render a widget, but add a "foo" class to it -->
+        <?php echo $view['form']->widget($form['name'], array('attr' => array(
+            'class' => 'foo',
+        ))) ?>
+
+The array passed as the second argument contains form "variables". For
+more details about this concept in Twig, see :ref:`twig-reference-form-variables`.
+
+.. _`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

reference/forms/twig_reference.rst

@@ -23,6 +23,9 @@ label you want to display as the second argument.
     {{ form_label(form.name, 'Your Name', { 'attr': {'class': 'foo'} }) }}
     {{ form_label(form.name, null, { 'label': 'Your name', 'attr': {'class': 'foo'} }) }}
 
+See ":ref:`twig-reference-form-variables`" to learn about the ``variables``
+argument.
+
 form_errors(form.name)
 ----------------------
 
@@ -50,11 +53,11 @@ The second argument to ``form_widget`` is an array of variables. The most
 common variable is ``attr``, which is an array of HTML attributes to apply
 to the HTML widget. In some cases, certain types also have other template-related
 options that can be passed. These are discussed on a type-by-type basis.
+The ``attributes`` are not applied recursively to child fields if you're
+rendering many fields at once (e.g. ``form_widget(form)``).
 
-.. note::
-
-    In case the first argument is a form, all ``variables`` will 
-    only be applied to the form itself and not its children.
+See ":ref:`twig-reference-form-variables`" to learn more about the ``variables``
+argument.
 
 form_row(form.name, variables)
 ------------------------------
@@ -71,6 +74,9 @@ The second argument to ``form_row`` is an array of variables. The templates
 provided in Symfony only allow to override the label as shown in the example
 above.
 
+See ":ref:`twig-reference-form-variables`" to learn about the ``variables``
+argument.
+
 form_rest(form, variables)
 --------------------------
 
@@ -92,4 +98,68 @@ good idea to include this in your form tag:
 
 .. code-block:: html+jinja
 
-    <form action="{{ path('form_submit') }}" method="post" {{ form_enctype(form) }}>
+    <form action="{{ path('form_submit') }}" method="post" {{ form_enctype(form) }}>
+
+.. _`twig-reference-form-variables`:
+
+More about Form "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
+following would render the "widget" for a field, and modify its attributes
+to include a special class:
+
+.. code-block:: jinja
+
+    {# render a widget, but add a "foo" class to it #}
+    {{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}
+
+The purpose of these variables - what they do & where they come from - may
+not be immediately clear, but they're incredibly powerful. Whenever you
+render any part of a form, the block that renders it makes use of a number
+of variables. By default, these blocks live inside `form_div_layout.html.twig`_.
+
+Look at the ``generic_label`` as an example:
+
+.. code-block:: jinja
+
+    {% block generic_label %}
+        {% if required %}
+            {% set attr = attr|merge({'class': attr.class|default('') ~ ' required'}) %}
+        {% endif %}
+        <label{% for attrname,attrvalue in attr %} {{attrname}}="{{attrvalue}}"{% endfor %}>{{ label|trans }}</label>
+    {% endblock %}
+
+This block makes use of 3 variables: ``required``, ``attr`` and ``label``.
+These variables are made available by the form rendering system. But more
+importantly, these are the variables that you can override when calling ``form_label``
+(since in this example, you're rendering the label).
+
+The exact variables available to override depends on which part of the form
+you're rendering (e.g. label versus widget) and which field you're rendering
+(e.g. a ``choice`` widget has an extra ``expanded`` option). If you get comfortable
+with looking through `form_div_layout.html.twig`_, you'll always be able
+to see what options you have available.
+
+.. tip::
+
+    Behind the scenes, these variables are made available to the ``FormView``
+    object of your form when the form component calls ``buildView`` and ``buildViewBottomUp``
+    on each "node" of your form tree. To see what "view" variables a particularly
+    field has, find the source code for the form field (and its parent fields)
+    and look at the above two functions.
+
+.. note::
+
+    If you're rendering an entire form at once (or an entire embedded form),
+    the ``variables`` argument will only be applied to the form itself and
+    not its children. In other words, the following will **not** pass a "foo"
+    class attribute to all of the child fields in the form:
+
+    .. code-block:: jinja
+
+        {# does **not** work - the variables are not recursive #}
+        {{ form_widget(form, { 'attr': {'class': 'foo'} }) }}
+
+.. _`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