Document workaround for regroup tag and CHOICES fields

[Scot Hacker]

If using regroup to group against a CHOICES field rather than a db field, xxx.grouper renders the key, rather than the value from the CHOICES set. There is no way to apply get_FOO_display() against xxx.grouper after regroup has done its thing. This patch documents the workaround.

[Scot Hacker]

Document workaround for using regroup with CHOICES

[Russell Keith-Magee]

While completely correct, I'm not sure this actually serves to clarify anything. {% regroup %} groups on an attribute. That attribute is then used as a key for displaying regrouped objects. If the key isn't useful for display, then you should have used something else as a grouping attribute

As a side note, you could get access to get_gender_display after grouping by gender using group.list.0.get_gender_display .This exploits the fact that every member in the grouper list will have the same gender (by definition), and the list must have at least 1 entry (since there is a group to be found).

[Scot Hacker]

I'm not sure I understand what you mean by "I'm not sure this actually serves to clarify anything." There is no documentation on how to address this particular use case. While an advanced user can probably figure it out on their own, an intermediate user such as myself ends up spending a long time combing mailing lists and blogs trying to find a solution. Shouldn't the documentation strive to reduce that?

[Russell Keith-Magee]

There are *many* use cases that aren't described explicitly in the documentation. The purpose of documentation shouldn't be to enumerate every possible use case. Rather, it should strive to establish the mental model that makes every possible use case obvious to all readers. An example may sometimes form part of that, but what you've proposed isn't a simple example -- it reads like it's trying to establish get_FOO_display as some sort of special case requiring special attention.

Perhaps another way to phrase the source of my rejection would be this: What is it about the existing documentation that obscured the idea of using get_gender_display as a grouping value? Looking at it from my (admittedly expert) eyes, the documentation suggests that you choose an attribute that you want to group around, and you will get a set of groups that are keyed by the values of that attribute, whose members share a common attribute value. get_gender_display() is just another attribute. If get_gender_display() provides a more meaningful grouping label than the raw gender attribute, then you should use it.

I don't see what is so special about get_FOO_display() in this case, other than the fact that it is evidently the case that caused you specific difficulty. I'm not unsympathetic to the fact that this evidently caused you some confusion, and I certainly appreciate you taking the time to make the suggestion and write up some draft text. However, I just don't see that enumerating choices/get_FOO_display() as a special case adds clarity to the docs.

If there's some sort of general clarification that can be made (and a get_gender_display()-based example may form a part of that clarification) I'm all ears -- but I want to understand and solve the general problem, not a specific example of the problem.

[Gabriel Hurley]

I think what wasn't clear to shacker was that the term "attribute" also included methods on the object. Perhaps a more generalized improvement to the docs could make it clear that methods are also valid arguments to regroup, and offer up the get_FOO_display as an example since it is a method that is commonly (automatically) added to objects.

[Scot Hacker]

In my simplistic world view, I'm not thinking about methods or attributes when solving a problem like this. I just know there's thing called get_FOO_display that turns CHOICES keys into their corresponding values in a template, and that suddenly it doesn't work as I'm accustomed.

The purpose of documentation shouldn't be to enumerate every possible use case. Rather, it should strive to establish the mental model that makes every possible use case obvious to all readers.

Thanks for clarifying that. Speaking personally, I value the working examples in the documentation hugely - they're what turn abstract principles into something I can actually accomplish. More importantly, they help with the learning process. As far as I'm concerned there should be working examples for almost *everything* in the docs, and that as many use cases as possible should be addressed. Maybe it's just me, but I think it's fair to say that as Django becomes more popular, there will be more and more users like me (i.e. part-time developers without a CS background) who are trying to pick this stuff up in the margins. Yes, I'd love to get to the point someday where things like this make intuitive sense ... but that day is a long way off. Until then, I'll let StackOverflow and other sites fill the gaps and not expect the official docs to be example-heavy.

If we do want to continue this ticket, I think gabrielhurley hits the nail on the head. I'd be happy to re-do the patch in those terms if russelm agrees.

[Russell Keith-Magee]

Gabriel's comment seems like a reasonable point of clarification; if you want to try a draft in that vein, I'm happy to look at it.

[Scot Hacker]

Thanks for being flexible on this! Attached patch simplifies and takes Gabriel's approach.

[Scot Hacker]

Hmm.. Need to re-open this to attach.

[Scot Hacker]

Documentation clarified

[Russell Keith-Magee]

Draft text isn't perfect, but it's certainly on the right track. Methods aren't the only 'special' case here - anything that is a valid template lookup is a legal grouping attribute, too. If you can do {{ object.attribute }}, you can do {% regroup object by attribute ... %}, so that means attributes, methods, dictionary keys and list items are all fair game.

[Scot Hacker]

Modified patch to be more inclusive of regroupable properties

[Scot Hacker]

Just wanted to make sure the 3rd patch I attached here had been reviewed before acceptance.

[Tim Graham]

(In [15108]) Fixed #13452 - Document that regroup can be used with any template lookup. Thanks shacker for the suggestion and draft patch.

[Tim Graham]

(In [15109]) [1.2.X] Fixed #13452 - Document that regroup can be used with any template lookup. Thanks shacker for the suggestion and draft patch.

Backport of r15108 from trunk.