| 1 |
==================== |
| 2 |
Single object mixins |
| 3 |
==================== |
| 4 |
|
| 5 |
``SingleObjectMixin`` |
| 6 |
===================== |
| 7 |
|
| 8 |
.. class:: django.views.generic.detail.SingleObjectMixin |
| 9 |
|
| 10 |
Provides a mechanism for looking up an object associated with the |
| 11 |
current HTTP request. |
| 12 |
|
| 13 |
**Methods and Attributes** |
| 14 |
|
| 15 |
.. attribute:: model |
| 16 |
|
| 17 |
The model that this view will display data for. Specifying ``model |
| 18 |
= Foo`` is effectively the same as specifying ``queryset = |
| 19 |
Foo.objects.all()``, where ``objects`` stands for ``Foo``’s |
| 20 |
:ref:`default manager <default-managers>`. |
| 21 |
|
| 22 |
.. attribute:: queryset |
| 23 |
|
| 24 |
A ``QuerySet`` that represents the objects. If provided, the value of |
| 25 |
``queryset`` supersedes the value provided for :attr:`model`. |
| 26 |
|
| 27 |
.. warning:: |
| 28 |
|
| 29 |
``queryset`` is a class attribute with a *mutable* value so care |
| 30 |
must be taken when using it directly. Before using it, either call |
| 31 |
its :meth:`~django.db.models.query.QuerySet.all` method or |
| 32 |
retrieve it with :meth:`get_queryset` which takes care of the |
| 33 |
cloning behind the scenes. |
| 34 |
|
| 35 |
.. attribute:: slug_field |
| 36 |
|
| 37 |
The name of the field on the model that contains the slug. By default, |
| 38 |
``slug_field`` is ``'slug'``. |
| 39 |
|
| 40 |
.. attribute:: slug_url_kwarg |
| 41 |
|
| 42 |
The name of the URLConf keyword argument that contains the slug. By |
| 43 |
default, ``slug_url_kwarg`` is ``'slug'``. |
| 44 |
|
| 45 |
.. attribute:: pk_url_kwarg |
| 46 |
|
| 47 |
The name of the URLConf keyword argument that contains the primary key. |
| 48 |
By default, ``pk_url_kwarg`` is ``'pk'``. |
| 49 |
|
| 50 |
.. attribute:: context_object_name |
| 51 |
|
| 52 |
Designates the name of the variable to use in the context. |
| 53 |
|
| 54 |
.. attribute:: query_pk_and_slug |
| 55 |
|
| 56 |
If ``True``, causes :meth:`get_object()` to perform its lookup using |
| 57 |
both the primary key and the slug. Defaults to ``False``. |
| 58 |
|
| 59 |
This attribute can help mitigate `insecure direct object reference`_ |
| 60 |
attacks. When applications allow access to individual objects by a |
| 61 |
sequential primary key, an attacker could brute-force guess all URLs; |
| 62 |
thereby obtaining a list of all objects in the application. If users |
| 63 |
with access to individual objects should be prevented from obtaining |
| 64 |
this list, setting ``query_pk_and_slug`` to ``True`` will help prevent |
| 65 |
the guessing of URLs as each URL will require two correct, |
| 66 |
non-sequential arguments. Using a unique slug may serve the same |
| 67 |
purpose, but this scheme allows you to have non-unique slugs. |
| 68 |
|
| 69 |
.. _insecure direct object reference: https://wiki.owasp.org/index.php/Top_10_2013-A4-Insecure_Direct_Object_References |
| 70 |
|
| 71 |
.. method:: get_object(queryset=None) |
| 72 |
|
| 73 |
Returns the single object that this view will display. If ``queryset`` |
| 74 |
is provided, that queryset will be used as the source of objects; |
| 75 |
otherwise, :meth:`get_queryset` will be used. ``get_object()`` looks |
| 76 |
for a :attr:`pk_url_kwarg` argument in the arguments to the view; if |
| 77 |
this argument is found, this method performs a primary-key based lookup |
| 78 |
using that value. If this argument is not found, it looks for a |
| 79 |
:attr:`slug_url_kwarg` argument, and performs a slug lookup using the |
| 80 |
:attr:`slug_field`. |
| 81 |
|
| 82 |
When :attr:`query_pk_and_slug` is ``True``, ``get_object()`` will |
| 83 |
perform its lookup using both the primary key and the slug. |
| 84 |
|
| 85 |
.. method:: get_queryset() |
| 86 |
|
| 87 |
Returns the queryset that will be used to retrieve the object that |
| 88 |
this view will display. By default, :meth:`get_queryset` returns the |
| 89 |
value of the :attr:`queryset` attribute if it is set, otherwise |
| 90 |
it constructs a :class:`~django.db.models.query.QuerySet` by calling |
| 91 |
the ``all()`` method on the :attr:`model` attribute's default manager. |
| 92 |
|
| 93 |
.. method:: get_context_object_name(obj) |
| 94 |
|
| 95 |
Return the context variable name that will be used to contain the |
| 96 |
data that this view is manipulating. If :attr:`context_object_name` is |
| 97 |
not set, the context name will be constructed from the ``model_name`` |
| 98 |
of the model that the queryset is composed from. For example, the model |
| 99 |
``Article`` would have context object named ``'article'``. |
| 100 |
|
| 101 |
.. method:: get_context_data(**kwargs) |
| 102 |
|
| 103 |
Returns context data for displaying the object. |
| 104 |
|
| 105 |
The base implementation of this method requires that the ``self.object`` |
| 106 |
attribute be set by the view (even if ``None``). Be sure to do this if |
| 107 |
you are using this mixin without one of the built-in views that does so. |
| 108 |
|
| 109 |
It returns a dictionary with these contents: |
| 110 |
|
| 111 |
* ``object``: The object that this view is displaying |
| 112 |
(``self.object``). |
| 113 |
* ``context_object_name``: ``self.object`` will also be stored under |
| 114 |
the name returned by :meth:`get_context_object_name`, which defaults |
| 115 |
to the lowercased version of the model name. |
| 116 |
|
| 117 |
.. admonition:: Context variables override values from template context processors |
| 118 |
|
| 119 |
Any variables from :meth:`get_context_data` take precedence over |
| 120 |
context variables from :ref:`context processors |
| 121 |
<subclassing-context-requestcontext>`. For example, if your view |
| 122 |
sets the :attr:`model` attribute to |
| 123 |
:class:`~django.contrib.auth.models.User`, the default context |
| 124 |
object name of ``user`` would override the ``user`` variable from |
| 125 |
the :func:`django.contrib.auth.context_processors.auth` context |
| 126 |
processor. Use :meth:`get_context_object_name` to avoid a clash. |
| 127 |
|
| 128 |
.. method:: get_slug_field() |
| 129 |
|
| 130 |
Returns the name of a slug field to be used to look up by slug. By |
| 131 |
default this returns the value of :attr:`slug_field`. |
| 132 |
|
| 133 |
|
| 134 |
``SingleObjectTemplateResponseMixin`` |
| 135 |
===================================== |
| 136 |
|
| 137 |
.. class:: django.views.generic.detail.SingleObjectTemplateResponseMixin |
| 138 |
|
| 139 |
A mixin class that performs template-based response rendering for views |
| 140 |
that operate upon a single object instance. Requires that the view it is |
| 141 |
mixed with provides ``self.object``, the object instance that the view is |
| 142 |
operating on. ``self.object`` will usually be, but is not required to be, |
| 143 |
an instance of a Django model. It may be ``None`` if the view is in the |
| 144 |
process of constructing a new instance. |
| 145 |
|
| 146 |
**Extends** |
| 147 |
|
| 148 |
* :class:`~django.views.generic.base.TemplateResponseMixin` |
| 149 |
|
| 150 |
**Methods and Attributes** |
| 151 |
|
| 152 |
.. attribute:: template_name_field |
| 153 |
|
| 154 |
The field on the current object instance that can be used to determine |
| 155 |
the name of a candidate template. If either ``template_name_field`` |
| 156 |
itself or the value of the ``template_name_field`` on the current |
| 157 |
object instance is ``None``, the object will not be used for a |
| 158 |
candidate template name. |
| 159 |
|
| 160 |
.. attribute:: template_name_suffix |
| 161 |
|
| 162 |
The suffix to append to the auto-generated candidate template name. |
| 163 |
Default suffix is ``_detail``. |
| 164 |
|
| 165 |
.. method:: get_template_names() |
| 166 |
|
| 167 |
Returns a list of candidate template names. Return a list containing |
| 168 |
``template_name``, if set on the value. Otherwise, return a list |
| 169 |
containing: |
| 170 |
|
| 171 |
* the contents of the ``template_name_field`` field on the |
| 172 |
object instance that the view is operating upon (if available) |
| 173 |
* ``<app_label>/<model_name><template_name_suffix>.html`` |