mirror of https://github.com/django/django.git
Fixed #18804 - Reorganized class based views docs a bit; thanks anthonyb for the initial patch.
This commit is contained in:
Tim Graham
parent
01b9c3d519
commit
df7c1a13a0
|
|
@ -11,8 +11,7 @@ to structure your views and reuse code by harnessing inheritance and
|
|||
mixins. There are also some generic views for simple tasks which we'll
|
||||
get to later, but you may want to design your own structure of
|
||||
reusable views which suits your use case. For full details, see the
|
||||
:doc:`class-based views reference
|
||||
documentation</ref/class-based-views/index>`.
|
||||
:doc:`class-based views reference documentation</ref/class-based-views/index>`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
@ -32,19 +31,35 @@ redirect, and :class:`~django.views.generic.base.TemplateView` extends the base
|
|||
to make it also render a template.
|
||||
|
||||
|
||||
Simple usage
|
||||
============
|
||||
Simple usage in your URLconf
|
||||
============================
|
||||
|
||||
Class-based generic views (and any class-based views that inherit from
|
||||
the base classes Django provides) can be configured in two
|
||||
ways: subclassing, or passing in arguments directly in the URLconf.
|
||||
The simplest way to use generic views is to create them directly in your
|
||||
URLconf. If you're only changing a few simple attributes on a class-based view,
|
||||
you can simply pass them into the ``as_view`` method call itself::
|
||||
|
||||
When you subclass a class-based view, you can override attributes
|
||||
(such as the ``template_name``) or methods (such as ``get_context_data``)
|
||||
in your subclass to provide new values or methods. Consider, for example,
|
||||
a view that just displays one template, ``about.html``. Django has a
|
||||
generic view to do this - :class:`~django.views.generic.base.TemplateView` -
|
||||
so we can just subclass it, and override the template name::
|
||||
from django.conf.urls import patterns, url, include
|
||||
from django.views.generic import TemplateView
|
||||
|
||||
urlpatterns = patterns('',
|
||||
(r'^about/', TemplateView.as_view(template_name="about.html")),
|
||||
)
|
||||
|
||||
Any arguments given will override the ``template_name`` on the
|
||||
A similar overriding pattern can be used for the ``url`` attribute on
|
||||
:class:`~django.views.generic.base.RedirectView`.
|
||||
|
||||
|
||||
Subclassing generic views
|
||||
=========================
|
||||
|
||||
The second, more powerful way to use generic views is to inherit from an
|
||||
existing view and override attributes (such as the ``template_name``) or
|
||||
methods (such as ``get_context_data``) in your subclass to provide new values
|
||||
or methods. Consider, for example, a view that just displays one template,
|
||||
``about.html``. Django has a generic view to do this -
|
||||
:class:`~django.views.generic.base.TemplateView` - so we can just subclass it,
|
||||
and override the template name::
|
||||
|
||||
# some_app/views.py
|
||||
from django.views.generic import TemplateView
|
||||
|
|
@ -52,9 +67,10 @@ so we can just subclass it, and override the template name::
|
|||
class AboutView(TemplateView):
|
||||
template_name = "about.html"
|
||||
|
||||
Then, we just need to add this new view into our URLconf. As the class-based
|
||||
views themselves are classes, we point the URL to the ``as_view`` class method
|
||||
instead, which is the entry point for class-based views::
|
||||
Then we just need to add this new view into our URLconf.
|
||||
`~django.views.generic.base.TemplateView` is a class, not a function, so we
|
||||
point the URL to the ``as_view`` class method instead, which provides a
|
||||
function-like entry to class-based views::
|
||||
|
||||
# urls.py
|
||||
from django.conf.urls import patterns, url, include
|
||||
|
|
@ -64,104 +80,6 @@ instead, which is the entry point for class-based views::
|
|||
(r'^about/', AboutView.as_view()),
|
||||
)
|
||||
|
||||
Alternatively, if you're only changing a few simple attributes on a
|
||||
class-based view, you can simply pass the new attributes into the ``as_view``
|
||||
method call itself::
|
||||
|
||||
from django.conf.urls import patterns, url, include
|
||||
from django.views.generic import TemplateView
|
||||
|
||||
urlpatterns = patterns('',
|
||||
(r'^about/', TemplateView.as_view(template_name="about.html")),
|
||||
)
|
||||
|
||||
A similar overriding pattern can be used for the ``url`` attribute on
|
||||
:class:`~django.views.generic.base.RedirectView`.
|
||||
|
||||
.. _jsonresponsemixin-example:
|
||||
|
||||
More than just HTML
|
||||
-------------------
|
||||
|
||||
Where class based views shine is when you want to do the same thing many times.
|
||||
Suppose you're writing an API, and every view should return JSON instead of
|
||||
rendered HTML.
|
||||
|
||||
We can create a mixin class to use in all of our views, handling the
|
||||
conversion to JSON once.
|
||||
|
||||
For example, a simple JSON mixin might look something like this::
|
||||
|
||||
import json
|
||||
from django.http import HttpResponse
|
||||
|
||||
class JSONResponseMixin(object):
|
||||
"""
|
||||
A mixin that can be used to render a JSON response.
|
||||
"""
|
||||
response_class = HttpResponse
|
||||
|
||||
def render_to_response(self, context, **response_kwargs):
|
||||
"""
|
||||
Returns a JSON response, transforming 'context' to make the payload.
|
||||
"""
|
||||
response_kwargs['content_type'] = 'application/json'
|
||||
return self.response_class(
|
||||
self.convert_context_to_json(context),
|
||||
**response_kwargs
|
||||
)
|
||||
|
||||
def convert_context_to_json(self, context):
|
||||
"Convert the context dictionary into a JSON object"
|
||||
# Note: This is *EXTREMELY* naive; in reality, you'll need
|
||||
# to do much more complex handling to ensure that arbitrary
|
||||
# objects -- such as Django model instances or querysets
|
||||
# -- can be serialized as JSON.
|
||||
return json.dumps(context)
|
||||
|
||||
Now we mix this into the base TemplateView::
|
||||
|
||||
from django.views.generic import TemplateView
|
||||
|
||||
class JSONView(JSONResponseMixin, TemplateView):
|
||||
pass
|
||||
|
||||
Equally we could use our mixin with one of the generic views. We can make our
|
||||
own version of :class:`~django.views.generic.detail.DetailView` by mixing
|
||||
:class:`JSONResponseMixin` with the
|
||||
:class:`~django.views.generic.detail.BaseDetailView` -- (the
|
||||
:class:`~django.views.generic.detail.DetailView` before template
|
||||
rendering behavior has been mixed in)::
|
||||
|
||||
class JSONDetailView(JSONResponseMixin, BaseDetailView):
|
||||
pass
|
||||
|
||||
This view can then be deployed in the same way as any other
|
||||
:class:`~django.views.generic.detail.DetailView`, with exactly the
|
||||
same behavior -- except for the format of the response.
|
||||
|
||||
If you want to be really adventurous, you could even mix a
|
||||
:class:`~django.views.generic.detail.DetailView` subclass that is able
|
||||
to return *both* HTML and JSON content, depending on some property of
|
||||
the HTTP request, such as a query argument or a HTTP header. Just mix
|
||||
in both the :class:`JSONResponseMixin` and a
|
||||
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`,
|
||||
and override the implementation of :func:`render_to_response()` to defer
|
||||
to the appropriate subclass depending on the type of response that the user
|
||||
requested::
|
||||
|
||||
class HybridDetailView(JSONResponseMixin, SingleObjectTemplateResponseMixin, BaseDetailView):
|
||||
def render_to_response(self, context):
|
||||
# Look for a 'format=json' GET argument
|
||||
if self.request.GET.get('format','html') == 'json':
|
||||
return JSONResponseMixin.render_to_response(self, context)
|
||||
else:
|
||||
return SingleObjectTemplateResponseMixin.render_to_response(self, context)
|
||||
|
||||
Because of the way that Python resolves method overloading, the local
|
||||
``render_to_response()`` implementation will override the versions provided by
|
||||
:class:`JSONResponseMixin` and
|
||||
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
|
||||
|
||||
For more information on how to use the built in generic views, consult the next
|
||||
topic on :doc:`generic class based views</topics/class-based-views/generic-display>`.
|
||||
|
|
@ -171,16 +89,15 @@ Decorating class-based views
|
|||
|
||||
.. highlightlang:: python
|
||||
|
||||
The extension of class-based views isn't limited to using mixins. You
|
||||
can use also use decorators.
|
||||
Since class-based views aren't functions, decorating them works differently
|
||||
depending on if you're using ``as_view`` or creating a subclass.
|
||||
|
||||
Decorating in URLconf
|
||||
---------------------
|
||||
|
||||
The simplest way of decorating class-based views is to decorate the
|
||||
result of the :meth:`~django.views.generic.base.View.as_view` method.
|
||||
The easiest place to do this is in the URLconf where you deploy your
|
||||
view::
|
||||
The easiest place to do this is in the URLconf where you deploy your view::
|
||||
|
||||
from django.contrib.auth.decorators import login_required, permission_required
|
||||
from django.views.generic import TemplateView
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ interface to working with templates in class-based views.
|
|||
add more members to the dictionary.
|
||||
|
||||
Building up Django's generic class-based views
|
||||
===============================================
|
||||
==============================================
|
||||
|
||||
Let's look at how two of Django's generic class-based views are built
|
||||
out of mixins providing discrete functionality. We'll consider
|
||||
|
|
@ -222,8 +222,7 @@ we'll want the functionality provided by
|
|||
:class:`~django.views.generic.detail.SingleObjectMixin`.
|
||||
|
||||
We'll demonstrate this with the publisher modelling we used in the
|
||||
:doc:`generic class-based views
|
||||
introduction<generic-display>`.
|
||||
:doc:`generic class-based views introduction<generic-display>`.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
|
@ -256,9 +255,7 @@ we're interested in, which it just does with a simple call to
|
|||
``self.get_object()``. Everything else is taken care of for us by the
|
||||
mixin.
|
||||
|
||||
We can hook this into our URLs easily enough:
|
||||
|
||||
.. code-block:: python
|
||||
We can hook this into our URLs easily enough::
|
||||
|
||||
# urls.py
|
||||
from books.views import RecordInterest
|
||||
|
|
@ -294,8 +291,6 @@ object. In order to do this, we need to have two different querysets:
|
|||
We'll figure that out ourselves in :meth:`get_queryset()` so we
|
||||
can take into account the Publisher we're looking at.
|
||||
|
||||
.. highlightlang:: python
|
||||
|
||||
.. note::
|
||||
|
||||
We have to think carefully about :meth:`get_context_data()`.
|
||||
|
|
@ -428,9 +423,9 @@ code so that on ``POST`` the form gets called appropriately.
|
|||
the views implement :meth:`get()`, and things would get much more
|
||||
confusing.
|
||||
|
||||
Our new :class:`AuthorDetail` looks like this:
|
||||
.. highlightlang:: python
|
||||
|
||||
.. code-block:: python
|
||||
Our new :class:`AuthorDetail` looks like this::
|
||||
|
||||
# CAUTION: you almost certainly do not want to do this.
|
||||
# It is provided as part of a discussion of problems you can
|
||||
|
|
@ -603,3 +598,88 @@ This approach can also be used with any other generic class-based
|
|||
views or your own class-based views inheriting directly from
|
||||
:class:`View` or :class:`TemplateView`, as it keeps the different
|
||||
views as separate as possible.
|
||||
|
||||
.. _jsonresponsemixin-example:
|
||||
|
||||
More than just HTML
|
||||
===================
|
||||
|
||||
Where class based views shine is when you want to do the same thing many times.
|
||||
Suppose you're writing an API, and every view should return JSON instead of
|
||||
rendered HTML.
|
||||
|
||||
We can create a mixin class to use in all of our views, handling the
|
||||
conversion to JSON once.
|
||||
|
||||
For example, a simple JSON mixin might look something like this::
|
||||
|
||||
import json
|
||||
from django.http import HttpResponse
|
||||
|
||||
class JSONResponseMixin(object):
|
||||
"""
|
||||
A mixin that can be used to render a JSON response.
|
||||
"""
|
||||
response_class = HttpResponse
|
||||
|
||||
def render_to_response(self, context, **response_kwargs):
|
||||
"""
|
||||
Returns a JSON response, transforming 'context' to make the payload.
|
||||
"""
|
||||
response_kwargs['content_type'] = 'application/json'
|
||||
return self.response_class(
|
||||
self.convert_context_to_json(context),
|
||||
**response_kwargs
|
||||
)
|
||||
|
||||
def convert_context_to_json(self, context):
|
||||
"Convert the context dictionary into a JSON object"
|
||||
# Note: This is *EXTREMELY* naive; in reality, you'll need
|
||||
# to do much more complex handling to ensure that arbitrary
|
||||
# objects -- such as Django model instances or querysets
|
||||
# -- can be serialized as JSON.
|
||||
return json.dumps(context)
|
||||
|
||||
Now we mix this into the base TemplateView::
|
||||
|
||||
from django.views.generic import TemplateView
|
||||
|
||||
class JSONView(JSONResponseMixin, TemplateView):
|
||||
pass
|
||||
|
||||
Equally we could use our mixin with one of the generic views. We can make our
|
||||
own version of :class:`~django.views.generic.detail.DetailView` by mixing
|
||||
:class:`JSONResponseMixin` with the
|
||||
:class:`~django.views.generic.detail.BaseDetailView` -- (the
|
||||
:class:`~django.views.generic.detail.DetailView` before template
|
||||
rendering behavior has been mixed in)::
|
||||
|
||||
class JSONDetailView(JSONResponseMixin, BaseDetailView):
|
||||
pass
|
||||
|
||||
This view can then be deployed in the same way as any other
|
||||
:class:`~django.views.generic.detail.DetailView`, with exactly the
|
||||
same behavior -- except for the format of the response.
|
||||
|
||||
If you want to be really adventurous, you could even mix a
|
||||
:class:`~django.views.generic.detail.DetailView` subclass that is able
|
||||
to return *both* HTML and JSON content, depending on some property of
|
||||
the HTTP request, such as a query argument or a HTTP header. Just mix
|
||||
in both the :class:`JSONResponseMixin` and a
|
||||
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`,
|
||||
and override the implementation of :func:`render_to_response()` to defer
|
||||
to the appropriate subclass depending on the type of response that the user
|
||||
requested::
|
||||
|
||||
class HybridDetailView(JSONResponseMixin, SingleObjectTemplateResponseMixin, BaseDetailView):
|
||||
def render_to_response(self, context):
|
||||
# Look for a 'format=json' GET argument
|
||||
if self.request.GET.get('format','html') == 'json':
|
||||
return JSONResponseMixin.render_to_response(self, context)
|
||||
else:
|
||||
return SingleObjectTemplateResponseMixin.render_to_response(self, context)
|
||||
|
||||
Because of the way that Python resolves method overloading, the local
|
||||
``render_to_response()`` implementation will override the versions provided by
|
||||
:class:`JSONResponseMixin` and
|
||||
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue