Debian Codegraph @

docs/ref/class-based-views/mixins-single-object.txt

raw
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``