Ticket #13452: regroup-choices-3.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

@@ -825 +825 @@
 
     {% regroup people|dictsort:"gender" by gender as gender_list %}
 
+
+Grouping on other properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Any valid template lookup is a legal grouping attribute for the regroup 
+tag, including methods, attributes, dictionary keys and list items. For 
+example, if the "gender" field is a foreign key to a class with
+an attribute "description," you could use::
+
+    {% regroup people by gender.description as gender_list %}
+
+Or, if the "gender" field is a CHOICES field rather than a foreign key, 
+it will naturally have a :ref:`get_FOO_display() 
+<extra-instance-methods>` method available as an attribute, allowing 
+you to group on the display string rather than the CHOICES key::
+
+    {% 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