merged branch TomAdam/pr-choice-bc-doc (PR #5263)

Commits
-------

9e3e589 Alter upgrade notes with changes to _form_is_choice_selected twig function

Discussion
----------

Undocumented BC break - choice field type template

The upgrade notes for the choice field template are out of date. They currently state:

```
The `choices` variable now contains `ChoiceView` objects with two getters,
getValue() and getLabel(), to access the choice data.
```

However these methods do not exist. I assume this is the result of a rollback to maintain BC?

In addition to this, the `_form_is_choice_selected` twig function has been removed and replaced with a filter called `selectedchoice`. This is an undocumented BC break. I have attached an update to the notes to reflect these changes.

---------------------------------------------------------------------------

by fabpot at 2012-08-15T17:20:35Z

ping @bschussek

---------------------------------------------------------------------------

by bschussek at 2012-08-16T17:36:22Z

Looks good apart from my comment. Thanks for fixing this!

UPGRADE-2.1.md

@@ -532,11 +532,9 @@
     by default. Take care if your JavaScript relies on that. If you want to
     read the actual choice value, read the `value` attribute instead.
 
-  * In the choice field type's template, the structure of the `choices` variable
-    has changed.
-
-    The `choices` variable now contains `ChoiceView` objects with two getters,
-    `getValue()` and `getLabel()`, to access the choice data.
+  * In the choice field type's template, the `_form_is_choice_selected` method
+    used to identify a selected choice has been replaced with the `selectedchoice`
+    filter.
 
     Before:
 
@@ -551,9 +549,9 @@
     After:
 
     ```
-    {% for choice in choices %}
-        <option value="{{ choice.value }}"{% if _form_is_choice_selected(form, choice) %} selected="selected"{% endif %}>
-            {{ choice.label }}
+    {% for choice, label in choices %}
+        <option value="{{ choice }}"{% if choice is selectedchoice(form) %} selected="selected"{% endif %}>
+            {{ label }}
         </option>
     {% endfor %}
     ```