mirror of https://github.com/django/django.git
298 lines
10 KiB
Plaintext
298 lines
10 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 base view class. All other class-based views inherit from this base
|
|
class. It isn't strictly a generic view and thus can also be imported from
|
|
``django.views``.
|
|
|
|
**Method Flowchart**
|
|
|
|
#. :meth:`setup()`
|
|
#. :meth:`dispatch()`
|
|
#. :meth:`http_method_not_allowed()`
|
|
#. :meth:`options()`
|
|
|
|
**Example views.py**::
|
|
|
|
from django.http import HttpResponse
|
|
from django.views import View
|
|
|
|
class MyView(View):
|
|
|
|
def get(self, request, *args, **kwargs):
|
|
return HttpResponse('Hello, World!')
|
|
|
|
**Example urls.py**::
|
|
|
|
from django.urls import path
|
|
|
|
from myapp.views import MyView
|
|
|
|
urlpatterns = [
|
|
path('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)
|
|
|
|
The returned view has ``view_class`` and ``view_initkwargs``
|
|
attributes.
|
|
|
|
When the view is called during the request/response cycle, the
|
|
:meth:`setup` method assigns the :class:`~django.http.HttpRequest` to
|
|
the view's ``request`` attribute, and any positional and/or keyword
|
|
arguments :ref:`captured from the URL pattern
|
|
<how-django-processes-a-request>` to the ``args`` and ``kwargs``
|
|
attributes, respectively. Then :meth:`dispatch` is called.
|
|
|
|
If a ``View`` subclass defines asynchronous (``async def``) method
|
|
handlers, ``as_view()`` will mark the returned callable as a coroutine
|
|
function. An ``ImproperlyConfigured`` exception will be raised if both
|
|
asynchronous (``async def``) and synchronous (``def``) handlers are
|
|
defined on a single view-class.
|
|
|
|
.. versionchanged:: 4.1
|
|
|
|
Compatibility with asynchronous (``async def``) method handlers was
|
|
added.
|
|
|
|
.. method:: setup(request, *args, **kwargs)
|
|
|
|
Performs key view initialization prior to :meth:`dispatch`.
|
|
|
|
If overriding this method, you must call ``super()``.
|
|
|
|
.. method:: dispatch(request, *args, **kwargs)
|
|
|
|
The ``view`` part of the view -- the method that accepts a ``request``
|
|
argument plus arguments, and returns an 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 an 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
|
|
response with the ``Allow`` header containing a list of the view's
|
|
allowed HTTP method names.
|
|
|
|
If the other HTTP methods handlers on the class are asynchronous
|
|
(``async def``) then the response will be wrapped in a coroutine
|
|
function for use with ``await``.
|
|
|
|
.. versionchanged:: 4.1
|
|
|
|
Compatibility with classes defining asynchronous (``async def``)
|
|
method handlers was added.
|
|
|
|
``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**
|
|
|
|
#. :meth:`~django.views.generic.base.View.setup()`
|
|
#. :meth:`~django.views.generic.base.View.dispatch()`
|
|
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
|
#. :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().get_context_data(**kwargs)
|
|
context['latest_articles'] = Article.objects.all()[:5]
|
|
return context
|
|
|
|
**Example urls.py**::
|
|
|
|
from django.urls import path
|
|
|
|
from myapp.views import HomePageView
|
|
|
|
urlpatterns = [
|
|
path('', 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.
|
|
* You can also add context using the
|
|
:attr:`~django.views.generic.base.ContextMixin.extra_context` keyword
|
|
argument for :meth:`~django.views.generic.base.View.as_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**
|
|
|
|
#. :meth:`~django.views.generic.base.View.setup()`
|
|
#. :meth:`~django.views.generic.base.View.dispatch()`
|
|
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
|
#. :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=kwargs['pk'])
|
|
article.update_counter()
|
|
return super().get_redirect_url(*args, **kwargs)
|
|
|
|
**Example urls.py**::
|
|
|
|
from django.urls import path
|
|
from django.views.generic.base import RedirectView
|
|
|
|
from article.views import ArticleCounterRedirectView, ArticleDetailView
|
|
|
|
urlpatterns = [
|
|
path('counter/<int:pk>/', ArticleCounterRedirectView.as_view(), name='article-counter'),
|
|
path('details/<int:pk>/', ArticleDetailView.as_view(), name='article-detail'),
|
|
path('go-to-django/', RedirectView.as_view(url='https://www.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
|
|
|
|
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 ``False``.
|
|
|
|
.. 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.
|
|
|
|
The ``args`` and ``kwargs`` arguments are positional and/or keyword
|
|
arguments :ref:`captured from the URL pattern
|
|
<how-django-processes-a-request>`, respectively.
|
|
|
|
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.
|