| 1 |
============================== |
| 2 |
Built-in class-based views API |
| 3 |
============================== |
| 4 |
|
| 5 |
Class-based views API reference. For introductory material, see the |
| 6 |
:doc:`/topics/class-based-views/index` topic guide. |
| 7 |
|
| 8 |
.. toctree:: |
| 9 |
:maxdepth: 3 |
| 10 |
|
| 11 |
base |
| 12 |
generic-display |
| 13 |
generic-editing |
| 14 |
generic-date-based |
| 15 |
mixins |
| 16 |
flattened-index |
| 17 |
|
| 18 |
Specification |
| 19 |
============= |
| 20 |
|
| 21 |
Each request served by a class-based view has an independent state; therefore, |
| 22 |
it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is |
| 23 |
a thread-safe operation). |
| 24 |
|
| 25 |
A class-based view is deployed into a URL pattern using the |
| 26 |
:meth:`~django.views.generic.base.View.as_view()` classmethod:: |
| 27 |
|
| 28 |
urlpatterns = [ |
| 29 |
path("view/", MyView.as_view(size=42)), |
| 30 |
] |
| 31 |
|
| 32 |
.. admonition:: Thread safety with view arguments |
| 33 |
|
| 34 |
Arguments passed to a view are shared between every instance of a view. |
| 35 |
This means that you shouldn't use a list, dictionary, or any other |
| 36 |
mutable object as an argument to a view. If you do and the shared object |
| 37 |
is modified, the actions of one user visiting your view could have an |
| 38 |
effect on subsequent users visiting the same view. |
| 39 |
|
| 40 |
Arguments passed into :meth:`~django.views.generic.base.View.as_view()` will |
| 41 |
be assigned onto the instance that is used to service a request. Using the |
| 42 |
previous example, this means that every request on ``MyView`` is able to use |
| 43 |
``self.size``. Arguments must correspond to attributes that already exist on |
| 44 |
the class (return ``True`` on a ``hasattr`` check). |
| 45 |
|
| 46 |
Base vs Generic views |
| 47 |
===================== |
| 48 |
|
| 49 |
Base class-based views can be thought of as *parent* views, which can be |
| 50 |
used by themselves or inherited from. They may not provide all the |
| 51 |
capabilities required for projects, in which case there are Mixins which |
| 52 |
extend what base views can do. |
| 53 |
|
| 54 |
Django's generic views are built off of those base views, and were developed |
| 55 |
as a shortcut for common usage patterns such as displaying the details of an |
| 56 |
object. They take certain common idioms and patterns found in view |
| 57 |
development and abstract them so that you can quickly write common views of |
| 58 |
data without having to repeat yourself. |
| 59 |
|
| 60 |
Most generic views require the ``queryset`` key, which is a ``QuerySet`` |
| 61 |
instance; see :doc:`/topics/db/queries` for more information about ``QuerySet`` |
| 62 |
objects. |