django/docs/ref/class-based-views/base.txt

257 lines
8.2 KiB
Plaintext

==========
Base views
==========
The following three classes provide much of the functionality needed to create
Django views. You may think of them as *parent* views, which can be used by
themselves or inherited from. They may not provide all the capabilities
required for projects, in which case there are Mixins and Generic class-based
views.
Many of Django's built-in class-based views inherit from other class-based
views or various mixins. Because this inheritance chain is very important, the
ancestor classes are documented under the section title of **Ancestors (MRO)**.
MRO is an acronym for Method Resolution Order.
View
----
.. class:: django.views.generic.base.View
The master class-based base view. All other class-based views inherit from
this base class.
**Method Flowchart**
1. :meth:`dispatch()`
2. :meth:`http_method_not_allowed()`
3. :meth:`options()`
**Example views.py**::
from django.http import HttpResponse
from django.views.generic import View
class MyView(View):
def get(self, request, *args, **kwargs):
return HttpResponse('Hello, World!')
**Example urls.py**::
from django.conf.urls import patterns, url
from myapp.views import MyView
urlpatterns = patterns('',
url(r'^mine/$', MyView.as_view(), name='my-view'),
)
**Attributes**
.. attribute:: http_method_names
The list of HTTP method names that this view will accept.
Default::
['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace']
**Methods**
.. classmethod:: as_view(**initkwargs)
Returns a callable view that takes a request and returns a response::
response = MyView.as_view()(request)
.. method:: dispatch(request, *args, **kwargs)
The ``view`` part of the view -- the method that accepts a ``request``
argument plus arguments, and returns a HTTP response.
The default implementation will inspect the HTTP method and attempt to
delegate to a method that matches the HTTP method; a ``GET`` will be
delegated to ``get()``, a ``POST`` to ``post()``, and so on.
By default, a ``HEAD`` request will be delegated to ``get()``.
If you need to handle ``HEAD`` requests in a different way than ``GET``,
you can override the ``head()`` method. See
:ref:`supporting-other-http-methods` for an example.
.. method:: http_method_not_allowed(request, *args, **kwargs)
If the view was called with a HTTP method it doesn't support, this
method is called instead.
The default implementation returns ``HttpResponseNotAllowed`` with a
list of allowed methods in plain text.
.. method:: options(request, *args, **kwargs)
Handles responding to requests for the OPTIONS HTTP verb. Returns a
list of the allowed HTTP method names for the view.
TemplateView
------------
.. class:: django.views.generic.base.TemplateView
Renders a given template, with the context containing parameters captured
in the URL.
**Ancestors (MRO)**
This view inherits methods and attributes from the following views:
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.base.ContextMixin`
* :class:`django.views.generic.base.View`
**Method Flowchart**
1. :meth:`~django.views.generic.base.View.dispatch()`
2. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
3. :meth:`~django.views.generic.base.ContextMixin.get_context_data()`
**Example views.py**::
from django.views.generic.base import TemplateView
from articles.models import Article
class HomePageView(TemplateView):
template_name = "home.html"
def get_context_data(self, **kwargs):
context = super(HomePageView, self).get_context_data(**kwargs)
context['latest_articles'] = Article.objects.all()[:5]
return context
**Example urls.py**::
from django.conf.urls import patterns, url
from myapp.views import HomePageView
urlpatterns = patterns('',
url(r'^$', HomePageView.as_view(), name='home'),
)
**Context**
* Populated (through :class:`~django.views.generic.base.ContextMixin`) with
the keyword arguments captured from the URL pattern that served the view.
RedirectView
------------
.. class:: django.views.generic.base.RedirectView
Redirects to a given URL.
The given URL may contain dictionary-style string formatting, which will be
interpolated against the parameters captured in the URL. Because keyword
interpolation is *always* done (even if no arguments are passed in), any
``"%"`` characters in the URL must be written as ``"%%"`` so that Python
will convert them to a single percent sign on output.
If the given URL is ``None``, Django will return an ``HttpResponseGone``
(410).
**Ancestors (MRO)**
This view inherits methods and attributes from the following view:
* :class:`django.views.generic.base.View`
**Method Flowchart**
1. :meth:`~django.views.generic.base.View.dispatch()`
2. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
3. :meth:`get_redirect_url()`
**Example views.py**::
from django.shortcuts import get_object_or_404
from django.views.generic.base import RedirectView
from articles.models import Article
class ArticleCounterRedirectView(RedirectView):
permanent = False
query_string = True
pattern_name = 'article-detail'
def get_redirect_url(self, *args, **kwargs):
article = get_object_or_404(Article, pk=pk)
article.update_counter()
return super(ArticleCounterRedirectView, self).get_redirect_url(*args, **kwargs)
**Example urls.py**::
from django.conf.urls import patterns, url
from django.views.generic.base import RedirectView
from article.views import ArticleCounterRedirectView, ArticleDetail
urlpatterns = patterns('',
url(r'^counter/(?P<pk>\d+)/$', ArticleCounterRedirectView.as_view(), name='article-counter'),
url(r'^details/(?P<pk>\d+)/$', ArticleDetail.as_view(), name='article-detail'),
url(r'^go-to-django/$', RedirectView.as_view(url='http://djangoproject.com'), name='go-to-django'),
)
**Attributes**
.. attribute:: url
The URL to redirect to, as a string. Or ``None`` to raise a 410 (Gone)
HTTP error.
.. attribute:: pattern_name
.. versionadded:: 1.6
The name of the URL pattern to redirect to. Reversing will be done
using the same args and kwargs as are passed in for this view.
.. attribute:: permanent
Whether the redirect should be permanent. The only difference here is
the HTTP status code returned. If ``True``, then the redirect will use
status code 301. If ``False``, then the redirect will use status code
302. By default, ``permanent`` is ``True``.
.. attribute:: query_string
Whether to pass along the GET query string to the new location. If
``True``, then the query string is appended to the URL. If ``False``,
then the query string is discarded. By default, ``query_string`` is
``False``.
**Methods**
.. method:: get_redirect_url(*args, **kwargs)
Constructs the target URL for redirection.
.. versionchanged:: 1.6
The signature of this method was changed to include ``*args``.
The default implementation uses :attr:`url` as a starting
string and performs expansion of ``%`` named parameters in that string
using the named groups captured in the URL.
If :attr:`url` is not set, ``get_redirect_url()`` tries to reverse the
:attr:`pattern_name` using what was captured in the URL (both named and
unnamed groups are used).
If requested by :attr:`query_string`, it will also append the query
string to the generated URL.
Subclasses may implement any behavior they wish, as long as the method
returns a redirect-ready URL string.