/docs/ref/generic-views.txt

https://code.google.com/p/mango-py/ · Plain Text · 1114 lines · 760 code · 354 blank · 0 comment · 0 complexity · 8805f361aedfc566a58e908b455501e3 MD5 · raw file

  1. =============
  2. Generic views
  3. =============
  4. .. versionchanged:: 1.3
  5. .. note::
  6. From Django 1.3, function-based generic views have been deprecated in favor
  7. of a class-based approach, described in the class-based views :doc:`topic
  8. guide </topics/class-based-views>` and :doc:`detailed reference
  9. </ref/class-based-views>`.
  10. Writing Web applications can be monotonous, because we repeat certain patterns
  11. again and again. In Django, the most common of these patterns have been
  12. abstracted into "generic views" that let you quickly provide common views of
  13. an object without actually needing to write any Python code.
  14. A general introduction to generic views can be found in the :doc:`topic guide
  15. </topics/generic-views>`.
  16. This reference contains details of Django's built-in generic views, along with
  17. a list of all keyword arguments that a generic view expects. Remember that
  18. arguments may either come from the URL pattern or from the ``extra_context``
  19. additional-information dictionary.
  20. Most generic views require the ``queryset`` key, which is a ``QuerySet``
  21. instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
  22. objects.
  23. .. module:: django.views.generic.simple
  24. "Simple" generic views
  25. ======================
  26. The ``django.views.generic.simple`` module contains simple views to handle a
  27. couple of common cases: rendering a template when no view logic is needed,
  28. and issuing a redirect.
  29. ``django.views.generic.simple.direct_to_template``
  30. --------------------------------------------------
  31. **Description:**
  32. Renders a given template, passing it a ``{{ params }}`` template variable,
  33. which is a dictionary of the parameters captured in the URL.
  34. **Required arguments:**
  35. * ``template``: The full name of a template to use.
  36. **Optional arguments:**
  37. * ``extra_context``: A dictionary of values to add to the template
  38. context. By default, this is an empty dictionary. If a value in the
  39. dictionary is callable, the generic view will call it
  40. just before rendering the template.
  41. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  42. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  43. **Example:**
  44. Given the following URL patterns::
  45. from django.views.generic.simple import direct_to_template
  46. urlpatterns = patterns('',
  47. (r'^foo/$', direct_to_template, {'template': 'foo_index.html'}),
  48. (r'^foo/(?P<id>\d+)/$', direct_to_template, {'template': 'foo_detail.html'}),
  49. )
  50. ... a request to ``/foo/`` would render the template ``foo_index.html``, and a
  51. request to ``/foo/15/`` would render the ``foo_detail.html`` with a context
  52. variable ``{{ params.id }}`` that is set to ``15``.
  53. ``django.views.generic.simple.redirect_to``
  54. -------------------------------------------
  55. **Description:**
  56. Redirects to a given URL.
  57. The given URL may contain dictionary-style string formatting, which will be
  58. interpolated against the parameters captured in the URL. Because keyword
  59. interpolation is *always* done (even if no arguments are passed in), any ``"%"``
  60. characters in the URL must be written as ``"%%"`` so that Python will convert
  61. them to a single percent sign on output.
  62. If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).
  63. **Required arguments:**
  64. * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410
  65. (Gone) HTTP error.
  66. **Optional arguments:**
  67. * ``permanent``: Whether the redirect should be permanent. The only
  68. difference here is the HTTP status code returned. If ``True``, then the
  69. redirect will use status code 301. If ``False``, then the redirect will
  70. use status code 302. By default, ``permanent`` is ``True``.
  71. * ``query_string``: Whether to pass along the GET query string to
  72. the new location. If ``True``, then the query string is appended
  73. to the URL. If ``False``, then the query string is discarded. By
  74. default, ``query_string`` is ``False``.
  75. .. versionadded:: 1.3
  76. The ``query_string`` keyword argument is new in Django 1.3.
  77. **Example:**
  78. This example issues a permanent redirect (HTTP status code 301) from
  79. ``/foo/<id>/`` to ``/bar/<id>/``::
  80. from django.views.generic.simple import redirect_to
  81. urlpatterns = patterns('',
  82. ('^foo/(?P<id>\d+)/$', redirect_to, {'url': '/bar/%(id)s/'}),
  83. )
  84. This example issues a non-permanent redirect (HTTP status code 302) from
  85. ``/foo/<id>/`` to ``/bar/<id>/``::
  86. from django.views.generic.simple import redirect_to
  87. urlpatterns = patterns('',
  88. ('^foo/(?P<id>\d+)/$', redirect_to, {'url': '/bar/%(id)s/', 'permanent': False}),
  89. )
  90. This example returns a 410 HTTP error for requests to ``/bar/``::
  91. from django.views.generic.simple import redirect_to
  92. urlpatterns = patterns('',
  93. ('^bar/$', redirect_to, {'url': None}),
  94. )
  95. This example shows how ``"%"`` characters must be written in the URL in order
  96. to avoid confusion with Python's string formatting markers. If the redirect
  97. string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised::
  98. from django.views.generic.simple import redirect_to
  99. urlpatterns = patterns('',
  100. ('^bar/$', redirect_to, {'url': '%%7Ejacob.'}),
  101. )
  102. .. module:: django.views.generic.date_based
  103. Date-based generic views
  104. ========================
  105. Date-based generic views (in the module ``django.views.generic.date_based``)
  106. are views for displaying drilldown pages for date-based data.
  107. ``django.views.generic.date_based.archive_index``
  108. -------------------------------------------------
  109. **Description:**
  110. A top-level index page showing the "latest" objects, by date. Objects with
  111. a date in the *future* are not included unless you set ``allow_future`` to
  112. ``True``.
  113. **Required arguments:**
  114. * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
  115. * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
  116. the ``QuerySet``'s model that the date-based archive should use to
  117. determine the objects on the page.
  118. **Optional arguments:**
  119. * ``num_latest``: The number of latest objects to send to the template
  120. context. By default, it's 15.
  121. * ``template_name``: The full name of a template to use in rendering the
  122. page. This lets you override the default template name (see below).
  123. * ``template_loader``: The template loader to use when loading the
  124. template. By default, it's ``django.template.loader``.
  125. * ``extra_context``: A dictionary of values to add to the template
  126. context. By default, this is an empty dictionary. If a value in the
  127. dictionary is callable, the generic view will call it
  128. just before rendering the template.
  129. * ``allow_empty``: A boolean specifying whether to display the page if no
  130. objects are available. If this is ``False`` and no objects are available,
  131. the view will raise a 404 instead of displaying an empty page. By
  132. default, this is ``True``.
  133. * ``context_processors``: A list of template-context processors to apply to
  134. the view's template.
  135. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  136. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  137. * ``allow_future``: A boolean specifying whether to include "future"
  138. objects on this page, where "future" means objects in which the field
  139. specified in ``date_field`` is greater than the current date/time. By
  140. default, this is ``False``.
  141. * ``template_object_name``: Designates the name of the template variable
  142. to use in the template context. By default, this is ``'latest'``.
  143. **Template name:**
  144. If ``template_name`` isn't specified, this view will use the template
  145. ``<app_label>/<model_name>_archive.html`` by default, where:
  146. * ``<model_name>`` is your model's name in all lowercase. For a model
  147. ``StaffMember``, that'd be ``staffmember``.
  148. * ``<app_label>`` is the right-most part of the full Python path to
  149. your model's app. For example, if your model lives in
  150. ``apps/blog/models.py``, that'd be ``blog``.
  151. **Template context:**
  152. In addition to ``extra_context``, the template's context will be:
  153. * ``date_list``: A ``DateQuerySet`` object containing all years that have
  154. have objects available according to ``queryset``, represented as
  155. ``datetime.datetime`` objects. These are ordered in reverse. This is
  156. equivalent to ``queryset.dates(date_field, 'year')[::-1]``.
  157. * ``latest``: The ``num_latest`` objects in the system, ordered descending
  158. by ``date_field``. For example, if ``num_latest`` is ``10``, then
  159. ``latest`` will be a list of the latest 10 objects in ``queryset``.
  160. This variable's name depends on the ``template_object_name`` parameter,
  161. which is ``'latest'`` by default. If ``template_object_name`` is
  162. ``'foo'``, this variable's name will be ``foo``.
  163. ``django.views.generic.date_based.archive_year``
  164. ------------------------------------------------
  165. **Description:**
  166. A yearly archive page showing all available months in a given year. Objects
  167. with a date in the *future* are not displayed unless you set ``allow_future``
  168. to ``True``.
  169. **Required arguments:**
  170. * ``year``: The four-digit year for which the archive serves.
  171. * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
  172. * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
  173. the ``QuerySet``'s model that the date-based archive should use to
  174. determine the objects on the page.
  175. **Optional arguments:**
  176. * ``template_name``: The full name of a template to use in rendering the
  177. page. This lets you override the default template name (see below).
  178. * ``template_loader``: The template loader to use when loading the
  179. template. By default, it's ``django.template.loader``.
  180. * ``extra_context``: A dictionary of values to add to the template
  181. context. By default, this is an empty dictionary. If a value in the
  182. dictionary is callable, the generic view will call it
  183. just before rendering the template.
  184. * ``allow_empty``: A boolean specifying whether to display the page if no
  185. objects are available. If this is ``False`` and no objects are available,
  186. the view will raise a 404 instead of displaying an empty page. By
  187. default, this is ``False``.
  188. * ``context_processors``: A list of template-context processors to apply to
  189. the view's template.
  190. * ``template_object_name``: Designates the name of the template variable
  191. to use in the template context. By default, this is ``'object'``. The
  192. view will append ``'_list'`` to the value of this parameter in
  193. determining the variable's name.
  194. * ``make_object_list``: A boolean specifying whether to retrieve the full
  195. list of objects for this year and pass those to the template. If ``True``,
  196. this list of objects will be made available to the template as
  197. ``object_list``. (The name ``object_list`` may be different; see the docs
  198. for ``object_list`` in the "Template context" section below.) By default,
  199. this is ``False``.
  200. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  201. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  202. * ``allow_future``: A boolean specifying whether to include "future"
  203. objects on this page, where "future" means objects in which the field
  204. specified in ``date_field`` is greater than the current date/time. By
  205. default, this is ``False``.
  206. **Template name:**
  207. If ``template_name`` isn't specified, this view will use the template
  208. ``<app_label>/<model_name>_archive_year.html`` by default.
  209. **Template context:**
  210. In addition to ``extra_context``, the template's context will be:
  211. * ``date_list``: A ``DateQuerySet`` object containing all months that have
  212. have objects available according to ``queryset``, represented as
  213. ``datetime.datetime`` objects, in ascending order.
  214. * ``year``: The given year, as a four-character string.
  215. * ``object_list``: If the ``make_object_list`` parameter is ``True``, this
  216. will be set to a list of objects available for the given year, ordered by
  217. the date field. This variable's name depends on the
  218. ``template_object_name`` parameter, which is ``'object'`` by default. If
  219. ``template_object_name`` is ``'foo'``, this variable's name will be
  220. ``foo_list``.
  221. If ``make_object_list`` is ``False``, ``object_list`` will be passed to
  222. the template as an empty list.
  223. ``django.views.generic.date_based.archive_month``
  224. -------------------------------------------------
  225. **Description:**
  226. A monthly archive page showing all objects in a given month. Objects with a
  227. date in the *future* are not displayed unless you set ``allow_future`` to
  228. ``True``.
  229. **Required arguments:**
  230. * ``year``: The four-digit year for which the archive serves (a string).
  231. * ``month``: The month for which the archive serves, formatted according to
  232. the ``month_format`` argument.
  233. * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
  234. * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
  235. the ``QuerySet``'s model that the date-based archive should use to
  236. determine the objects on the page.
  237. **Optional arguments:**
  238. * ``month_format``: A format string that regulates what format the
  239. ``month`` parameter uses. This should be in the syntax accepted by
  240. Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
  241. ``"%b"`` by default, which is a three-letter month abbreviation. To
  242. change it to use numbers, use ``"%m"``.
  243. * ``template_name``: The full name of a template to use in rendering the
  244. page. This lets you override the default template name (see below).
  245. * ``template_loader``: The template loader to use when loading the
  246. template. By default, it's ``django.template.loader``.
  247. * ``extra_context``: A dictionary of values to add to the template
  248. context. By default, this is an empty dictionary. If a value in the
  249. dictionary is callable, the generic view will call it
  250. just before rendering the template.
  251. * ``allow_empty``: A boolean specifying whether to display the page if no
  252. objects are available. If this is ``False`` and no objects are available,
  253. the view will raise a 404 instead of displaying an empty page. By
  254. default, this is ``False``.
  255. * ``context_processors``: A list of template-context processors to apply to
  256. the view's template.
  257. * ``template_object_name``: Designates the name of the template variable
  258. to use in the template context. By default, this is ``'object'``. The
  259. view will append ``'_list'`` to the value of this parameter in
  260. determining the variable's name.
  261. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  262. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  263. * ``allow_future``: A boolean specifying whether to include "future"
  264. objects on this page, where "future" means objects in which the field
  265. specified in ``date_field`` is greater than the current date/time. By
  266. default, this is ``False``.
  267. **Template name:**
  268. If ``template_name`` isn't specified, this view will use the template
  269. ``<app_label>/<model_name>_archive_month.html`` by default.
  270. **Template context:**
  271. .. versionadded:: 1.2
  272. The inclusion of ``date_list`` in the template's context is new.
  273. In addition to ``extra_context``, the template's context will be:
  274. * ``date_list``: A ``DateQuerySet`` object containing all days that have
  275. have objects available in the given month, according to ``queryset``,
  276. represented as ``datetime.datetime`` objects, in ascending order.
  277. * ``month``: A ``datetime.date`` object representing the given month.
  278. * ``next_month``: A ``datetime.date`` object representing the first day of
  279. the next month. If the next month is in the future, this will be
  280. ``None``.
  281. * ``previous_month``: A ``datetime.date`` object representing the first day
  282. of the previous month. Unlike ``next_month``, this will never be
  283. ``None``.
  284. * ``object_list``: A list of objects available for the given month. This
  285. variable's name depends on the ``template_object_name`` parameter, which
  286. is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
  287. this variable's name will be ``foo_list``.
  288. .. _strftime docs: http://docs.python.org/library/time.html#time.strftime
  289. ``django.views.generic.date_based.archive_week``
  290. ------------------------------------------------
  291. **Description:**
  292. A weekly archive page showing all objects in a given week. Objects with a date
  293. in the *future* are not displayed unless you set ``allow_future`` to ``True``.
  294. **Required arguments:**
  295. * ``year``: The four-digit year for which the archive serves (a string).
  296. * ``week``: The week of the year for which the archive serves (a string).
  297. Weeks start with Sunday.
  298. * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
  299. * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
  300. the ``QuerySet``'s model that the date-based archive should use to
  301. determine the objects on the page.
  302. **Optional arguments:**
  303. * ``template_name``: The full name of a template to use in rendering the
  304. page. This lets you override the default template name (see below).
  305. * ``template_loader``: The template loader to use when loading the
  306. template. By default, it's ``django.template.loader``.
  307. * ``extra_context``: A dictionary of values to add to the template
  308. context. By default, this is an empty dictionary. If a value in the
  309. dictionary is callable, the generic view will call it
  310. just before rendering the template.
  311. * ``allow_empty``: A boolean specifying whether to display the page if no
  312. objects are available. If this is ``False`` and no objects are available,
  313. the view will raise a 404 instead of displaying an empty page. By
  314. default, this is ``True``.
  315. * ``context_processors``: A list of template-context processors to apply to
  316. the view's template.
  317. * ``template_object_name``: Designates the name of the template variable
  318. to use in the template context. By default, this is ``'object'``. The
  319. view will append ``'_list'`` to the value of this parameter in
  320. determining the variable's name.
  321. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  322. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  323. * ``allow_future``: A boolean specifying whether to include "future"
  324. objects on this page, where "future" means objects in which the field
  325. specified in ``date_field`` is greater than the current date/time. By
  326. default, this is ``False``.
  327. **Template name:**
  328. If ``template_name`` isn't specified, this view will use the template
  329. ``<app_label>/<model_name>_archive_week.html`` by default.
  330. **Template context:**
  331. In addition to ``extra_context``, the template's context will be:
  332. * ``week``: A ``datetime.date`` object representing the first day of the
  333. given week.
  334. * ``object_list``: A list of objects available for the given week. This
  335. variable's name depends on the ``template_object_name`` parameter, which
  336. is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
  337. this variable's name will be ``foo_list``.
  338. ``django.views.generic.date_based.archive_day``
  339. -----------------------------------------------
  340. **Description:**
  341. A day archive page showing all objects in a given day. Days in the future throw
  342. a 404 error, regardless of whether any objects exist for future days, unless
  343. you set ``allow_future`` to ``True``.
  344. **Required arguments:**
  345. * ``year``: The four-digit year for which the archive serves (a string).
  346. * ``month``: The month for which the archive serves, formatted according to
  347. the ``month_format`` argument.
  348. * ``day``: The day for which the archive serves, formatted according to the
  349. ``day_format`` argument.
  350. * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
  351. * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
  352. the ``QuerySet``'s model that the date-based archive should use to
  353. determine the objects on the page.
  354. **Optional arguments:**
  355. * ``month_format``: A format string that regulates what format the
  356. ``month`` parameter uses. This should be in the syntax accepted by
  357. Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
  358. ``"%b"`` by default, which is a three-letter month abbreviation. To
  359. change it to use numbers, use ``"%m"``.
  360. * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
  361. It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
  362. * ``template_name``: The full name of a template to use in rendering the
  363. page. This lets you override the default template name (see below).
  364. * ``template_loader``: The template loader to use when loading the
  365. template. By default, it's ``django.template.loader``.
  366. * ``extra_context``: A dictionary of values to add to the template
  367. context. By default, this is an empty dictionary. If a value in the
  368. dictionary is callable, the generic view will call it
  369. just before rendering the template.
  370. * ``allow_empty``: A boolean specifying whether to display the page if no
  371. objects are available. If this is ``False`` and no objects are available,
  372. the view will raise a 404 instead of displaying an empty page. By
  373. default, this is ``False``.
  374. * ``context_processors``: A list of template-context processors to apply to
  375. the view's template.
  376. * ``template_object_name``: Designates the name of the template variable
  377. to use in the template context. By default, this is ``'object'``. The
  378. view will append ``'_list'`` to the value of this parameter in
  379. determining the variable's name.
  380. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  381. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  382. * ``allow_future``: A boolean specifying whether to include "future"
  383. objects on this page, where "future" means objects in which the field
  384. specified in ``date_field`` is greater than the current date/time. By
  385. default, this is ``False``.
  386. **Template name:**
  387. If ``template_name`` isn't specified, this view will use the template
  388. ``<app_label>/<model_name>_archive_day.html`` by default.
  389. **Template context:**
  390. In addition to ``extra_context``, the template's context will be:
  391. * ``day``: A ``datetime.date`` object representing the given day.
  392. * ``next_day``: A ``datetime.date`` object representing the next day. If
  393. the next day is in the future, this will be ``None``.
  394. * ``previous_day``: A ``datetime.date`` object representing the previous day.
  395. Unlike ``next_day``, this will never be ``None``.
  396. * ``object_list``: A list of objects available for the given day. This
  397. variable's name depends on the ``template_object_name`` parameter, which
  398. is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
  399. this variable's name will be ``foo_list``.
  400. ``django.views.generic.date_based.archive_today``
  401. -------------------------------------------------
  402. **Description:**
  403. A day archive page showing all objects for *today*. This is exactly the same as
  404. ``archive_day``, except the ``year``/``month``/``day`` arguments are not used,
  405. and today's date is used instead.
  406. ``django.views.generic.date_based.object_detail``
  407. -------------------------------------------------
  408. **Description:**
  409. A page representing an individual object. If the object has a date value in the
  410. future, the view will throw a 404 error by default, unless you set
  411. ``allow_future`` to ``True``.
  412. **Required arguments:**
  413. * ``year``: The object's four-digit year (a string).
  414. * ``month``: The object's month , formatted according to the
  415. ``month_format`` argument.
  416. * ``day``: The object's day , formatted according to the ``day_format``
  417. argument.
  418. * ``queryset``: A ``QuerySet`` that contains the object.
  419. * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
  420. the ``QuerySet``'s model that the generic view should use to look up the
  421. object according to ``year``, ``month`` and ``day``.
  422. * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
  423. If you provide ``object_id``, it should be the value of the primary-key
  424. field for the object being displayed on this page.
  425. Otherwise, ``slug`` should be the slug of the given object, and
  426. ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
  427. model. By default, ``slug_field`` is ``'slug'``.
  428. **Optional arguments:**
  429. * ``month_format``: A format string that regulates what format the
  430. ``month`` parameter uses. This should be in the syntax accepted by
  431. Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
  432. ``"%b"`` by default, which is a three-letter month abbreviation. To
  433. change it to use numbers, use ``"%m"``.
  434. * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
  435. It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
  436. * ``template_name``: The full name of a template to use in rendering the
  437. page. This lets you override the default template name (see below).
  438. * ``template_name_field``: The name of a field on the object whose value is
  439. the template name to use. This lets you store template names in the data.
  440. In other words, if your object has a field ``'the_template'`` that
  441. contains a string ``'foo.html'``, and you set ``template_name_field`` to
  442. ``'the_template'``, then the generic view for this object will use the
  443. template ``'foo.html'``.
  444. It's a bit of a brain-bender, but it's useful in some cases.
  445. * ``template_loader``: The template loader to use when loading the
  446. template. By default, it's ``django.template.loader``.
  447. * ``extra_context``: A dictionary of values to add to the template
  448. context. By default, this is an empty dictionary. If a value in the
  449. dictionary is callable, the generic view will call it
  450. just before rendering the template.
  451. * ``context_processors``: A list of template-context processors to apply to
  452. the view's template.
  453. * ``template_object_name``: Designates the name of the template variable
  454. to use in the template context. By default, this is ``'object'``.
  455. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  456. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  457. * ``allow_future``: A boolean specifying whether to include "future"
  458. objects on this page, where "future" means objects in which the field
  459. specified in ``date_field`` is greater than the current date/time. By
  460. default, this is ``False``.
  461. **Template name:**
  462. If ``template_name`` isn't specified, this view will use the template
  463. ``<app_label>/<model_name>_detail.html`` by default.
  464. **Template context:**
  465. In addition to ``extra_context``, the template's context will be:
  466. * ``object``: The object. This variable's name depends on the
  467. ``template_object_name`` parameter, which is ``'object'`` by default. If
  468. ``template_object_name`` is ``'foo'``, this variable's name will be
  469. ``foo``.
  470. .. module:: django.views.generic.list_detail
  471. List/detail generic views
  472. =========================
  473. The list-detail generic-view framework (in the
  474. ``django.views.generic.list_detail`` module) is similar to the date-based one,
  475. except the former simply has two views: a list of objects and an individual
  476. object page.
  477. ``django.views.generic.list_detail.object_list``
  478. ------------------------------------------------
  479. **Description:**
  480. A page representing a list of objects.
  481. **Required arguments:**
  482. * ``queryset``: A ``QuerySet`` that represents the objects.
  483. **Optional arguments:**
  484. * ``paginate_by``: An integer specifying how many objects should be
  485. displayed per page. If this is given, the view will paginate objects with
  486. ``paginate_by`` objects per page. The view will expect either a ``page``
  487. query string parameter (via ``GET``) or a ``page`` variable specified in
  488. the URLconf. See `Notes on pagination`_ below.
  489. * ``page``: The current page number, as an integer, or the string
  490. ``'last'``. This is 1-based. See `Notes on pagination`_ below.
  491. * ``template_name``: The full name of a template to use in rendering the
  492. page. This lets you override the default template name (see below).
  493. * ``template_loader``: The template loader to use when loading the
  494. template. By default, it's ``django.template.loader``.
  495. * ``extra_context``: A dictionary of values to add to the template
  496. context. By default, this is an empty dictionary. If a value in the
  497. dictionary is callable, the generic view will call it
  498. just before rendering the template.
  499. * ``allow_empty``: A boolean specifying whether to display the page if no
  500. objects are available. If this is ``False`` and no objects are available,
  501. the view will raise a 404 instead of displaying an empty page. By
  502. default, this is ``True``.
  503. * ``context_processors``: A list of template-context processors to apply to
  504. the view's template.
  505. * ``template_object_name``: Designates the name of the template variable
  506. to use in the template context. By default, this is ``'object'``. The
  507. view will append ``'_list'`` to the value of this parameter in
  508. determining the variable's name.
  509. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  510. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  511. **Template name:**
  512. If ``template_name`` isn't specified, this view will use the template
  513. ``<app_label>/<model_name>_list.html`` by default.
  514. **Template context:**
  515. In addition to ``extra_context``, the template's context will be:
  516. * ``object_list``: The list of objects. This variable's name depends on the
  517. ``template_object_name`` parameter, which is ``'object'`` by default. If
  518. ``template_object_name`` is ``'foo'``, this variable's name will be
  519. ``foo_list``.
  520. * ``is_paginated``: A boolean representing whether the results are
  521. paginated. Specifically, this is set to ``False`` if the number of
  522. available objects is less than or equal to ``paginate_by``.
  523. If the results are paginated, the context will contain these extra variables:
  524. * ``paginator``: An instance of ``django.core.paginator.Paginator``.
  525. * ``page_obj``: An instance of ``django.core.paginator.Page``.
  526. Notes on pagination
  527. ~~~~~~~~~~~~~~~~~~~
  528. If ``paginate_by`` is specified, Django will paginate the results. You can
  529. specify the page number in the URL in one of two ways:
  530. * Use the ``page`` parameter in the URLconf. For example, this is what
  531. your URLconf might look like::
  532. (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
  533. * Pass the page number via the ``page`` query-string parameter. For
  534. example, a URL would look like this::
  535. /objects/?page=3
  536. * To loop over all the available page numbers, use the ``page_range``
  537. variable. You can iterate over the list provided by ``page_range``
  538. to create a link to every page of results.
  539. These values and lists are 1-based, not 0-based, so the first page would be
  540. represented as page ``1``.
  541. For more on pagination, read the :doc:`pagination documentation
  542. </topics/pagination>`.
  543. As a special case, you are also permitted to use ``last`` as a value for
  544. ``page``::
  545. /objects/?page=last
  546. This allows you to access the final page of results without first having to
  547. determine how many pages there are.
  548. Note that ``page`` *must* be either a valid page number or the value ``last``;
  549. any other value for ``page`` will result in a 404 error.
  550. ``django.views.generic.list_detail.object_detail``
  551. --------------------------------------------------
  552. A page representing an individual object.
  553. **Description:**
  554. A page representing an individual object.
  555. **Required arguments:**
  556. * ``queryset``: A ``QuerySet`` that contains the object.
  557. * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
  558. If you provide ``object_id``, it should be the value of the primary-key
  559. field for the object being displayed on this page.
  560. Otherwise, ``slug`` should be the slug of the given object, and
  561. ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
  562. model. By default, ``slug_field`` is ``'slug'``.
  563. **Optional arguments:**
  564. * ``template_name``: The full name of a template to use in rendering the
  565. page. This lets you override the default template name (see below).
  566. * ``template_name_field``: The name of a field on the object whose value is
  567. the template name to use. This lets you store template names in the data.
  568. In other words, if your object has a field ``'the_template'`` that
  569. contains a string ``'foo.html'``, and you set ``template_name_field`` to
  570. ``'the_template'``, then the generic view for this object will use the
  571. template ``'foo.html'``.
  572. It's a bit of a brain-bender, but it's useful in some cases.
  573. * ``template_loader``: The template loader to use when loading the
  574. template. By default, it's ``django.template.loader``.
  575. * ``extra_context``: A dictionary of values to add to the template
  576. context. By default, this is an empty dictionary. If a value in the
  577. dictionary is callable, the generic view will call it
  578. just before rendering the template.
  579. * ``context_processors``: A list of template-context processors to apply to
  580. the view's template.
  581. * ``template_object_name``: Designates the name of the template variable
  582. to use in the template context. By default, this is ``'object'``.
  583. * ``mimetype``: The MIME type to use for the resulting document. Defaults
  584. to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
  585. **Template name:**
  586. If ``template_name`` isn't specified, this view will use the template
  587. ``<app_label>/<model_name>_detail.html`` by default.
  588. **Template context:**
  589. In addition to ``extra_context``, the template's context will be:
  590. * ``object``: The object. This variable's name depends on the
  591. ``template_object_name`` parameter, which is ``'object'`` by default. If
  592. ``template_object_name`` is ``'foo'``, this variable's name will be
  593. ``foo``.
  594. .. module:: django.views.generic.create_update
  595. Create/update/delete generic views
  596. ==================================
  597. The ``django.views.generic.create_update`` module contains a set of functions
  598. for creating, editing and deleting objects.
  599. ``django.views.generic.create_update.create_object``
  600. ----------------------------------------------------
  601. **Description:**
  602. A page that displays a form for creating an object, redisplaying the form with
  603. validation errors (if there are any) and saving the object.
  604. **Required arguments:**
  605. * Either ``form_class`` or ``model`` is required.
  606. If you provide ``form_class``, it should be a ``django.forms.ModelForm``
  607. subclass. Use this argument when you need to customize the model's form.
  608. See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
  609. information.
  610. Otherwise, ``model`` should be a Django model class and the form used
  611. will be a standard ``ModelForm`` for ``model``.
  612. **Optional arguments:**
  613. * ``post_save_redirect``: A URL to which the view will redirect after
  614. saving the object. By default, it's ``object.get_absolute_url()``.
  615. ``post_save_redirect`` may contain dictionary string formatting, which
  616. will be interpolated against the object's field attributes. For example,
  617. you could use ``post_save_redirect="/polls/%(slug)s/"``.
  618. * ``login_required``: A boolean that designates whether a user must be
  619. logged in, in order to see the page and save changes. This hooks into the
  620. Django :doc:`authentication system </topics/auth>`. By default, this is
  621. ``False``.
  622. If this is ``True``, and a non-logged-in user attempts to visit this page
  623. or save the form, Django will redirect the request to ``/accounts/login/``.
  624. * ``template_name``: The full name of a template to use in rendering the
  625. page. This lets you override the default template name (see below).
  626. * ``template_loader``: The template loader to use when loading the
  627. template. By default, it's ``django.template.loader``.
  628. * ``extra_context``: A dictionary of values to add to the template
  629. context. By default, this is an empty dictionary. If a value in the
  630. dictionary is callable, the generic view will call it
  631. just before rendering the template.
  632. * ``context_processors``: A list of template-context processors to apply to
  633. the view's template.
  634. **Template name:**
  635. If ``template_name`` isn't specified, this view will use the template
  636. ``<app_label>/<model_name>_form.html`` by default.
  637. **Template context:**
  638. In addition to ``extra_context``, the template's context will be:
  639. * ``form``: A ``django.forms.ModelForm`` instance representing the form
  640. for creating the object. This lets you refer to form fields easily in the
  641. template system.
  642. For example, if the model has two fields, ``name`` and ``address``::
  643. <form action="" method="post">
  644. <p>{{ form.name.label_tag }} {{ form.name }}</p>
  645. <p>{{ form.address.label_tag }} {{ form.address }}</p>
  646. </form>
  647. See the :doc:`forms documentation </topics/forms/index>` for more
  648. information about using ``Form`` objects in templates.
  649. ``django.views.generic.create_update.update_object``
  650. ----------------------------------------------------
  651. **Description:**
  652. A page that displays a form for editing an existing object, redisplaying the
  653. form with validation errors (if there are any) and saving changes to the
  654. object. This uses a form automatically generated from the object's
  655. model class.
  656. **Required arguments:**
  657. * Either ``form_class`` or ``model`` is required.
  658. If you provide ``form_class``, it should be a ``django.forms.ModelForm``
  659. subclass. Use this argument when you need to customize the model's form.
  660. See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
  661. information.
  662. Otherwise, ``model`` should be a Django model class and the form used
  663. will be a standard ``ModelForm`` for ``model``.
  664. * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
  665. If you provide ``object_id``, it should be the value of the primary-key
  666. field for the object being displayed on this page.
  667. Otherwise, ``slug`` should be the slug of the given object, and
  668. ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
  669. model. By default, ``slug_field`` is ``'slug'``.
  670. **Optional arguments:**
  671. * ``post_save_redirect``: A URL to which the view will redirect after
  672. saving the object. By default, it's ``object.get_absolute_url()``.
  673. ``post_save_redirect`` may contain dictionary string formatting, which
  674. will be interpolated against the object's field attributes. For example,
  675. you could use ``post_save_redirect="/polls/%(slug)s/"``.
  676. * ``login_required``: A boolean that designates whether a user must be
  677. logged in, in order to see the page and save changes. This hooks into the
  678. Django :doc:`authentication system </topics/auth>`. By default, this is
  679. ``False``.
  680. If this is ``True``, and a non-logged-in user attempts to visit this page
  681. or save the form, Django will redirect to :setting:`LOGIN_URL` (which
  682. defaults to ``/accounts/login/``).
  683. * ``template_name``: The full name of a template to use in rendering the
  684. page. This lets you override the default template name (see below).
  685. * ``template_loader``: The template loader to use when loading the
  686. template. By default, it's ``django.template.loader``.
  687. * ``extra_context``: A dictionary of values to add to the template
  688. context. By default, this is an empty dictionary. If a value in the
  689. dictionary is callable, the generic view will call it
  690. just before rendering the template.
  691. * ``context_processors``: A list of template-context processors to apply to
  692. the view's template.
  693. * ``template_object_name``: Designates the name of the template variable
  694. to use in the template context. By default, this is ``'object'``.
  695. **Template name:**
  696. If ``template_name`` isn't specified, this view will use the template
  697. ``<app_label>/<model_name>_form.html`` by default.
  698. **Template context:**
  699. In addition to ``extra_context``, the template's context will be:
  700. * ``form``: A ``django.forms.ModelForm`` instance representing the form
  701. for editing the object. This lets you refer to form fields easily in the
  702. template system.
  703. For example, if the model has two fields, ``name`` and ``address``::
  704. <form action="" method="post">
  705. <p>{{ form.name.label_tag }} {{ form.name }}</p>
  706. <p>{{ form.address.label_tag }} {{ form.address }}</p>
  707. </form>
  708. See the :doc:`forms documentation </topics/forms/index>` for more
  709. information about using ``Form`` objects in templates.
  710. * ``object``: The original object being edited. This variable's name
  711. depends on the ``template_object_name`` parameter, which is ``'object'``
  712. by default. If ``template_object_name`` is ``'foo'``, this variable's
  713. name will be ``foo``.
  714. ``django.views.generic.create_update.delete_object``
  715. ----------------------------------------------------
  716. **Description:**
  717. A view that displays a confirmation page and deletes an existing object. The
  718. given object will only be deleted if the request method is ``POST``. If this
  719. view is fetched via ``GET``, it will display a confirmation page that should
  720. contain a form that POSTs to the same URL.
  721. **Required arguments:**
  722. * ``model``: The Django model class of the object that the form will
  723. delete.
  724. * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
  725. If you provide ``object_id``, it should be the value of the primary-key
  726. field for the object being displayed on this page.
  727. Otherwise, ``slug`` should be the slug of the given object, and
  728. ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
  729. model. By default, ``slug_field`` is ``'slug'``.
  730. * ``post_delete_redirect``: A URL to which the view will redirect after
  731. deleting the object.
  732. **Optional arguments:**
  733. * ``login_required``: A boolean that designates whether a user must be
  734. logged in, in order to see the page and save changes. This hooks into the
  735. Django :doc:`authentication system </topics/auth>`. By default, this is
  736. ``False``.
  737. If this is ``True``, and a non-logged-in user attempts to visit this page
  738. or save the form, Django will redirect to :setting:`LOGIN_URL` (which
  739. defaults to ``/accounts/login/``).
  740. * ``template_name``: The full name of a template to use in rendering the
  741. page. This lets you override the default template name (see below).
  742. * ``template_loader``: The template loader to use when loading the
  743. template. By default, it's ``django.template.loader``.
  744. * ``extra_context``: A dictionary of values to add to the template
  745. context. By default, this is an empty dictionary. If a value in the
  746. dictionary is callable, the generic view will call it
  747. just before rendering the template.
  748. * ``context_processors``: A list of template-context processors to apply to
  749. the view's template.
  750. * ``template_object_name``: Designates the name of the template variable
  751. to use in the template context. By default, this is ``'object'``.
  752. **Template name:**
  753. If ``template_name`` isn't specified, this view will use the template
  754. ``<app_label>/<model_name>_confirm_delete.html`` by default.
  755. **Template context:**
  756. In addition to ``extra_context``, the template's context will be:
  757. * ``object``: The original object that's about to be deleted. This
  758. variable's name depends on the ``template_object_name`` parameter, which
  759. is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
  760. this variable's name will be ``foo``.