Opened 9 years ago
Closed 9 years ago
#24458 closed Cleanup/optimization (worksforme)
Documentation often overlooks class-based views
| Reported by: | Daniel Quinn | Owned by: | Daniel Quinn |
|---|---|---|---|
| Component: | Documentation | Version: | 1.7 |
| Severity: | Normal | Keywords: | |
| Cc: | Triage Stage: | Accepted | |
| Has patch: | no | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | yes | UI/UX: | no |
Description
While the explanation of what CBVs are and why we use them is concise, there isn't much in the way of covering how to use them with different components in Django. Many examples show only how to use a feature with function-based views, with no explanation as to how this would translate to CBVs. Below I've listed some sections that could use some attention:
- https://docs.djangoproject.com/en/1.7/topics/http/sessions/#setting-test-cookies
- https://docs.djangoproject.com/en/1.7/topics/http/sessions/#examples
- https://docs.djangoproject.com/en/1.7/topics/auth/default/#the-login-required-decorator
- https://docs.djangoproject.com/en/1.7/topics/cache/#the-per-view-cache
- https://docs.djangoproject.com/en/1.7/topics/cache/#using-vary-headers
- https://docs.djangoproject.com/en/1.7/topics/cache/#controlling-cache-using-other-headers
- https://docs.djangoproject.com/en/1.7/topics/pagination/#using-paginator-in-a-view
- https://docs.djangoproject.com/en/1.7/topics/conditional-view-processing/#the-condition-decorator
Change History (6)
comment:1 by , 9 years ago
| Owner: | changed from to |
|---|---|
| Status: | new → assigned |
follow-up: 3 comment:2 by , 9 years ago
| Triage Stage: | Unreviewed → Accepted |
|---|---|
| Type: | Uncategorized → Cleanup/optimization |
comment:3 by , 9 years ago
I agree, this would be preferable. Should it just be an addendum to the existing "Class Based Views" page, or something separate?
comment:4 by , 9 years ago
Actually, now that I look at the CBV docs, there appears to be everything covered there, it just wasn't immediately obvious from the URLs above where I needed to look to do things like use @login_required in a CBV. Maybe it's just a question of prioritising function-based over class-based, and that's fine if that's the case, but some way to point to these docs when referencing things like decorators would be handy.
comment:5 by , 9 years ago
Yea, not sure. It seems a bit annoying to link to that doc on every decorator, but maybe it could be done tastefully.
comment:6 by , 9 years ago
| Resolution: | → worksforme |
|---|---|
| Status: | assigned → closed |
Feel free to reopen if you want to provide a patch. Not sure it's terribly high priority.
Hopefully we can do this in a way that doesn't require two examples for every case. Maybe a more general "translating between function and class-based views" overview would be useful.