Document the ability to use multiple themes

Author: vicb

book/forms.rst

@@ -356,7 +356,7 @@ corresponding errors printed out with the form.
    a ``required`` attribute on fields that are required. For browsers that
    support HTML5, this will result in a native browser message being displayed
    if the user tries to submit the form with that field blank.
-   
+
    Generated forms take full advantage of this new feature by adding sensible
    HTML attributes that trigger the validation. The client-side validation,
    however, can be disabled by adding the ``novalidate`` attribute to the
@@ -447,13 +447,13 @@ the documentation for each type.
     that HTML5-ready browsers will apply client-side validation if the field
     is left blank. If you don't want this behavior, either set the ``required``
     option on your field to ``false`` or :ref:`disable HTML5 validation<book-forms-html5-validation-disable>`.
-    
+
     Also note that setting the ``required`` option to ``true`` will **not**
     result in server-side validation to be applied. In other words, if a
     user submits a blank value for the field (either with an old browser
     or web service, for example), it will be accepted as a valid value unless
     you use Symfony's ``NotBlank`` or ``NotNull`` validation constraint.
-    
+
     In other words, the ``required`` option is "nice", but true server-side
     validation should *always* be used.
 
@@ -532,7 +532,7 @@ the correct values of a number of field options.
   option can be guessed from the validation constrains (if ``MinLength``
   or ``Min`` is used) or from the Doctrine metadata (via the field's length).
 
-* ``max_length``: Similar to ``min_length``, the maximum length can also 
+* ``max_length``: Similar to ``min_length``, the maximum length can also
   be guessed.
 
 .. note::
@@ -614,11 +614,11 @@ output can be customized on many different levels.
 .. tip::
 
     You can access the current data of your form via ``form.vars.value``:
-    
+
     .. configuration-block::
 
         .. code-block:: jinja
-        
+
             {{ form.vars.value.task }}
 
         .. code-block:: html+php
@@ -820,15 +820,15 @@ the choice is ultimately up to you.
         }
 
 .. tip::
-    
-    When mapping forms to objects, all fields are mapped. Any fields on the 
+
+    When mapping forms to objects, all fields are mapped. Any fields on the
     form that do not exist on the mapped object will cause an exception to
     be thrown.
-    
+
     In cases where you need extra fields in the form (for example: a "do you
     agree with these terms" checkbox) that will not be mapped to the underlying
     object, you need to set the property_path option to ``false``::
-    
+
         public function buildForm(FormBuilder $builder, array $options)
         {
             $builder->add('task');
@@ -1085,6 +1085,8 @@ renders the form:
 
         {% form_theme form 'AcmeTaskBundle:Form:fields.html.twig' %}
 
+        {% form_theme form 'AcmeTaskBundle:Form:fields.html.twig' 'AcmeTaskBundle:Form:fields2.html.twig' %}
+
         <form ...>
 
     .. code-block:: html+php
@@ -1093,6 +1095,8 @@ renders the form:
 
         <?php $view['form']->setTheme($form, array('AcmeTaskBundle:Form')) ?>
 
+        <?php $view['form']->setTheme($form, array('AcmeTaskBundle:Form', 'AcmeTaskBundle:Form')) ?>
+
         <form ...>
 
 The ``form_theme`` tag (in Twig) "imports" the fragments defined in the given
@@ -1101,6 +1105,13 @@ template and uses them when rendering the form. In other words, when the
 block from your custom theme (instead of the default ``field_row`` block
 that ships with Symfony).
 
+Your custom theme does not have to override all the blocks. When rendering a block
+which is not overridden in your custom theme, the theming engine will fall back
+to the global theme (defined at the bundle level).
+
+If several custom themes are provided they will be searched in the listed order
+before falling back to the global theme.
+
 To customize any portion of a form, you just need to override the appropriate
 fragment. Knowing exactly which block or file to override is the subject of
 the next section.
@@ -1348,7 +1359,7 @@ The CSRF token can be customized on a form-by-form basis. For example::
     class TaskType extends AbstractType
     {
         // ...
-    
+
         public function getDefaultOptions(array $options)
         {
             return array(
@@ -1359,7 +1370,7 @@ The CSRF token can be customized on a form-by-form basis. For example::
                 'intention'       => 'task_item',
             );
         }
-        
+
         // ...
     }
 
@@ -1398,14 +1409,14 @@ an array of the submitted data. This is actually really easy::
             ->add('email', 'email')
             ->add('message', 'textarea')
             ->getForm();
-        
+
             if ($request->getMethod() == 'POST') {
                 $form->bindRequest($request);
 
                 // data is an array with "name", "email", and "message" keys
                 $data = $form->getData();
             }
-        
+
         // ... render the form
     }
 
@@ -1425,14 +1436,14 @@ an array.
 
 .. tip::
 
-    You can also access POST values (in this case "name") directly through 
+    You can also access POST values (in this case "name") directly through
     the request object, like so:
 
     .. code-block:: php
 
         $this->get('request')->request->get('name');
 
-    Be advised, however, that in most cases using the getData() method is 
+    Be advised, however, that in most cases using the getData() method is
     a better choice, since it returns the data (usually an object) after
     it's been transformed by the form framework.
 
@@ -1487,15 +1498,15 @@ method to specify the option::
                 'name' => new MinLength(5),
                 'email' => new Email(array('message' => 'Invalid email address')),
             ));
-        
+
             return array('validation_constraint' => $collectionConstraint);
         }
     }
 
 Now, you have the flexibility to create forms - with validation - that return
 an array of data, instead of an object. In most cases, it's better - and
 certainly more robust - to bind your form to an object. But for simple forms,
-this is a great approach. 
+this is a great approach.
 
 Final Thoughts
 --------------