/docs/ref/generic-views.txt
Plain Text | 1114 lines | 760 code | 354 blank | 0 comment | 0 complexity | 8805f361aedfc566a58e908b455501e3 MD5 | raw file
1============= 2Generic views 3============= 4 5 6.. versionchanged:: 1.3 7 8.. note:: 9 10 From Django 1.3, function-based generic views have been deprecated in favor 11 of a class-based approach, described in the class-based views :doc:`topic 12 guide </topics/class-based-views>` and :doc:`detailed reference 13 </ref/class-based-views>`. 14 15Writing Web applications can be monotonous, because we repeat certain patterns 16again and again. In Django, the most common of these patterns have been 17abstracted into "generic views" that let you quickly provide common views of 18an object without actually needing to write any Python code. 19 20A general introduction to generic views can be found in the :doc:`topic guide 21</topics/generic-views>`. 22 23This reference contains details of Django's built-in generic views, along with 24a list of all keyword arguments that a generic view expects. Remember that 25arguments may either come from the URL pattern or from the ``extra_context`` 26additional-information dictionary. 27 28Most generic views require the ``queryset`` key, which is a ``QuerySet`` 29instance; see :doc:`/topics/db/queries` for more information about ``QuerySet`` 30objects. 31 32.. module:: django.views.generic.simple 33 34"Simple" generic views 35====================== 36 37The ``django.views.generic.simple`` module contains simple views to handle a 38couple of common cases: rendering a template when no view logic is needed, 39and issuing a redirect. 40 41``django.views.generic.simple.direct_to_template`` 42-------------------------------------------------- 43 44**Description:** 45 46Renders a given template, passing it a ``{{ params }}`` template variable, 47which is a dictionary of the parameters captured in the URL. 48 49**Required arguments:** 50 51 * ``template``: The full name of a template to use. 52 53**Optional arguments:** 54 55 * ``extra_context``: A dictionary of values to add to the template 56 context. By default, this is an empty dictionary. If a value in the 57 dictionary is callable, the generic view will call it 58 just before rendering the template. 59 60 * ``mimetype``: The MIME type to use for the resulting document. Defaults 61 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 62 63**Example:** 64 65Given the following URL patterns:: 66 67 from django.views.generic.simple import direct_to_template 68 69 urlpatterns = patterns('', 70 (r'^foo/$', direct_to_template, {'template': 'foo_index.html'}), 71 (r'^foo/(?P<id>\d+)/$', direct_to_template, {'template': 'foo_detail.html'}), 72 ) 73 74... a request to ``/foo/`` would render the template ``foo_index.html``, and a 75request to ``/foo/15/`` would render the ``foo_detail.html`` with a context 76variable ``{{ params.id }}`` that is set to ``15``. 77 78``django.views.generic.simple.redirect_to`` 79------------------------------------------- 80 81**Description:** 82 83Redirects to a given URL. 84 85The given URL may contain dictionary-style string formatting, which will be 86interpolated against the parameters captured in the URL. Because keyword 87interpolation is *always* done (even if no arguments are passed in), any ``"%"`` 88characters in the URL must be written as ``"%%"`` so that Python will convert 89them to a single percent sign on output. 90 91If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410). 92 93**Required arguments:** 94 95 * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410 96 (Gone) HTTP error. 97 98**Optional arguments:** 99 100 * ``permanent``: Whether the redirect should be permanent. The only 101 difference here is the HTTP status code returned. If ``True``, then the 102 redirect will use status code 301. If ``False``, then the redirect will 103 use status code 302. By default, ``permanent`` is ``True``. 104 105 * ``query_string``: Whether to pass along the GET query string to 106 the new location. If ``True``, then the query string is appended 107 to the URL. If ``False``, then the query string is discarded. By 108 default, ``query_string`` is ``False``. 109 110.. versionadded:: 1.3 111 The ``query_string`` keyword argument is new in Django 1.3. 112 113**Example:** 114 115This example issues a permanent redirect (HTTP status code 301) from 116``/foo/<id>/`` to ``/bar/<id>/``:: 117 118 from django.views.generic.simple import redirect_to 119 120 urlpatterns = patterns('', 121 ('^foo/(?P<id>\d+)/$', redirect_to, {'url': '/bar/%(id)s/'}), 122 ) 123 124This example issues a non-permanent redirect (HTTP status code 302) from 125``/foo/<id>/`` to ``/bar/<id>/``:: 126 127 from django.views.generic.simple import redirect_to 128 129 urlpatterns = patterns('', 130 ('^foo/(?P<id>\d+)/$', redirect_to, {'url': '/bar/%(id)s/', 'permanent': False}), 131 ) 132 133This example returns a 410 HTTP error for requests to ``/bar/``:: 134 135 from django.views.generic.simple import redirect_to 136 137 urlpatterns = patterns('', 138 ('^bar/$', redirect_to, {'url': None}), 139 ) 140 141This example shows how ``"%"`` characters must be written in the URL in order 142to avoid confusion with Python's string formatting markers. If the redirect 143string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised:: 144 145 from django.views.generic.simple import redirect_to 146 147 urlpatterns = patterns('', 148 ('^bar/$', redirect_to, {'url': '%%7Ejacob.'}), 149 ) 150 151.. module:: django.views.generic.date_based 152 153Date-based generic views 154======================== 155 156Date-based generic views (in the module ``django.views.generic.date_based``) 157are views for displaying drilldown pages for date-based data. 158 159``django.views.generic.date_based.archive_index`` 160------------------------------------------------- 161 162**Description:** 163 164A top-level index page showing the "latest" objects, by date. Objects with 165a date in the *future* are not included unless you set ``allow_future`` to 166``True``. 167 168**Required arguments:** 169 170 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 171 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 176**Optional arguments:** 177 178 * ``num_latest``: The number of latest objects to send to the template 179 context. By default, it's 15. 180 181 * ``template_name``: The full name of a template to use in rendering the 182 page. This lets you override the default template name (see below). 183 184 * ``template_loader``: The template loader to use when loading the 185 template. By default, it's ``django.template.loader``. 186 187 * ``extra_context``: A dictionary of values to add to the template 188 context. By default, this is an empty dictionary. If a value in the 189 dictionary is callable, the generic view will call it 190 just before rendering the template. 191 192 * ``allow_empty``: A boolean specifying whether to display the page if no 193 objects are available. If this is ``False`` and no objects are available, 194 the view will raise a 404 instead of displaying an empty page. By 195 default, this is ``True``. 196 197 * ``context_processors``: A list of template-context processors to apply to 198 the view's template. 199 200 * ``mimetype``: The MIME type to use for the resulting document. Defaults 201 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 202 203 * ``allow_future``: A boolean specifying whether to include "future" 204 objects on this page, where "future" means objects in which the field 205 specified in ``date_field`` is greater than the current date/time. By 206 default, this is ``False``. 207 208 * ``template_object_name``: Designates the name of the template variable 209 to use in the template context. By default, this is ``'latest'``. 210 211**Template name:** 212 213If ``template_name`` isn't specified, this view will use the template 214``<app_label>/<model_name>_archive.html`` by default, where: 215 216 * ``<model_name>`` is your model's name in all lowercase. For a model 217 ``StaffMember``, that'd be ``staffmember``. 218 219 * ``<app_label>`` is the right-most part of the full Python path to 220 your model's app. For example, if your model lives in 221 ``apps/blog/models.py``, that'd be ``blog``. 222 223**Template context:** 224 225In addition to ``extra_context``, the template's context will be: 226 227 * ``date_list``: A ``DateQuerySet`` object containing all years that have 228 have objects available according to ``queryset``, represented as 229 ``datetime.datetime`` objects. These are ordered in reverse. This is 230 equivalent to ``queryset.dates(date_field, 'year')[::-1]``. 231 232 * ``latest``: The ``num_latest`` objects in the system, ordered descending 233 by ``date_field``. For example, if ``num_latest`` is ``10``, then 234 ``latest`` will be a list of the latest 10 objects in ``queryset``. 235 236 This variable's name depends on the ``template_object_name`` parameter, 237 which is ``'latest'`` by default. If ``template_object_name`` is 238 ``'foo'``, this variable's name will be ``foo``. 239 240``django.views.generic.date_based.archive_year`` 241------------------------------------------------ 242 243**Description:** 244 245A yearly archive page showing all available months in a given year. Objects 246with a date in the *future* are not displayed unless you set ``allow_future`` 247to ``True``. 248 249**Required arguments:** 250 251 * ``year``: The four-digit year for which the archive serves. 252 253 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 254 255 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 256 the ``QuerySet``'s model that the date-based archive should use to 257 determine the objects on the page. 258 259**Optional arguments:** 260 261 * ``template_name``: The full name of a template to use in rendering the 262 page. This lets you override the default template name (see below). 263 264 * ``template_loader``: The template loader to use when loading the 265 template. By default, it's ``django.template.loader``. 266 267 * ``extra_context``: A dictionary of values to add to the template 268 context. By default, this is an empty dictionary. If a value in the 269 dictionary is callable, the generic view will call it 270 just before rendering the template. 271 272 * ``allow_empty``: A boolean specifying whether to display the page if no 273 objects are available. If this is ``False`` and no objects are available, 274 the view will raise a 404 instead of displaying an empty page. By 275 default, this is ``False``. 276 277 * ``context_processors``: A list of template-context processors to apply to 278 the view's template. 279 280 * ``template_object_name``: Designates the name of the template variable 281 to use in the template context. By default, this is ``'object'``. The 282 view will append ``'_list'`` to the value of this parameter in 283 determining the variable's name. 284 285 * ``make_object_list``: A boolean specifying whether to retrieve the full 286 list of objects for this year and pass those to the template. If ``True``, 287 this list of objects will be made available to the template as 288 ``object_list``. (The name ``object_list`` may be different; see the docs 289 for ``object_list`` in the "Template context" section below.) By default, 290 this is ``False``. 291 292 * ``mimetype``: The MIME type to use for the resulting document. Defaults 293 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 294 295 * ``allow_future``: A boolean specifying whether to include "future" 296 objects on this page, where "future" means objects in which the field 297 specified in ``date_field`` is greater than the current date/time. By 298 default, this is ``False``. 299 300**Template name:** 301 302If ``template_name`` isn't specified, this view will use the template 303``<app_label>/<model_name>_archive_year.html`` by default. 304 305**Template context:** 306 307In addition to ``extra_context``, the template's context will be: 308 309 * ``date_list``: A ``DateQuerySet`` object containing all months that have 310 have objects available according to ``queryset``, represented as 311 ``datetime.datetime`` objects, in ascending order. 312 313 * ``year``: The given year, as a four-character string. 314 315 * ``object_list``: If the ``make_object_list`` parameter is ``True``, this 316 will be set to a list of objects available for the given year, ordered by 317 the date field. This variable's name depends on the 318 ``template_object_name`` parameter, which is ``'object'`` by default. If 319 ``template_object_name`` is ``'foo'``, this variable's name will be 320 ``foo_list``. 321 322 If ``make_object_list`` is ``False``, ``object_list`` will be passed to 323 the template as an empty list. 324 325``django.views.generic.date_based.archive_month`` 326------------------------------------------------- 327 328**Description:** 329 330A monthly archive page showing all objects in a given month. Objects with a 331date in the *future* are not displayed unless you set ``allow_future`` to 332``True``. 333 334**Required arguments:** 335 336 * ``year``: The four-digit year for which the archive serves (a string). 337 338 * ``month``: The month for which the archive serves, formatted according to 339 the ``month_format`` argument. 340 341 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 342 343 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 344 the ``QuerySet``'s model that the date-based archive should use to 345 determine the objects on the page. 346 347**Optional arguments:** 348 349 * ``month_format``: A format string that regulates what format the 350 ``month`` parameter uses. This should be in the syntax accepted by 351 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 352 ``"%b"`` by default, which is a three-letter month abbreviation. To 353 change it to use numbers, use ``"%m"``. 354 355 * ``template_name``: The full name of a template to use in rendering the 356 page. This lets you override the default template name (see below). 357 358 * ``template_loader``: The template loader to use when loading the 359 template. By default, it's ``django.template.loader``. 360 361 * ``extra_context``: A dictionary of values to add to the template 362 context. By default, this is an empty dictionary. If a value in the 363 dictionary is callable, the generic view will call it 364 just before rendering the template. 365 366 * ``allow_empty``: A boolean specifying whether to display the page if no 367 objects are available. If this is ``False`` and no objects are available, 368 the view will raise a 404 instead of displaying an empty page. By 369 default, this is ``False``. 370 371 * ``context_processors``: A list of template-context processors to apply to 372 the view's template. 373 374 * ``template_object_name``: Designates the name of the template variable 375 to use in the template context. By default, this is ``'object'``. The 376 view will append ``'_list'`` to the value of this parameter in 377 determining the variable's name. 378 379 * ``mimetype``: The MIME type to use for the resulting document. Defaults 380 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 381 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 387**Template name:** 388 389If ``template_name`` isn't specified, this view will use the template 390``<app_label>/<model_name>_archive_month.html`` by default. 391 392**Template context:** 393 394.. versionadded:: 1.2 395 The inclusion of ``date_list`` in the template's context is new. 396 397In addition to ``extra_context``, the template's context will be: 398 399 * ``date_list``: A ``DateQuerySet`` object containing all days that have 400 have objects available in the given month, according to ``queryset``, 401 represented as ``datetime.datetime`` objects, in ascending order. 402 403 * ``month``: A ``datetime.date`` object representing the given month. 404 405 * ``next_month``: A ``datetime.date`` object representing the first day of 406 the next month. If the next month is in the future, this will be 407 ``None``. 408 409 * ``previous_month``: A ``datetime.date`` object representing the first day 410 of the previous month. Unlike ``next_month``, this will never be 411 ``None``. 412 413 * ``object_list``: A list of objects available for the given month. This 414 variable's name depends on the ``template_object_name`` parameter, which 415 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 416 this variable's name will be ``foo_list``. 417 418.. _strftime docs: http://docs.python.org/library/time.html#time.strftime 419 420``django.views.generic.date_based.archive_week`` 421------------------------------------------------ 422 423**Description:** 424 425A weekly archive page showing all objects in a given week. Objects with a date 426in the *future* are not displayed unless you set ``allow_future`` to ``True``. 427 428**Required arguments:** 429 430 * ``year``: The four-digit year for which the archive serves (a string). 431 432 * ``week``: The week of the year for which the archive serves (a string). 433 Weeks start with Sunday. 434 435 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 436 437 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 438 the ``QuerySet``'s model that the date-based archive should use to 439 determine the objects on the page. 440 441**Optional arguments:** 442 443 * ``template_name``: The full name of a template to use in rendering the 444 page. This lets you override the default template name (see below). 445 446 * ``template_loader``: The template loader to use when loading the 447 template. By default, it's ``django.template.loader``. 448 449 * ``extra_context``: A dictionary of values to add to the template 450 context. By default, this is an empty dictionary. If a value in the 451 dictionary is callable, the generic view will call it 452 just before rendering the template. 453 454 * ``allow_empty``: A boolean specifying whether to display the page if no 455 objects are available. If this is ``False`` and no objects are available, 456 the view will raise a 404 instead of displaying an empty page. By 457 default, this is ``True``. 458 459 * ``context_processors``: A list of template-context processors to apply to 460 the view's template. 461 462 * ``template_object_name``: Designates the name of the template variable 463 to use in the template context. By default, this is ``'object'``. The 464 view will append ``'_list'`` to the value of this parameter in 465 determining the variable's name. 466 467 * ``mimetype``: The MIME type to use for the resulting document. Defaults 468 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 469 470 * ``allow_future``: A boolean specifying whether to include "future" 471 objects on this page, where "future" means objects in which the field 472 specified in ``date_field`` is greater than the current date/time. By 473 default, this is ``False``. 474 475**Template name:** 476 477If ``template_name`` isn't specified, this view will use the template 478``<app_label>/<model_name>_archive_week.html`` by default. 479 480**Template context:** 481 482In addition to ``extra_context``, the template's context will be: 483 484 * ``week``: A ``datetime.date`` object representing the first day of the 485 given week. 486 487 * ``object_list``: A list of objects available for the given week. This 488 variable's name depends on the ``template_object_name`` parameter, which 489 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 490 this variable's name will be ``foo_list``. 491 492``django.views.generic.date_based.archive_day`` 493----------------------------------------------- 494 495**Description:** 496 497A day archive page showing all objects in a given day. Days in the future throw 498a 404 error, regardless of whether any objects exist for future days, unless 499you set ``allow_future`` to ``True``. 500 501**Required arguments:** 502 503 * ``year``: The four-digit year for which the archive serves (a string). 504 505 * ``month``: The month for which the archive serves, formatted according to 506 the ``month_format`` argument. 507 508 * ``day``: The day for which the archive serves, formatted according to the 509 ``day_format`` argument. 510 511 * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 512 513 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 514 the ``QuerySet``'s model that the date-based archive should use to 515 determine the objects on the page. 516 517**Optional arguments:** 518 519 * ``month_format``: A format string that regulates what format the 520 ``month`` parameter uses. This should be in the syntax accepted by 521 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 522 ``"%b"`` by default, which is a three-letter month abbreviation. To 523 change it to use numbers, use ``"%m"``. 524 525 * ``day_format``: Like ``month_format``, but for the ``day`` parameter. 526 It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). 527 528 * ``template_name``: The full name of a template to use in rendering the 529 page. This lets you override the default template name (see below). 530 531 * ``template_loader``: The template loader to use when loading the 532 template. By default, it's ``django.template.loader``. 533 534 * ``extra_context``: A dictionary of values to add to the template 535 context. By default, this is an empty dictionary. If a value in the 536 dictionary is callable, the generic view will call it 537 just before rendering the template. 538 539 * ``allow_empty``: A boolean specifying whether to display the page if no 540 objects are available. If this is ``False`` and no objects are available, 541 the view will raise a 404 instead of displaying an empty page. By 542 default, this is ``False``. 543 544 * ``context_processors``: A list of template-context processors to apply to 545 the view's template. 546 547 * ``template_object_name``: Designates the name of the template variable 548 to use in the template context. By default, this is ``'object'``. The 549 view will append ``'_list'`` to the value of this parameter in 550 determining the variable's name. 551 552 * ``mimetype``: The MIME type to use for the resulting document. Defaults 553 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 554 555 * ``allow_future``: A boolean specifying whether to include "future" 556 objects on this page, where "future" means objects in which the field 557 specified in ``date_field`` is greater than the current date/time. By 558 default, this is ``False``. 559 560**Template name:** 561 562If ``template_name`` isn't specified, this view will use the template 563``<app_label>/<model_name>_archive_day.html`` by default. 564 565**Template context:** 566 567In addition to ``extra_context``, the template's context will be: 568 569 * ``day``: A ``datetime.date`` object representing the given day. 570 571 * ``next_day``: A ``datetime.date`` object representing the next day. If 572 the next day is in the future, this will be ``None``. 573 574 * ``previous_day``: A ``datetime.date`` object representing the previous day. 575 Unlike ``next_day``, this will never be ``None``. 576 577 * ``object_list``: A list of objects available for the given day. This 578 variable's name depends on the ``template_object_name`` parameter, which 579 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 580 this variable's name will be ``foo_list``. 581 582``django.views.generic.date_based.archive_today`` 583------------------------------------------------- 584 585**Description:** 586 587A day archive page showing all objects for *today*. This is exactly the same as 588``archive_day``, except the ``year``/``month``/``day`` arguments are not used, 589and today's date is used instead. 590 591``django.views.generic.date_based.object_detail`` 592------------------------------------------------- 593 594**Description:** 595 596A page representing an individual object. If the object has a date value in the 597future, the view will throw a 404 error by default, unless you set 598``allow_future`` to ``True``. 599 600**Required arguments:** 601 602 * ``year``: The object's four-digit year (a string). 603 604 * ``month``: The object's month , formatted according to the 605 ``month_format`` argument. 606 607 * ``day``: The object's day , formatted according to the ``day_format`` 608 argument. 609 610 * ``queryset``: A ``QuerySet`` that contains the object. 611 612 * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 613 the ``QuerySet``'s model that the generic view should use to look up the 614 object according to ``year``, ``month`` and ``day``. 615 616 * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. 617 618 If you provide ``object_id``, it should be the value of the primary-key 619 field for the object being displayed on this page. 620 621 Otherwise, ``slug`` should be the slug of the given object, and 622 ``slug_field`` should be the name of the slug field in the ``QuerySet``'s 623 model. By default, ``slug_field`` is ``'slug'``. 624 625**Optional arguments:** 626 627 * ``month_format``: A format string that regulates what format the 628 ``month`` parameter uses. This should be in the syntax accepted by 629 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 630 ``"%b"`` by default, which is a three-letter month abbreviation. To 631 change it to use numbers, use ``"%m"``. 632 633 * ``day_format``: Like ``month_format``, but for the ``day`` parameter. 634 It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). 635 636 * ``template_name``: The full name of a template to use in rendering the 637 page. This lets you override the default template name (see below). 638 639 * ``template_name_field``: The name of a field on the object whose value is 640 the template name to use. This lets you store template names in the data. 641 In other words, if your object has a field ``'the_template'`` that 642 contains a string ``'foo.html'``, and you set ``template_name_field`` to 643 ``'the_template'``, then the generic view for this object will use the 644 template ``'foo.html'``. 645 646 It's a bit of a brain-bender, but it's useful in some cases. 647 648 * ``template_loader``: The template loader to use when loading the 649 template. By default, it's ``django.template.loader``. 650 651 * ``extra_context``: A dictionary of values to add to the template 652 context. By default, this is an empty dictionary. If a value in the 653 dictionary is callable, the generic view will call it 654 just before rendering the template. 655 656 * ``context_processors``: A list of template-context processors to apply to 657 the view's template. 658 659 * ``template_object_name``: Designates the name of the template variable 660 to use in the template context. By default, this is ``'object'``. 661 662 * ``mimetype``: The MIME type to use for the resulting document. Defaults 663 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 664 665 * ``allow_future``: A boolean specifying whether to include "future" 666 objects on this page, where "future" means objects in which the field 667 specified in ``date_field`` is greater than the current date/time. By 668 default, this is ``False``. 669 670**Template name:** 671 672If ``template_name`` isn't specified, this view will use the template 673``<app_label>/<model_name>_detail.html`` by default. 674 675**Template context:** 676 677In addition to ``extra_context``, the template's context will be: 678 679 * ``object``: The object. This variable's name depends on the 680 ``template_object_name`` parameter, which is ``'object'`` by default. If 681 ``template_object_name`` is ``'foo'``, this variable's name will be 682 ``foo``. 683 684.. module:: django.views.generic.list_detail 685 686List/detail generic views 687========================= 688 689The list-detail generic-view framework (in the 690``django.views.generic.list_detail`` module) is similar to the date-based one, 691except the former simply has two views: a list of objects and an individual 692object page. 693 694``django.views.generic.list_detail.object_list`` 695------------------------------------------------ 696 697**Description:** 698 699A page representing a list of objects. 700 701**Required arguments:** 702 703 * ``queryset``: A ``QuerySet`` that represents the objects. 704 705**Optional arguments:** 706 707 * ``paginate_by``: An integer specifying how many objects should be 708 displayed per page. If this is given, the view will paginate objects with 709 ``paginate_by`` objects per page. The view will expect either a ``page`` 710 query string parameter (via ``GET``) or a ``page`` variable specified in 711 the URLconf. See `Notes on pagination`_ below. 712 713 * ``page``: The current page number, as an integer, or the string 714 ``'last'``. This is 1-based. See `Notes on pagination`_ below. 715 716 * ``template_name``: The full name of a template to use in rendering the 717 page. This lets you override the default template name (see below). 718 719 * ``template_loader``: The template loader to use when loading the 720 template. By default, it's ``django.template.loader``. 721 722 * ``extra_context``: A dictionary of values to add to the template 723 context. By default, this is an empty dictionary. If a value in the 724 dictionary is callable, the generic view will call it 725 just before rendering the template. 726 727 * ``allow_empty``: A boolean specifying whether to display the page if no 728 objects are available. If this is ``False`` and no objects are available, 729 the view will raise a 404 instead of displaying an empty page. By 730 default, this is ``True``. 731 732 * ``context_processors``: A list of template-context processors to apply to 733 the view's template. 734 735 * ``template_object_name``: Designates the name of the template variable 736 to use in the template context. By default, this is ``'object'``. The 737 view will append ``'_list'`` to the value of this parameter in 738 determining the variable's name. 739 740 * ``mimetype``: The MIME type to use for the resulting document. Defaults 741 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 742 743**Template name:** 744 745If ``template_name`` isn't specified, this view will use the template 746``<app_label>/<model_name>_list.html`` by default. 747 748**Template context:** 749 750In addition to ``extra_context``, the template's context will be: 751 752 * ``object_list``: The list of objects. This variable's name depends on the 753 ``template_object_name`` parameter, which is ``'object'`` by default. If 754 ``template_object_name`` is ``'foo'``, this variable's name will be 755 ``foo_list``. 756 757 * ``is_paginated``: A boolean representing whether the results are 758 paginated. Specifically, this is set to ``False`` if the number of 759 available objects is less than or equal to ``paginate_by``. 760 761If the results are paginated, the context will contain these extra variables: 762 763 * ``paginator``: An instance of ``django.core.paginator.Paginator``. 764 765 * ``page_obj``: An instance of ``django.core.paginator.Page``. 766 767Notes on pagination 768~~~~~~~~~~~~~~~~~~~ 769 770If ``paginate_by`` is specified, Django will paginate the results. You can 771specify the page number in the URL in one of two ways: 772 773 * Use the ``page`` parameter in the URLconf. For example, this is what 774 your URLconf might look like:: 775 776 (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict)) 777 778 * Pass the page number via the ``page`` query-string parameter. For 779 example, a URL would look like this:: 780 781 /objects/?page=3 782 783 * To loop over all the available page numbers, use the ``page_range`` 784 variable. You can iterate over the list provided by ``page_range`` 785 to create a link to every page of results. 786 787These values and lists are 1-based, not 0-based, so the first page would be 788represented as page ``1``. 789 790For more on pagination, read the :doc:`pagination documentation 791</topics/pagination>`. 792 793As a special case, you are also permitted to use ``last`` as a value for 794``page``:: 795 796 /objects/?page=last 797 798This allows you to access the final page of results without first having to 799determine how many pages there are. 800 801Note that ``page`` *must* be either a valid page number or the value ``last``; 802any other value for ``page`` will result in a 404 error. 803 804``django.views.generic.list_detail.object_detail`` 805-------------------------------------------------- 806 807A page representing an individual object. 808 809**Description:** 810 811A page representing an individual object. 812 813**Required arguments:** 814 815 * ``queryset``: A ``QuerySet`` that contains the object. 816 817 * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. 818 819 If you provide ``object_id``, it should be the value of the primary-key 820 field for the object being displayed on this page. 821 822 Otherwise, ``slug`` should be the slug of the given object, and 823 ``slug_field`` should be the name of the slug field in the ``QuerySet``'s 824 model. By default, ``slug_field`` is ``'slug'``. 825 826**Optional arguments:** 827 828 * ``template_name``: The full name of a template to use in rendering the 829 page. This lets you override the default template name (see below). 830 831 * ``template_name_field``: The name of a field on the object whose value is 832 the template name to use. This lets you store template names in the data. 833 In other words, if your object has a field ``'the_template'`` that 834 contains a string ``'foo.html'``, and you set ``template_name_field`` to 835 ``'the_template'``, then the generic view for this object will use the 836 template ``'foo.html'``. 837 838 It's a bit of a brain-bender, but it's useful in some cases. 839 840 * ``template_loader``: The template loader to use when loading the 841 template. By default, it's ``django.template.loader``. 842 843 * ``extra_context``: A dictionary of values to add to the template 844 context. By default, this is an empty dictionary. If a value in the 845 dictionary is callable, the generic view will call it 846 just before rendering the template. 847 848 * ``context_processors``: A list of template-context processors to apply to 849 the view's template. 850 851 * ``template_object_name``: Designates the name of the template variable 852 to use in the template context. By default, this is ``'object'``. 853 854 * ``mimetype``: The MIME type to use for the resulting document. Defaults 855 to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. 856 857**Template name:** 858 859If ``template_name`` isn't specified, this view will use the template 860``<app_label>/<model_name>_detail.html`` by default. 861 862**Template context:** 863 864In addition to ``extra_context``, the template's context will be: 865 866 * ``object``: The object. This variable's name depends on the 867 ``template_object_name`` parameter, which is ``'object'`` by default. If 868 ``template_object_name`` is ``'foo'``, this variable's name will be 869 ``foo``. 870 871.. module:: django.views.generic.create_update 872 873Create/update/delete generic views 874================================== 875 876The ``django.views.generic.create_update`` module contains a set of functions 877for creating, editing and deleting objects. 878 879``django.views.generic.create_update.create_object`` 880---------------------------------------------------- 881 882**Description:** 883 884A page that displays a form for creating an object, redisplaying the form with 885validation errors (if there are any) and saving the object. 886 887**Required arguments:** 888 889 * Either ``form_class`` or ``model`` is required. 890 891 If you provide ``form_class``, it should be a ``django.forms.ModelForm`` 892 subclass. Use this argument when you need to customize the model's form. 893 See the :doc:`ModelForm docs </topics/forms/modelforms>` for more 894 information. 895 896 Otherwise, ``model`` should be a Django model class and the form used 897 will be a standard ``ModelForm`` for ``model``. 898 899**Optional arguments:** 900 901 * ``post_save_redirect``: A URL to which the view will redirect after 902 saving the object. By default, it's ``object.get_absolute_url()``. 903 904 ``post_save_redirect`` may contain dictionary string formatting, which 905 will be interpolated against the object's field attributes. For example, 906 you could use ``post_save_redirect="/polls/%(slug)s/"``. 907 908 * ``login_required``: A boolean that designates whether a user must be 909 logged in, in order to see the page and save changes. This hooks into the 910 Django :doc:`authentication system </topics/auth>`. By default, this is 911 ``False``. 912 913 If this is ``True``, and a non-logged-in user attempts to visit this page 914 or save the form, Django will redirect the request to ``/accounts/login/``. 915 916 * ``template_name``: The full name of a template to use in rendering the 917 page. This lets you override the default template name (see below). 918 919 * ``template_loader``: The template loader to use when loading the 920 template. By default, it's ``django.template.loader``. 921 922 * ``extra_context``: A dictionary of values to add to the template 923 context. By default, this is an empty dictionary. If a value in the 924 dictionary is callable, the generic view will call it 925 just before rendering the template. 926 927 * ``context_processors``: A list of template-context processors to apply to 928 the view's template. 929 930**Template name:** 931 932If ``template_name`` isn't specified, this view will use the template 933``<app_label>/<model_name>_form.html`` by default. 934 935**Template context:** 936 937In addition to ``extra_context``, the template's context will be: 938 939 * ``form``: A ``django.forms.ModelForm`` instance representing the form 940 for creating the object. This lets you refer to form fields easily in the 941 template system. 942 943 For example, if the model has two fields, ``name`` and ``address``:: 944 945 <form action="" method="post"> 946 <p>{{ form.name.label_tag }} {{ form.name }}</p> 947 <p>{{ form.address.label_tag }} {{ form.address }}</p> 948 </form> 949 950 See the :doc:`forms documentation </topics/forms/index>` for more 951 information about using ``Form`` objects in templates. 952 953``django.views.generic.create_update.update_object`` 954---------------------------------------------------- 955 956**Description:** 957 958A page that displays a form for editing an existing object, redisplaying the 959form with validation errors (if there are any) and saving changes to the 960object. This uses a form automatically generated from the object's 961model class. 962 963**Required arguments:** 964 965 * Either ``form_class`` or ``model`` is required. 966 967 If you provide ``form_class``, it should be a ``django.forms.ModelForm`` 968 subclass. Use this argument when you need to customize the model's form. 969 See the :doc:`ModelForm docs </topics/forms/modelforms>` for more 970 information. 971 972 Otherwise, ``model`` should be a Django model class and the form used 973 will be a standard ``ModelForm`` for ``model``. 974 975 * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. 976 977 If you provide ``object_id``, it should be the value of the primary-key 978 field for the object being displayed on this page. 979 980 Otherwise, ``slug`` should be the slug of the given object, and 981 ``slug_field`` should be the name of the slug field in the ``QuerySet``'s 982 model. By default, ``slug_field`` is ``'slug'``. 983 984**Optional arguments:** 985 986 * ``post_save_redirect``: A URL to which the view will redirect after 987 saving the object. By default, it's ``object.get_absolute_url()``. 988 989 ``post_save_redirect`` may contain dictionary string formatting, which 990 will be interpolated against the object's field attributes. For example, 991 you could use ``post_save_redirect="/polls/%(slug)s/"``. 992 993 * ``login_required``: A boolean that designates whether a user must be 994 logged in, in order to see the page and save changes. This hooks into the 995 Django :doc:`authentication system </topics/auth>`. By default, this is 996 ``False``. 997 998 If this is ``True``, and a non-logged-in user attempts to visit this page 999 or save the form, Django will redirect to :setting:`LOGIN_URL` (which 1000 defaults to ``/accounts/login/``). 1001 1002 * ``template_name``: The full name of a template to use in rendering the 1003 page. This lets you override the default template name (see below). 1004 1005 * ``template_loader``: The template loader to use when loading the 1006 template. By default, it's ``django.template.loader``. 1007 1008 * ``extra_context``: A dictionary of values to add to the template 1009 context. By default, this is an empty dictionary. If a value in the 1010 dictionary is callable, the generic view will call it 1011 just before rendering the template. 1012 1013 * ``context_processors``: A list of template-context processors to apply to 1014 the view's template. 1015 1016 * ``template_object_name``: Designates the name of the template variable 1017 to use in the template context. By default, this is ``'object'``. 1018 1019**Template name:** 1020 1021If ``template_name`` isn't specified, this view will use the template 1022``<app_label>/<model_name>_form.html`` by default. 1023 1024**Template context:** 1025 1026In addition to ``extra_context``, the template's context will be: 1027 1028 * ``form``: A ``django.forms.ModelForm`` instance representing the form 1029 for editing the object. This lets you refer to form fields easily in the 1030 template system. 1031 1032 For example, if the model has two fields, ``name`` and ``address``:: 1033 1034 <form action="" method="post"> 1035 <p>{{ form.name.label_tag }} {{ form.name }}</p> 1036 <p>{{ form.address.label_tag }} {{ form.address }}</p> 1037 </form> 1038 1039 See the :doc:`forms documentation </topics/forms/index>` for more 1040 information about using ``Form`` objects in templates. 1041 1042 * ``object``: The original object being edited. This variable's name 1043 depends on the ``template_object_name`` parameter, which is ``'object'`` 1044 by default. If ``template_object_name`` is ``'foo'``, this variable's 1045 name will be ``foo``. 1046 1047``django.views.generic.create_update.delete_object`` 1048---------------------------------------------------- 1049 1050**Description:** 1051 1052A view that displays a confirmation page and deletes an existing object. The 1053given object will only be deleted if the request method is ``POST``. If this 1054view is fetched via ``GET``, it will display a confirmation page that should 1055contain a form that POSTs to the same URL. 1056 1057**Required arguments:** 1058 1059 * ``model``: The Django model class of the object that the form will 1060 delete. 1061 1062 * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. 1063 1064 If you provide ``object_id``, it should be the value of the primary-key 1065 field for the object being displayed on this page. 1066 1067 Otherwise, ``slug`` should be the slug of the given object, and 1068 ``slug_field`` should be the name of the slug field in the ``QuerySet``'s 1069 model. By default, ``slug_field`` is ``'slug'``. 1070 1071 * ``post_delete_redirect``: A URL to which the view will redirect after 1072 deleting the object. 1073 1074**Optional arguments:** 1075 1076 * ``login_required``: A boolean that designates whether a user must be 1077 logged in, in order to see the page and save changes. This hooks into the 1078 Django :doc:`authentication system </topics/auth>`. By default, this is 1079 ``False``. 1080 1081 If this is ``True``, and a non-logged-in user attempts to visit this page 1082 or save the form, Django will redirect to :setting:`LOGIN_URL` (which 1083 defaults to ``/accounts/login/``). 1084 1085 * ``template_name``: The full name of a template to use in rendering the 1086 page. This lets you override the default template name (see below). 1087 1088 * ``template_loader``: The template loader to use when loading the 1089 template. By default, it's ``django.template.loader``. 1090 1091 * ``extra_context``: A dictionary of values to add to the template 1092 context. By default, this is an empty dictionary. If a value in the 1093 dictionary is callable, the generic view will call it 1094 just before rendering the template. 1095 1096 * ``context_processors``: A list of template-context processors to apply to 1097 the view's template. 1098 1099 * ``template_object_name``: Designates the name of the template variable 1100 to use in the template context. By default, this is ``'object'``. 1101 1102**Template name:** 1103 1104If ``template_name`` isn't specified, this view will use the template 1105``<app_label>/<model_name>_confirm_delete.html`` by default. 1106 1107**Template context:** 1108 1109In addition to ``extra_context``, the template's context will be: 1110 1111 * ``object``: The original object that's about to be deleted. This 1112 variable's name depends on the ``template_object_name`` parameter, which 1113 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 1114 this variable's name will be ``foo``.