mirror of https://github.com/django/django.git
173 lines
7.3 KiB
Plaintext
173 lines
7.3 KiB
Plaintext
====================
|
||
Single object mixins
|
||
====================
|
||
|
||
SingleObjectMixin
|
||
=================
|
||
|
||
.. class:: django.views.generic.detail.SingleObjectMixin
|
||
|
||
Provides a mechanism for looking up an object associated with the
|
||
current HTTP request.
|
||
|
||
**Methods and Attributes**
|
||
|
||
.. attribute:: model
|
||
|
||
The model that this view will display data for. Specifying ``model
|
||
= Foo`` is effectively the same as specifying ``queryset =
|
||
Foo.objects.all()``, where ``objects`` stands for ``Foo``’s
|
||
:ref:`default manager <default-managers>`.
|
||
|
||
.. attribute:: queryset
|
||
|
||
A ``QuerySet`` that represents the objects. If provided, the value of
|
||
``queryset`` supersedes the value provided for :attr:`model`.
|
||
|
||
.. warning::
|
||
|
||
``queryset`` is a class attribute with a *mutable* value so care
|
||
must be taken when using it directly. Before using it, either call
|
||
its :meth:`~django.db.models.query.QuerySet.all` method or
|
||
retrieve it with :meth:`get_queryset` which takes care of the
|
||
cloning behind the scenes.
|
||
|
||
.. attribute:: slug_field
|
||
|
||
The name of the field on the model that contains the slug. By default,
|
||
``slug_field`` is ``'slug'``.
|
||
|
||
.. attribute:: slug_url_kwarg
|
||
|
||
The name of the URLConf keyword argument that contains the slug. By
|
||
default, ``slug_url_kwarg`` is ``'slug'``.
|
||
|
||
.. attribute:: pk_url_kwarg
|
||
|
||
The name of the URLConf keyword argument that contains the primary key.
|
||
By default, ``pk_url_kwarg`` is ``'pk'``.
|
||
|
||
.. attribute:: context_object_name
|
||
|
||
Designates the name of the variable to use in the context.
|
||
|
||
.. attribute:: query_pk_and_slug
|
||
|
||
If ``True``, causes :meth:`get_object()` to perform its lookup using
|
||
both the primary key and the slug. Defaults to ``False``.
|
||
|
||
This attribute can help mitigate `insecure direct object reference`_
|
||
attacks. When applications allow access to individual objects by a
|
||
sequential primary key, an attacker could brute-force guess all URLs;
|
||
thereby obtaining a list of all objects in the application. If users
|
||
with access to individual objects should be prevented from obtaining
|
||
this list, setting ``query_pk_and_slug`` to ``True`` will help prevent
|
||
the guessing of URLs as each URL will require two correct,
|
||
non-sequential arguments. Simply using a unique slug may serve the same
|
||
purpose, but this scheme allows you to have non-unique slugs.
|
||
|
||
.. _insecure direct object reference: https://www.owasp.org/index.php/Top_10_2013-A4-Insecure_Direct_Object_References
|
||
|
||
.. method:: get_object(queryset=None)
|
||
|
||
Returns the single object that this view will display. If ``queryset``
|
||
is provided, that queryset will be used as the source of objects;
|
||
otherwise, :meth:`get_queryset` will be used. ``get_object()`` looks
|
||
for a :attr:`pk_url_kwarg` argument in the arguments to the view; if
|
||
this argument is found, this method performs a primary-key based lookup
|
||
using that value. If this argument is not found, it looks for a
|
||
:attr:`slug_url_kwarg` argument, and performs a slug lookup using the
|
||
:attr:`slug_field`.
|
||
|
||
When :attr:`query_pk_and_slug` is ``True``, ``get_object()`` will
|
||
perform its lookup using both the primary key and the slug.
|
||
|
||
.. method:: get_queryset()
|
||
|
||
Returns the queryset that will be used to retrieve the object that
|
||
this view will display. By default, :meth:`get_queryset` returns the
|
||
value of the :attr:`queryset` attribute if it is set, otherwise
|
||
it constructs a :class:`~django.db.models.query.QuerySet` by calling
|
||
the ``all()`` method on the :attr:`model` attribute's default manager.
|
||
|
||
.. method:: get_context_object_name(obj)
|
||
|
||
Return the context variable name that will be used to contain the
|
||
data that this view is manipulating. If :attr:`context_object_name` is
|
||
not set, the context name will be constructed from the ``model_name``
|
||
of the model that the queryset is composed from. For example, the model
|
||
``Article`` would have context object named ``'article'``.
|
||
|
||
.. method:: get_context_data(**kwargs)
|
||
|
||
Returns context data for displaying the list of objects.
|
||
|
||
The base implementation of this method requires that the ``self.object``
|
||
attribute be set by the view (even if ``None``). Be sure to do this if
|
||
you are using this mixin without one of the built-in views that does so.
|
||
|
||
It returns a dictionary with these contents:
|
||
|
||
* ``object``: The object that this view is displaying
|
||
(``self.object``).
|
||
* ``context_object_name``: ``self.object`` will also be stored under
|
||
the name returned by :meth:`get_context_object_name`, which defaults
|
||
to the lowercased version of the model name.
|
||
|
||
.. admonition:: Context variables override values from template context processors
|
||
|
||
Any variables from :meth:`get_context_data` take precedence over
|
||
context variables from :ref:`context processors
|
||
<subclassing-context-requestcontext>`. For example, if your view
|
||
sets the :attr:`model` attribute to
|
||
:class:`~django.contrib.auth.models.User`, the default context
|
||
object name of ``user`` would override the ``user`` variable from
|
||
the :func:`django.contrib.auth.context_processors.auth` context
|
||
processor. Use :meth:`get_context_object_name` to avoid a clash.
|
||
|
||
.. method:: get_slug_field()
|
||
|
||
Returns the name of a slug field to be used to look up by slug. By
|
||
default this simply returns the value of :attr:`slug_field`.
|
||
|
||
|
||
SingleObjectTemplateResponseMixin
|
||
=================================
|
||
|
||
.. class:: django.views.generic.detail.SingleObjectTemplateResponseMixin
|
||
|
||
A mixin class that performs template-based response rendering for views
|
||
that operate upon a single object instance. Requires that the view it is
|
||
mixed with provides ``self.object``, the object instance that the view is
|
||
operating on. ``self.object`` will usually be, but is not required to be,
|
||
an instance of a Django model. It may be ``None`` if the view is in the
|
||
process of constructing a new instance.
|
||
|
||
**Extends**
|
||
|
||
* :class:`~django.views.generic.base.TemplateResponseMixin`
|
||
|
||
**Methods and Attributes**
|
||
|
||
.. attribute:: template_name_field
|
||
|
||
The field on the current object instance that can be used to determine
|
||
the name of a candidate template. If either ``template_name_field``
|
||
itself or the value of the ``template_name_field`` on the current
|
||
object instance is ``None``, the object will not be used for a
|
||
candidate template name.
|
||
|
||
.. attribute:: template_name_suffix
|
||
|
||
The suffix to append to the auto-generated candidate template name.
|
||
Default suffix is ``_detail``.
|
||
|
||
.. method:: get_template_names()
|
||
|
||
Returns a list of candidate template names. Returns the following list:
|
||
|
||
* the value of ``template_name`` on the view (if provided)
|
||
* the contents of the ``template_name_field`` field on the
|
||
object instance that the view is operating upon (if available)
|
||
* ``<app_label>/<model_name><template_name_suffix>.html``
|