Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

[DO NOT MERGE] #19898 - Document why/when of class-based views #840

Closed
wants to merge 10 commits into
from

Conversation

Projects
None yet
7 participants

Beginning the pull request early for documentation updates for class-based views.

Currently:

  • I've written out some thoughts that I think are important to express on the front topic page, but I need to do some work so weave this new content into the rest of the page better (i.e., make sure there's no overlap/repetition)
  • Currently working on the usage-patterns page that will hopefully demonstrate the ideas stated in this new topic front-page material.

@carljm carljm commented on the diff Feb 25, 2013

docs/topics/class-based-views/usage-patterns.txt
+
+When is it useful to depart from function based views and trade simple
+flow-control for modularity? The following usage patterns attempt to
+demonstrate cases where this makes sense.
+
+Usage patterns documented elsewhere:
+ * :doc:`Generic display</topics/class-based-views/generic-display>`
+ * :doc:`Generic editing</topics/class-based-views/generic-editing>`
+
+Each of the usage examples below demonstrates specific benefits of class-based
+views. It is implied that all of the examples demonstrate composition of
+featuers into views.
+
+
+
+Requiring authenticated user or super-user
@carljm

carljm Feb 25, 2013

Owner

I think this is a poor choice of usage pattern, as it can be handled so much more straightforwardly using a decorator on a function view. It may be useful to document how to do something similar with class-based views, but a cross-cutting concern that is easy to implement as a decorator should not be put forward as a reason to use CBVs.

@estebistec

estebistec Feb 26, 2013

yeah, I can pull these simpler ones. Hopefully my testing section gives people a better idea for their choices at that level anyway. I'm still gathering good examples of more complex views, but there's a fine line at the other end too where at a certain complexity, the code just needs to be not in the view.

I think that, to complete this page, I'm going to need to take feedback from the community somehow. Even if I can come up with my own great examples, they're simply my own patterns but I'd prefer to gather more and validate patterns with wider usage.

@carljm carljm commented on the diff Feb 25, 2013

docs/topics/class-based-views/index.txt
+high-level methods that do easy-to-understand things, like
+:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()`.
+Then there are specialized methods that let you hook into that "template method"
+such as
+:meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data()`
+(which is a more commonly extended method).
+
+When should I use class-based views?
+====================================
+
+The :doc:`usage patterns</topics/class-based-views/usage-patterns>` should help
+you draw a useful comparison, but here are some questions that may help guide
+you:
+
+#. Is your view supported by a generic view?
+#. Do you have a function-based view that is greater than 20-30 lines of code?
@carljm

carljm Feb 25, 2013

Owner

I think this documentation needs to mention that in many cases if your view is complex you will be better served to figure out whether some parts of the view can or should be moved into supporting objects (models, forms, viewmodels), rather than choosing a more complex structure for your view itself.

@estebistec

estebistec Feb 26, 2013

Yeah, that's fair. Basically explain that the decision tree is not just types of views to write, but that there are other places you should push logic to.

Owner

timgraham commented Oct 17, 2013

I'm going to close this for now due to inactivity and the fact that it doesn't appear to be ready for merge given the [DO NOT MERGE] tag. Feel free to open a new PR when you are ready for more feedback. Thanks!

@timgraham timgraham closed this Oct 17, 2013

yeah, once I got into this I discovered I needed to gather more/better examples, as many of my own may be more preferential where Django would still recommend function views.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment