symfony · fabpot · Apr 27, 2012 · Apr 20, 2012 · Apr 20, 2012 · Apr 20, 2012
diff --git a/UPGRADE-2.1.md b/UPGRADE-2.1.md
@@ -102,7 +102,7 @@
     ```
   * The custom factories for the firewall configuration are now
     registered during the build method of bundles instead of being registered
-    by the end-user. This means that you will you need to remove the 'factories' 
+    by the end-user. This means that you will you need to remove the 'factories'
     keys in your security configuration.
 
   * The Firewall listener is now registered after the Router listener. This
@@ -313,29 +313,29 @@
         return isset($options['widget']) && 'single_text' === $options['widget'] ? 'text' : 'choice';
     }
     ```
-    
+
   * The methods `getDefaultOptions()` and `getAllowedOptionValues()` of form
     types no longer receive an option array.
-    
+
     You can specify options that depend on other options using closures instead.
-    
+
     Before:
-    
+
     ```
     public function getDefaultOptions(array $options)
     {
         $defaultOptions = array();
-        
+
         if ($options['multiple']) {
             $defaultOptions['empty_data'] = array();
         }
-        
+
         return $defaultOptions;
     }
     ```
-    
+
     After:
-    
+
     ```
     public function getDefaultOptions()
     {
@@ -346,7 +346,7 @@
         );
     }
     ```
-    
+
     The second argument `$previousValue` does not have to be specified if not
     needed.
 
@@ -366,29 +366,92 @@
     (or any other of the BIND events). In case you used the CallbackValidator
     class, you should now pass the callback directly to `addEventListener`.
 
-  * simplified CSRF protection and removed the csrf type
+  * Since FormType and FieldType were merged, you need to adapt your form
+    themes.
+
+    The "field_widget" and all references to it should be renamed to
+    "form_widget_single_control":
+
+    Before:
+
+    ```
+    {% block url_widget %}
+    {% spaceless %}
+        {% set type = type|default('url') %}
+        {{ block('field_widget') }}
+    {% endspaceless %}
+    {% endblock url_widget %}
+    ```
+
+    After:
+
+    ```
+    {% block url_widget %}
+    {% spaceless %}
+        {% set type = type|default('url') %}
+        {{ block('form_widget_single_control') }}
+    {% endspaceless %}
+    {% endblock url_widget %}
+    ```
+
+    All other "field_*" blocks and references to them should be renamed to
+    "form_*". If you previously defined both a "field_*" and a "form_*"
+    block, you can merge them into a single "form_*" block and check the new
+    Boolean variable "single_control":
+
+    Before:
+
+    ```
+    {% block form_errors %}
+    {% spaceless %}
+        ... form code ...
+    {% endspaceless %}
+    {% endblock form_errors %}
 
-  * deprecated FieldType and merged it into FormType
+    {% block field_errors %}
+    {% spaceless %}
+        ... field code ...
+    {% endspaceless %}
+    {% endblock field_errors %}
+    ```
+
+    After:
+
+    ```
+    {% block form_errors %}
+    {% spaceless %}
+        {% if single_control %}
+            ... field code ...
+        {% else %}
+            ... form code ...
+        {% endif %}
+    {% endspaceless %}
+    {% endblock form_errors %}
+    ```
+
+    Furthermore, the block "generic_label" was merged into "form_label". You
+    should now override "form_label" in order to customize labels.
+
+    Last but not least, the block "widget_choice_options" was renamed to
+    "choice_widget_options" to be consistent with the rest of the default
+    theme.
 
-  * [BC BREAK] renamed "field_*" theme blocks to "form_*" and "field_widget" to
-    "input"
-
   * The method `guessMinLength()` of FormTypeGuesserInterface was deprecated
     and will be removed in Symfony 2.3. You should use the new method
     `guessPattern()` instead which may return any regular expression that
     is inserted in the HTML5 attribute "pattern".
-    
+
     Before:
-    
+
     public function guessMinLength($class, $property)
     {
         if (/* condition */) {
             return new ValueGuess($minLength, Guess::LOW_CONFIDENCE);
         }
     }
-    
+
     After:
-    
+
     public function guessPattern($class, $property)
     {
         if (/* condition */) {
@@ -470,7 +533,7 @@
     `validate` and its return value was dropped.
 
     `ConstraintValidator` still contains the deprecated `isValid` method and
-    forwards `validate` calls to `isValid` by default. This BC layer will be 
+    forwards `validate` calls to `isValid` by default. This BC layer will be
     removed in Symfony 2.3. You are advised to rename your methods. You should
     also remove the return values, which have never been used by the framework.
 
@@ -500,7 +563,7 @@
             $this->context->addViolation($constraint->message, array(
                 '{{ value }}' => $value,
             ));
-            
+
             return;
         }
     }