Ticket #13452: regroup-choices.diff

docs/ref/models/instances.txt

@@ -515 +515 @@
 More details on named URL patterns are in the :ref:`URL dispatch documentation
 <topics-http-urls>`.
 
+.. _extra-instance-methods:
+
 Extra instance methods
 ======================
 

docs/ref/templates/builtins.txt

@@ -818 +818 @@
 
     {% regroup people|dictsort:"gender" by gender as gender_list %}
 
+Regroup and CHOICES fields
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the "gender" field on the model in this example is a CHOICES field
+rather than a foreign key, ``{{ gender.grouper }}`` will display the
+choice's keys, rather than its values. Normally one would correct this
+by using the :ref:`get_FOO_display() <extra-instance-methods>` method
+to return the value. However, this does not work as one might expect
+after regroup has processed the data -- it will no longer be possible
+to get at the value string. The solution is to apply
+``get_FOO_display()`` against the *input* of regroup, rather than the
+output. So call regroup like this instead::
+
+    {% regroup people by get_gender_display as gender_list %}
+
+``{{ gender.grouper }}`` will now display the value fields from the
+CHOICES set rather than the keys.
+
+
 .. templatetag:: spaceless
 
 spaceless