Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#13452 closed (fixed)

Document workaround for regroup tag and CHOICES fields

Reported by: shacker Owned by: nobody
Component: Documentation Version: master
Severity: Keywords: regroup, CHOICES
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

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.

Attachments (3)

regroup-choices.diff (1.5 KB) - added by shacker 5 years ago.
Document workaround for using regroup with CHOICES
regroup-choices-2.diff (1.3 KB) - added by shacker 5 years ago.
Documentation clarified
regroup-choices-3.diff (1.5 KB) - added by shacker 5 years ago.
Modified patch to be more inclusive of regroupable properties

Download all attachments as: .zip

Change History (16)

Changed 5 years ago by shacker

Document workaround for using regroup with CHOICES

comment:1 Changed 5 years ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to wontfix
  • Status changed from new to closed

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).

comment:2 Changed 5 years ago by shacker

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?

comment:3 Changed 5 years ago by russellm

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.

comment:4 Changed 5 years ago by gabrielhurley

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.

comment:5 Changed 5 years ago by shacker

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.

comment:6 Changed 5 years ago by russellm

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.

comment:7 Changed 5 years ago by shacker

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

comment:8 Changed 5 years ago by shacker

  • Resolution wontfix deleted
  • Status changed from closed to reopened

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

Changed 5 years ago by shacker

Documentation clarified

comment:9 Changed 5 years ago by russellm

  • Patch needs improvement set
  • Triage Stage changed from Unreviewed to Accepted

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.

Changed 5 years ago by shacker

Modified patch to be more inclusive of regroupable properties

comment:10 Changed 5 years ago by shacker

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

comment:11 Changed 5 years ago by timo

  • Patch needs improvement unset

comment:12 Changed 5 years ago by timo

  • Resolution set to fixed
  • Status changed from reopened to closed

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

comment:13 Changed 5 years ago by timo

(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.

Note: See TracTickets for help on using tickets.
Back to Top