Django

Code

Changeset 2797

Show
Ignore:
Timestamp:
04/30/06 22:30:49 (2 years ago)
Author:
adrian
Message:

magic-removal: Proofread and extensively expanded docs/generic_views.txt

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/branches/magic-removal/docs/generic_views.txt

    r2778 r2797  
    1 =================== 
    2 Using generic views 
    3 =================== 
     1============= 
     2Generic views 
     3============= 
    44 
    55Writing Web applications can be monotonous, because we repeat certain patterns 
    …… 
    2929All of these views are used by creating configuration dictionaries in 
    3030your URLconf files and passing those dictionaries as the third member of the 
    31 URLconf tuple. For example, here's the URLconf for the simple weblog app that 
    32 drives the blog on djangoproject.com:: 
     31URLconf tuple for a given pattern. For example, here's the URLconf for the 
     32simple weblog app that drives the blog on djangoproject.com:: 
    3333 
    3434    from django.conf.urls.defaults import * 
    …… 
    4949 
    5050As you can see, this URLconf defines a few options in ``info_dict``. 
    51 ``'queryset'`` tells the generic view which objects to use (all of the 
    52 ``Entry`` objects, in this case), as well as some extra information (it is 
    53 used by the view to determine the model being used, for example). 
     51``'queryset'`` gives the generic view a ``QuerySet`` of objects to use (in this 
     52case, all of the ``Entry`` objects) and tells the generic view which model is 
     53being used. 
    5454 
    5555Documentation of each generic view follows, along with a list of all keyword 
    …… 
    6060 
    6161Most generic views require the ``queryset`` key, which is a ``QuerySet`` 
    62 instance (*not* an instance of the class); see the `database API docs`_ 
    63 for more information about query sets. 
    64  
    65 Using "simple" generic views 
    66 ============================ 
     62instance; see the `database API docs`_ for more information about ``Queryset`` 
     63objects. 
     64 
     65"Simple" generic views 
     66====================== 
    6767 
    6868The ``django.views.generic.simple`` module contains simple views to handle a 
    6969couple of common cases: rendering a template when no view logic is needed, 
    70 and issuing a redirect.  These views are: 
    71  
    72 ``direct_to_template`` 
    73     Renders a given template, passing it a ``{{ params }}`` template variable, 
    74     which is a dictionary of the parameters captured in the URL. This requires 
    75     the ``template`` argument. 
    76  
    77     For example, given the following URL patterns:: 
    78  
    79         urlpatterns = patterns('django.views.generic.simple', 
    80             (r'^foo/$',             'direct_to_template', {'template': 'foo_index'}), 
    81             (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail'}), 
    82         ) 
    83  
    84     ... a request to ``/foo/`` would cause the ``foo_index`` template to be 
    85     rendered, and a request to ``/foo/15/`` would cause the ``foo_detail`` 
    86     template to be rendered with a context variable ``{{ params.id }}`` that is 
    87     set to ``15``. 
    88  
    89 ``redirect_to`` 
    90     Issue a redirect to a given URL. 
    91  
    92     The given URL may contain dict-style string formatting, which will be 
    93     interpolated against the params in the URL.  For example, to redirect from 
    94     ``/foo/<id>/`` to ``/bar/<id>/``, you could use the following urlpattern:: 
    95  
    96         urlpatterns = patterns('django.views.generic.simple', 
    97             ('^foo/(?p<id>\d+)/$', 'redirect_to', {'url' : '/bar/%(id)s/'}), 
    98         ) 
    99  
    100     If the given URL is ``None``, an ``HttpResponseGone`` (410) will be issued. 
    101  
    102 Using date-based generic views 
    103 ============================== 
     70and issuing a redirect. 
     71 
     72``django.views.generic.simple.direct_to_template`` 
     73-------------------------------------------------- 
     74 
     75**Description:** 
     76 
     77Renders a given template, passing it a ``{{ params }}`` template variable, 
     78which is a dictionary of the parameters captured in the URL. 
     79 
     80**Required arguments:** 
     81 
     82    * ``template``: The full name of a template to use. 
     83 
     84**Example:** 
     85 
     86Given the following URL patterns:: 
     87 
     88    urlpatterns = patterns('django.views.generic.simple', 
     89        (r'^foo/$',             'direct_to_template', {'template': 'foo_index.html'}), 
     90        (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}), 
     91    ) 
     92 
     93... a request to ``/foo/`` would render the template ``foo_index.html``, and a 
     94request to ``/foo/15/`` would render the ``foo_detail.html`` with a context 
     95variable ``{{ params.id }}`` that is set to ``15``. 
     96 
     97``django.views.generic.simple.redirect_to`` 
     98------------------------------------------- 
     99 
     100**Description:** 
     101 
     102Redirects to a given URL. 
     103 
     104The given URL may contain dictionary-style string formatting, which will be 
     105interpolated against the parameters captured in the URL. 
     106 
     107If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410). 
     108 
     109**Required arguments:** 
     110 
     111    * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410 
     112      (Gone) HTTP error. 
     113 
     114**Example:** 
     115 
     116This example redirects from ``/foo/<id>/`` to ``/bar/<id>/``:: 
     117 
     118    urlpatterns = patterns('django.views.generic.simple', 
     119        ('^foo/(?p<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}), 
     120    ) 
     121 
     122This example returns a 410 HTTP error for requests to ``/bar/``:: 
     123 
     124    urlpatterns = patterns('django.views.generic.simple', 
     125        ('^bar/$', 'redirect_to', {'url': None}), 
     126    ) 
     127 
     128Date-based generic views 
     129======================== 
    104130 
    105131Date-based generic views (in the module ``django.views.generic.date_based``) 
    106 feature six functions for dealing with date-based data. Besides ``model``, all 
    107 date-based generic views require the ``date_field`` argument. This is the name 
    108 of the field that stores the date the objects should key off of. 
    109  
    110 Additionally, all date-based generic views have the following optional 
    111 arguments: 
    112  
    113     =======================  ================================================== 
    114     Argument                 Description 
    115     =======================  ================================================== 
    116     ``template_name``        Overrides the default template name used for the 
    117                              view. 
    118  
    119     ``extra_lookup_kwargs``  A dictionary of extra lookup parameters (see 
    120                              the `database API docs`_). 
    121  
    122     ``extra_context``        A dictionary of extra data to put into the 
    123                              template's context. 
    124  
    125     ``processors``           A tuple of processors to apply to the 
    126                              ``RequestContext`` of this view's template. See the 
    127                              `RequestContext docs`_ 
    128     =======================  ================================================== 
    129  
    130 .. _database API docs: http://www.djangoproject.com/documentation/db_api/ 
     132are views for displaying drilldown pages for date-based data. 
     133 
     134``django.views.generic.date_based.archive_index`` 
     135------------------------------------------------- 
     136 
     137**Description:** 
     138 
     139A top-level index page showing the "latest" objects, by date. Objects with 
     140a date in the *future* are not included. 
     141 
     142**Required arguments:** 
     143 
     144    * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 
     145 
     146    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 
     147      the ``QuerySet``'s model that the date-based archive should use to 
     148      determine the objects on the page. 
     149 
     150**Optional arguments:** 
     151 
     152    * ``num_latest``: The number of latest objects to send to the template 
     153      context. By default, it's 15. 
     154 
     155    * ``template_name``: The full name of a template to use in rendering the 
     156      page. This lets you override the default template name (see below). 
     157 
     158    * ``template_loader``: The template loader to use when loading the 
     159      template. By default, it's ``django.template.loader``. 
     160 
     161    * ``extra_context``: A dictionary of values to add to the template context. 
     162      If a value in the dictionary is callable, the generic view will call it 
     163      just before rendering the template. By default, this is an empty 
     164      dictionary. 
     165 
     166    * ``allow_empty``: A boolean specifying whether to display the page if no 
     167      objects are available. If this is ``False`` and no objects are available, 
     168      the view will raise a 404 instead of displaying an empty page. By 
     169      default, this is ``False``. 
     170 
     171    * ``context_processors``: A list of template-context processors to apply to 
     172      the view's template. See the `RequestContext docs`_. 
     173 
     174**Template name:** 
     175 
     176If ``template_name`` isn't specified, this view will use the template 
     177``<app_label>/<model_name>_archive.html`` by default, where: 
     178 
     179    * ``<model_name>`` is your model's name in all lowercase. For a model 
     180        ``StaffMember``, that'd be ``staffmember``. 
     181 
     182    * ``<app_label>`` is the right-most part of the full Python path to 
     183        your model's app. For example, if your model lives in 
     184        ``apps/blog/models.py``, that'd be ``blog``. 
     185 
     186**Template context:** 
     187 
     188In addition to ``extra_context``, the template's context will be: 
     189 
     190    * ``date_list``: A list of ``datetime.date`` objects representing all 
     191      years that have objects available according to ``queryset``. These are 
     192      ordered in reverse. This is equivalent to 
     193      ``queryset.dates(date_field, 'year')[::-1]``. 
     194    * ``latest``: The ``num_latest`` objects in the system, ordered descending 
     195      by ``date_field``. For example, if ``num_latest`` is ``10``, then 
     196      ``latest`` will be a list of the latest 10 objects in ``queryset``. 
     197 
    131198.. _RequestContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext 
    132199 
    133 The date-based generic functions are: 
    134  
    135 ``archive_index`` 
    136     A top-level index page showing the "latest" objects. 
    137  
    138     Takes the following optional arguments: 
    139  
    140         =======================  ================================================= 
    141         Argument                 Description 
    142         =======================  ================================================= 
    143         ``num_latest``           The number of items to display on the page. 
    144                                  Defaults to 15. 
    145  
    146         ``allow_empty``          If ``False`` and there are no objects to display, 
    147                                  the view will raise a 404 instead of displaying 
    148                                  an empty index page. ``False`` is default. 
    149         =======================  ================================================= 
    150  
    151     Uses the template ``<app_label>/<model_name>_archive.html`` by default, where: 
    152  
    153         * ``<model_name>`` is your model's name in all lowercase. For a model 
    154           ``StaffMember``, that'd be ``staffmember``. 
    155  
    156         * ``<app_label>`` is the right-most part of the full Python path to 
    157           your model's app. For example, if your model lives in 
    158           ``apps/blog/models.py``, that'd be ``blog``. 
    159  
    160     Has the following template context: 
    161  
    162         ``date_list`` 
    163             List of years with objects 
    164         ``latest`` 
    165             Latest objects by date 
    166  
    167 ``archive_year`` 
    168     Yearly archive. Requires that the ``year`` argument be present in the URL 
    169     pattern. 
    170  
    171     Takes an optional ``allow_empty`` parameter, as ``archive_index``. 
    172  
    173     Uses the template ``<app_label>/<model_name>_archive_year.html`` by default. 
    174  
    175     Has the following template context: 
    176  
    177         ``date_list`` 
    178             List of months in the given year with objects 
    179         ``year`` 
    180             The given year (an integer) 
    181  
    182 ``archive_month`` 
    183     Monthly archive. Requires that ``year`` and ``month`` arguments be given. 
    184     You can pass the additional option ``month_format`` if you'd like to change 
    185     the way months are specified in the URL. 
    186  
    187     ``month_format`` is a format string in the same syntax accepted by Python's 
    188     ``time.strftime``. (See the `strftime docs`_.) It's set to ``"%b"`` by 
    189     default, which is a three-letter month abbreviation. To change it to use 
    190     numbers, use ``"%m"``. 
    191  
    192     Takes an optional ``allow_empty`` parameter, as ``archive_index``. 
    193  
    194     Takes an optional ``template_object_name`` parameter, which designates the 
    195     name of the template variable to use. Default is ``'object'``. 
    196  
    197     Uses the template ``<app_label>/<model_name>_archive_month.html`` by default. 
    198  
    199     Has the following template context: 
    200  
    201         ``month`` 
    202             The given month (a datetime.date object) 
    203         ``next_month`` 
    204             The first day of the next month, or None if the next month is in 
    205             the future (a datetime.date object) 
    206         ``previous_month`` 
    207             The first day of the previous month (a datetime.date object) 
    208         ``object_list`` 
    209             List of objects published in the given month. 
    210  
    211             You can change this variable name from ``object_list`` by using the 
    212             ``template_object_name`` parameter. (See above.) For example, if 
    213             ``template_object_name`` is ``foo``, the variable will be 
    214             ``foo_list``. 
    215  
    216 ``archive_week`` 
    217     Weekly archive. Requires that ``year`` and ``week`` arguments be given. The 
    218     ``week`` argument should be an integer (as a string) representing the week 
    219     number, where weeks start with Sunday. 
    220  
    221     Takes an optional ``template_object_name`` parameter, which designates the 
    222     name of the template variable to use. Default is ``'object'``. 
    223  
    224     Uses the template ``<app_label>/<model_name>_archive_week.html`` by default. 
    225  
    226     Has the following template context: 
    227  
    228         ``object_list`` 
    229             List of objects published on the given day. 
    230  
    231             You can change this variable name from ``object_list`` by using the 
    232             ``template_object_name`` parameter. (See above.) For example, if 
    233             ``template_object_name`` is ``foo``, the variable will be ``foo_list``. 
    234         ``week`` 
    235             The first day of the given week (a datetime.datetime object) 
    236  
    237 ``archive_day`` 
    238     Daily archive. Requires that ``year``, ``month``, and ``day`` arguments be 
    239     given. 
    240  
    241     As in ``archive_month``, you can pass an optional ``month_format``. You can 
    242     also pass ``day_format``, which defaults to ``"%d"`` (day of the month as a 
    243     decimal number, 01-31). 
    244  
    245     Takes an optional ``template_object_name`` parameter, which designates the 
    246     name of the template variable to use. Default is ``'object'``. 
    247  
    248     Uses the template ``<app_label>/<model_name>_archive_day.html`` by default. 
    249  
    250     Has the following template context: 
    251  
    252         ``object_list`` 
    253             List of objects published on the given day. 
    254  
    255             You can change this variable name from ``object_list`` by using the 
    256             ``template_object_name`` parameter. (See above.) For example, if 
    257             ``template_object_name`` is ``foo``, the variable will be 
    258             ``foo_list``. 
    259         ``day`` 
    260             The given day (a datetime.datetime object) 
    261         ``previous_day`` 
    262             The previous day (a datetime.datetime object) 
    263         ``next_day`` 
    264             The next day (a datetime.datetime object), or None if the given 
    265             day is today 
    266  
    267 ``archive_today`` 
    268     List of objects for today. Exactly the same as ``archive_day``, except 
    269     the year/month/day arguments are not given, and today's date is used 
    270     instead. 
    271  
    272 ``object_detail`` 
    273     Individual object page. Requires ``year``/``month``/``day`` arguments like 
    274     ``archive_day``. This function can be used with two types of URLs: either 
    275     ``/year/month/day/slug/`` or ``/year/month/day/object_id/``. 
    276  
    277     If you're using the slug-style URLs, you'll need to have a ``slug`` item in 
    278     your URLconf, and you'll need to pass a ``slug_field`` key in your info 
    279     dictionary to indicate the name of the slug field. 
    280  
    281     If you're using the object_id-style URLs, you'll just need to give the URL 
    282     pattern an ``object_id`` field. 
    283  
    284     You can also pass the ``template_name_field`` argument to indicate that the 
    285     the object stores the name of its template in a field on the object itself. 
    286  
    287     As in ``archive_day``, ``object_detail`` takes optional ``month_format`` 
    288     and ``day_format`` parameters. 
    289  
    290     Takes an optional ``template_object_name`` parameter, which designates the 
    291     name of the template variable to use. Default is ``'object'``. 
     200``django.views.generic.date_based.archive_year`` 
     201------------------------------------------------ 
     202 
     203**Description:** 
     204 
     205A yearly archive page showing all available months in a given year. Objects 
     206with a date in the *future* are not displayed. 
     207 
     208**Required arguments:** 
     209 
     210    * ``year``: The four-digit year for which the archive serves. 
     211 
     212    * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 
     213 
     214    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 
     215      the ``QuerySet``'s model that the date-based archive should use to 
     216      determine the objects on the page. 
     217 
     218**Optional arguments:** 
     219 
     220    * ``template_name``: The full name of a template to use in rendering the 
     221      page. This lets you override the default template name (see below). 
     222 
     223    * ``template_loader``: The template loader to use when loading the 
     224      template. By default, it's ``django.template.loader``. 
     225 
     226    * ``extra_context``: A dictionary of values to add to the template context. 
     227      If a value in the dictionary is callable, the generic view will call it 
     228      just before rendering the template. By default, this is an empty 
     229      dictionary. 
     230 
     231    * ``allow_empty``: A boolean specifying whether to display the page if no 
     232      objects are available. If this is ``False`` and no objects are available, 
     233      the view will raise a 404 instead of displaying an empty page. By 
     234      default, this is ``False``. 
     235 
     236    * ``context_processors``: A list of template-context processors to apply to 
     237      the view's template. See the `RequestContext docs`_. 
     238 
     239**Template name:** 
     240 
     241If ``template_name`` isn't specified, this view will use the template 
     242``<app_label>/<model_name>_archive_year.html`` by default. 
     243 
     244**Template context:** 
     245 
     246In addition to ``extra_context``, the template's context will be: 
     247 
     248    * ``date_list``: A list of ``datetime.date`` objects representing all 
     249      months that have objects available in the given year, according to 
     250      ``queryset``, in ascending order. 
     251    * ``year``: The given year, as a four-character string. 
     252 
     253``django.views.generic.date_based.archive_month`` 
     254------------------------------------------------- 
     255 
     256**Description:** 
     257 
     258A monthly archive page showing all objects in a given month. Objects with a 
     259date in the *future* are not displayed. 
     260 
     261**Required arguments:** 
     262 
     263    * ``year``: The four-digit year for which the archive serves (a string). 
     264 
     265    * ``month``: The month for which the archive serves, formatted according to 
     266      the ``month_format`` argument. 
     267 
     268    * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 
     269 
     270    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 
     271      the ``QuerySet``'s model that the date-based archive should use to 
     272      determine the objects on the page. 
     273 
     274**Optional arguments:** 
     275 
     276    * ``month_format``: A format string that regulates what format the 
     277      ``month`` parameter uses. This should be in the syntax accepted by 
     278      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 
     279      ``"%b"`` by default, which is a three-letter month abbreviation. To 
     280      change it to use numbers, use ``"%m"``. 
     281 
     282    * ``template_name``: The full name of a template to use in rendering the 
     283      page. This lets you override the default template name (see below). 
     284 
     285    * ``template_loader``: The template loader to use when loading the 
     286      template. By default, it's ``django.template.loader``. 
     287 
     288    * ``extra_context``: A dictionary of values to add to the template context. 
     289      If a value in the dictionary is callable, the generic view will call it 
     290      just before rendering the template. By default, this is an empty 
     291      dictionary. 
     292 
     293    * ``allow_empty``: A boolean specifying whether to display the page if no 
     294      objects are available. If this is ``False`` and no objects are available, 
     295      the view will raise a 404 instead of displaying an empty page. By 
     296      default, this is ``False``. 
     297 
     298    * ``context_processors``: A list of template-context processors to apply to 
     299      the view's template. See the `RequestContext docs`_. 
     300 
     301    * ``template_object_name``:  Designates the name of the template variable 
     302       to use in the template context. By default, this is ``'object'``. The 
     303       view will append ``'_list'`` to the value of this parameter in 
     304       determining the variable's name. 
     305 
     306**Template name:** 
     307 
     308If ``template_name`` isn't specified, this view will use the template 
     309``<app_label>/<model_name>_archive_month.html`` by default. 
     310 
     311**Template context:** 
     312 
     313In addition to ``extra_context``, the template's context will be: 
     314 
     315    * ``month``: A ``datetime.date`` object representing the given month. 
     316 
     317    * ``next_month``: A ``datetime.date`` object representing the first day of 
     318      the next month. If the next month is in the future, this will be 
     319      ``None``. 
     320 
     321    * ``previous_month``: A ``datetime.date`` object representing the first day 
     322      of the previous month. Unlike ``next_month``, this will never be 
     323      ``None``. 
     324 
     325    * ``object_list``: A list of objects available for the given month. This 
     326      variable's name depends on the ``template_object_name`` parameter, which 
     327      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 
     328      this variable's name will be ``foo_list``. 
    292329 
    293330.. _strftime docs: http://www.python.org/doc/current/lib/module-time.html#l2h-1941 
    294331 
    295 Using list/detail generic views 
    296 =============================== 
     332``django.views.generic.date_based.archive_week`` 
     333------------------------------------------------ 
     334 
     335**Description:** 
     336 
     337A weekly archive page showing all objects in a given week. Objects with a date 
     338in the *future* are not displayed. 
     339 
     340**Required arguments:** 
     341 
     342    * ``year``: The four-digit year for which the archive serves (a string). 
     343 
     344    * ``week``: The week of the year for which the archive serves (a string). 
     345      Weeks start with Sunday. 
     346 
     347    * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 
     348 
     349    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 
     350      the ``QuerySet``'s model that the date-based archive should use to 
     351      determine the objects on the page. 
     352 
     353**Optional arguments:** 
     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 context. 
     362      If a value in the dictionary is callable, the generic view will call it 
     363      just before rendering the template. By default, this is an empty 
     364      dictionary. 
     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 ``True``. 
     370 
     371    * ``context_processors``: A list of template-context processors to apply to 
     372      the view's template. See the `RequestContext docs`_. 
     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**Template name:** 
     380 
     381If ``template_name`` isn't specified, this view will use the template 
     382``<app_label>/<model_name>_archive_week.html`` by default. 
     383 
     384**Template context:** 
     385 
     386In addition to ``extra_context``, the template's context will be: 
     387 
     388    * ``week``: A ``datetime.date`` object representing the first day of the 
     389      given week. 
     390 
     391    * ``object_list``: A list of objects available for the given week. This 
     392      variable's name depends on the ``template_object_name`` parameter, which 
     393      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 
     394      this variable's name will be ``foo_list``. 
     395 
     396``django.views.generic.date_based.archive_day`` 
     397----------------------------------------------- 
     398 
     399**Description:** 
     400 
     401A day archive page showing all objects in a given day. Days in the future throw 
     402a 404 error, regardless of whether any objects exist for future days. 
     403 
     404**Required arguments:** 
     405 
     406    * ``year``: The four-digit year for which the archive serves (a string). 
     407 
     408    * ``month``: The month for which the archive serves, formatted according to 
     409      the ``month_format`` argument. 
     410 
     411    * ``day``: The day for which the archive serves, formatted according to the 
     412      ``day_format`` argument. 
     413 
     414    * ``queryset``: A ``QuerySet`` of objects for which the archive serves. 
     415 
     416    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 
     417      the ``QuerySet``'s model that the date-based archive should use to 
     418      determine the objects on the page. 
     419 
     420**Optional arguments:** 
     421 
     422    * ``month_format``: A format string that regulates what format the 
     423      ``month`` parameter uses. This should be in the syntax accepted by 
     424      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 
     425      ``"%b"`` by default, which is a three-letter month abbreviation. To 
     426      change it to use numbers, use ``"%m"``. 
     427 
     428    * ``day_format``: Like ``month_format``, but for the ``day`` parameter. 
     429      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). 
     430 
     431    * ``template_name``: The full name of a template to use in rendering the 
     432      page. This lets you override the default template name (see below). 
     433 
     434    * ``template_loader``: The template loader to use when loading the 
     435      template. By default, it's ``django.template.loader``. 
     436 
     437    * ``extra_context``: A dictionary of values to add to the template context. 
     438      If a value in the dictionary is callable, the generic view will call it 
     439      just before rendering the template. By default, this is an empty 
     440      dictionary. 
     441 
     442    * ``allow_empty``: A boolean specifying whether to display the page if no 
     443      objects are available. If this is ``False`` and no objects are available, 
     444      the view will raise a 404 instead of displaying an empty page. By 
     445      default, this is ``False``. 
     446 
     447    * ``context_processors``: A list of template-context processors to apply to 
     448      the view's template. See the `RequestContext docs`_. 
     449 
     450    * ``template_object_name``:  Designates the name of the template variable 
     451       to use in the template context. By default, this is ``'object'``. The 
     452       view will append ``'_list'`` to the value of this parameter in 
     453       determining the variable's name. 
     454 
     455**Template name:** 
     456 
     457If ``template_name`` isn't specified, this view will use the template 
     458``<app_label>/<model_name>_archive_day.html`` by default. 
     459 
     460**Template context:** 
     461 
     462In addition to ``extra_context``, the template's context will be: 
     463 
     464    * ``day``: A ``datetime.date`` object representing the given day. 
     465 
     466    * ``next_day``: A ``datetime.date`` object representing the next day. If 
     467      the next day is in the future, this will be ``None``. 
     468 
     469    * ``previous_day``: A ``datetime.date`` object representing the given day. 
     470      Unlike ``next_day``, this will never be ``None``. 
     471 
     472    * ``object_list``: A list of objects available for the given day. This 
     473      variable's name depends on the ``template_object_name`` parameter, which 
     474      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 
     475      this variable's name will be ``foo_list``. 
     476 
     477``django.views.generic.date_based.archive_today`` 
     478------------------------------------------------- 
     479 
     480**Description:** 
     481 
     482A day archive page showing all objects for *today*. This is exactly the same as 
     483``archive_day``, except the ``year``/``month``/``day`` arguments are not used, 
     484and today's date is used instead. 
     485 
     486``django.views.generic.date_based.object_detail`` 
     487------------------------------------------------- 
     488 
     489**Description:** 
     490 
     491A page representing an individual object. 
     492 
     493**Required arguments:** 
     494 
     495    * ``year``: The object's four-digit year (a string). 
     496 
     497    * ``month``: The object's month , formatted according to the 
     498      ``month_format`` argument. 
     499 
     500    * ``day``: The object's day , formatted according to the ``day_format`` 
     501      argument. 
     502 
     503    * ``queryset``: A ``QuerySet`` that contains the object. 
     504 
     505    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in 
     506      the ``QuerySet``'s model that the generic view should use to look up the 
     507      object according to ``year``, ``month`` and ``day``. 
     508 
     509    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. 
     510 
     511      If you provide ``object_id``, it should be the value of the primary-key 
     512      field for the object being displayed on this page. 
     513 
     514      Otherwise, ``slug`` should be the slug of the given object, and 
     515      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s 
     516      model. 
     517 
     518**Optional arguments:** 
     519 
     520    * ``month_format``: A format string that regulates what format the 
     521      ``month`` parameter uses. This should be in the syntax accepted by 
     522      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 
     523      ``"%b"`` by default, which is a three-letter month abbreviation. To 
     524      change it to use numbers, use ``"%m"``. 
     525 
     526    * ``day_format``: Like ``month_format``, but for the ``day`` parameter. 
     527      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). 
     528 
     529    * ``template_name``: The full name of a template to use in rendering the 
     530      page. This lets you override the default template name (see below). 
     531 
     532    * ``template_name_field``: The name of a field on the object whose value is 
     533      the template name to use. This lets you store template names in the data. 
     534      In other words, if your object has a field ``'the_template'`` that 
     535      contains a string ``'foo.html'``, and you set ``template_name_field`` to 
     536      ``'the_template'``, then the generic view for this object will use the 
     537      template ``'foo.html'``. 
     538 
     539      It's a bit of a brain-bender, but it's useful in some cases. 
     540 
     541    * ``template_loader``: The template loader to use when loading the 
     542      template. By default, it's ``django.template.loader``. 
     543 
     544    * ``extra_context``: A dictionary of values to add to the template context. 
     545      If a value in the dictionary is callable, the generic view will call it 
     546      just before rendering the template. By default, this is an empty 
     547      dictionary. 
     548 
     549    * ``context_processors``: A list of template-context processors to apply to 
     550      the view's template. See the `RequestContext docs`_. 
     551 
     552    * ``template_object_name``:  Designates the name of the template variable 
     553       to use in the template context. By default, this is ``'object'``. 
     554 
     555**Template name:** 
     556 
     557If ``template_name`` isn't specified, this view will use the template 
     558``<app_label>/<model_name>_detail.html`` by default. 
     559 
     560**Template context:** 
     561 
     562In addition to ``extra_context``, the template's context will be: 
     563 
     564    * ``object``: The object. This variable's name depends on the 
     565      ``template_object_name`` parameter, which is ``'object'`` by default. If 
     566      ``template_object_name`` is ``'foo'``, this variable's name will be 
     567      ``foo``. 
     568 
     569List/detail generic views 
     570========================= 
    297571 
    298572The list-detail generic-view framework (in the 
    …… 
    301575object page. 
    302576 
    303 All these views take the same four optional arguments as the date-based ones 
    304 -- and, clearly, they don't accept the ``date_field`` argument. 
    305  
    306 Individual views are: 
    307  
    308 ``object_list`` 
    309     List of objects. 
    310  
    311     Takes the following optional arguments: 
    312  
    313         ========================  ================================================= 
    314         Argument                  Description 
    315         ========================  ================================================= 
    316         ``paginate_by``           If set to an integer, the view will paginate 
    317                                   objects with ``paginate_by`` objects per page. 
    318                                   The view will expect a ``page`` GET param with 
    319                                   the (zero-indexed) page number. 
    320  
    321         ``allow_empty``           If ``False`` and there are no objects to display, 
    322                                   the view will raise a 404 instead of displaying 
    323                                   an empty index page. ``False`` is default. 
    324  
    325         ``template_object_name``  Designates the name of the object template 
    326                                   variable. Default is ``'object'``. 
    327         ========================  ================================================= 
    328  
    329     Uses the template ``<app_label>/<module_name_list>.html`` by default. 
    330  
    331     Has the following template context: 
    332  
    333         ``object_list`` 
    334             List of objects. 
    335  
    336             You can change this variable name from ``object_list`` by using the 
    337             ``template_object_name`` parameter. (See above.) For example, if 
    338             ``template_object_name`` is ``foo``, the variable will be 
    339             ``foo_list``. 
    340         ``is_paginated`` 
    341             Are the results paginated? Either True or False 
    342  
    343     If the results are paginated, the context will have some extra variables: 
    344  
    345         ``results_per_page`` 
    346             Number of objects per page 
    347         ``has_next`` 
    348             Is there a next page? 
    349         ``has_previous`` 
    350             Is there a previous page? 
    351         ``page`` 
    352             The current page number 
    353         ``next`` 
    354             The next page number 
    355         ``previous`` 
    356             The previous page 
    357         ``pages`` 
    358             Number of pages total 
    359         ``hits`` 
    360             Total number of objects 
    361  
    362 ``object_detail`` 
    363     Object detail page. This works like and takes the same arguments as 
    364     the date-based ``object_detail`` above, except this one, obviously, 
    365     does not take the year/month/day arguments. 
    366  
    367 Using create/update/delete generic views 
    368 ======================================== 
     577``django.views.generic.list_detail.object_list`` 
     578------------------------------------------------ 
     579 
     580**Description:** 
     581 
     582A page representing a list of objects. 
     583 
     584**Required arguments:** 
     585 
     586    * ``queryset``: A ``QuerySet`` that represents the objects. 
     587 
     588**Optional arguments:** 
     589 
     590    * ``paginate_by``: An integer specifying how many objects should be 
     591      displayed per page. If this is given, the view will paginate objects with 
     592      ``paginate_by`` objects per page. The view will expect a ``page`` query 
     593      string (GET) parameter containing a zero-indexed page number. 
     594 
     595    * ``template_name``: The full name of a template to use in rendering the 
     596      page. This lets you override the default template name (see below). 
     597 
     598    * ``template_loader``: The template loader to use when loading the 
     599      template. By default, it's ``django.template.loader``. 
     600 
     601    * ``extra_context``: A dictionary of values to add to the template context. 
     602      If a value in the dictionary is callable, the generic view will call it 
     603      just before rendering the template. By default, this is an empty 
     604      dictionary. 
     605 
     606    * ``allow_empty``: A boolean specifying whether to display the page if no 
     607      objects are available. If this is ``False`` and no objects are available, 
     608      the view will raise a 404 instead of displaying an empty page. By 
     609      default, this is ``False``. 
     610 
     611    * ``context_processors``: A list of template-context processors to apply to 
     612      the view's template. See the `RequestContext docs`_. 
     613 
     614    * ``template_object_name``:  Designates the name of the template variable 
     615       to use in the template context. By default, this is ``'object'``. The 
     616       view will append ``'_list'`` to the value of this parameter in 
     617       determining the variable's name. 
     618 
     619**Template name:** 
     620 
     621If ``template_name`` isn't specified, this view will use the template 
     622``<app_label>/<model_name>_list.html`` by default. 
     623 
     624**Template context:** 
     625 
     626In addition to ``extra_context``, the template's context will be: 
     627 
     628    * ``object_list``: The list of objects. This variable's name depends on the 
     629      ``template_object_name`` parameter, which is ``'object'`` by default. If 
     630      ``template_object_name`` is ``'foo'``, this variable's name will be 
     631      ``foo_list``. 
     632 
     633    * ``is_paginated``: A boolean representing whether the results are 
     634      paginated. Specifically, this is set to ``False`` if the number of 
     635      available objects is less than or equal to ``paginate_by``. 
     636 
     637If the results are paginated, the context will contain these extra variables: 
     638 
     639    * ``results_per_page``: The number of objects per page. (Same as the 
     640      ``paginate_by`` parameter.) 
     641 
     642    * ``has_next``: A boolean representing whether there's a next page. 
     643 
     644    * ``has_previous``: A boolean representing whether there's a previous page. 
     645 
     646    * ``page``: The current page number, as an integer. This is 1-based. 
     647 
     648    * ``next``: The next page number, as an integer. If there's no next page, 
     649      this will still be an integer representing the theoretical next-page 
     650      number. This is 1-based. 
     651 
     652    * ``previous``: The previous page number, as an integer. This is 1-based. 
     653 
     654    * ``pages``: The total number of pages, as an integer. 
     655 
     656    * ``hits``: The total number of objects across *all* pages, not just this 
     657      page. 
     658 
     659``django.views.generic.list_detail.object_detail`` 
     660-------------------------------------------------- 
     661 
     662A page representing an individual object. 
     663 
     664**Description:** 
     665 
     666A page representing an individual object. 
     667 
     668**Required arguments:** 
     669 
     670    * ``queryset``: A ``QuerySet`` that contains the object. 
     671 
     672    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. 
     673 
     674      If you provide ``object_id``, it should be the value of the primary-key 
     675      field for the object being displayed on this page. 
     676 
     677      Otherwise, ``slug`` should be the slug of the given object, and 
     678      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s 
     679      model. 
     680 
     681**Optional arguments:** 
     682 
     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 
     686    * ``template_name_field``: The name of a field on the object whose value is 
     687      the template name to use. This lets you store template names in the data. 
     688      In other words, if your object has a field ``'the_template'`` that 
     689      contains a string ``'foo.html'``, and you set ``template_name_field`` to 
     690      ``'the_template'``, then the generic view for this object will use the 
     691      template ``'foo.html'``. 
     692 
     693      It's a bit of a brain-bender, but it's useful in some cases. 
     694 
     695    * ``template_loader``: The template loader to use when loading the 
     696      template. By default, it's ``django.template.loader``. 
     697 
     698    * ``extra_context``: A dictionary of values to add to the template context. 
     699      If a value in the dictionary is callable, the generic view will call it 
     700      just before rendering the template. By default, this is an empty 
     701      dictionary. 
     702 
     703    * ``context_processors``: A list of template-context processors to apply to 
     704      the view's template. See the `RequestContext docs`_. 
     705 
     706    * ``template_object_name``:  Designates the name of the template variable 
     707       to use in the template context. By default, this is ``'object'``. 
     708 
     709**Template name:** 
     710 
     711If ``template_name`` isn't specified, this view will use the template 
     712``<app_label>/<model_name>_detail.html`` by default. 
     713 
     714**Template context:** 
     715 
     716In addition to ``extra_context``, the template's context will be: 
     717 
     718    * ``object``: The object. This variable's name depends on the 
     719      ``template_object_name`` parameter, which is ``'object'`` by default. If 
     720      ``template_object_name`` is ``'foo'``, this variable's name will be 
     721      ``foo``. 
     722 
     723Create/update/delete generic views 
     724================================== 
    369725 
    370726The ``django.views.generic.create_update`` module contains a set of functions 
    371 for creating, editing and deleting objects. These views take the same global 
    372 arguments as the above sets of generic views. They also have a 
    373 ``login_required`` argument which, if ``True``, requires the user to be logged 
    374 in to have access to the page. (``login_required`` defaults to ``False``.) 
    375  
    376 The create/update/delete views are: 
    377  
    378 ``create_object`` 
    379     Create a new object. Has an extra optional argument, ``post_save_redirect``, 
    380     which is a URL to which the view will redirect after saving the object. 
    381     It defaults to ``object.get_absolute_url()``. 
    382  
    383     ``post_save_redirect`` may contain dictionary string formatting, which will 
    384     be interpolated against the object's field attributes. For example, you 
    385     could use ``post_save_redirect="/polls/%(slug)s/"``. 
    386  
    387     Uses the template ``<app_label>/<model_name>_form.html`` by default. This 
    388     is the same template as the ``update_object`` view below. Your template can 
    389     tell the difference by the presence or absence of ``{{ object }}`` in the 
    390     context. 
    391  
    392     Has the following template context: 
    393  
    394         form 
    395             The form wrapper for the object 
    396  
    397     .. admonition:: Note 
    398  
    399         See the `manipulator and formfield documentation`_ for more information 
    400         about using form wrappers in templates. 
    401  
    402 .. _`manipulator and formfield documentation`: http://www.djangoproject.com/documentation/forms/ 
    403  
    404 ``update_object`` 
    405     Edit an existing object. Has the same extra slug/ID parameters as 
    406     ``list_detail.object_detail`` does (see above), and the same 
    407     ``post_save_redirect`` as ``create_object`` does. 
    408  
    409     Takes an optional ``template_object_name`` parameter, which designates the 
    410     name of the template variable to use. Default is ``'object'``. 
    411  
    412     Uses the template ``<app_label>/<model_name>_form.html`` by default. 
    413  
    414     Has the following template context: 
    415  
    416         form 
    417             The form wrapper for the object 
    418         object 
    419             The original object being edited. 
    420  
    421             You can change this variable name from ``object`` by using the 
    422             ``template_object_name`` parameter. (See above.) For example, if 
    423             ``template_object_name`` is ``foo``, the variable will be ``foo`` 
    424             instead of ``object``. 
    425  
    426 ``delete_object`` 
    427     Delete an existing object. The given object will only actually be deleted 
    428     if the request method is POST. If this view is fetched with GET, it will 
    429     display a confirmation page that should contain a form that POSTs to the 
    430     same URL. 
    431  
    432     You must provide the ``post_delete_redirect`` argument to this function, so 
    433     that the view knows where to go after the object is deleted. 
    434  
    435     If fetched with GET, it uses the template 
    436     ``<app_label>/<model_name>_confirm_delete`` by default. It uses no template 
    437     if POSTed -- it simply deletes the object and redirects. 
    438  
    439     Takes an optional ``template_object_name`` parameter, which designates the 
    440     name of the template variable to use. Default is ``'object'``. 
    441  
    442     Has the following template context: 
    443  
    444         object 
    445             The object about to be deleted. 
    446  
    447             You can change this variable name from ``object`` by using the 
    448             ``template_object_name`` parameter. (See above.) For example, if 
    449             ``template_object_name`` is ``foo``, the variable will be ``foo`` 
    450             instead of ``object``. 
    451  
     727for creating, editing and deleting objects. 
     728 
     729``django.views.generic.create_update.create_object`` 
     730---------------------------------------------------- 
     731 
     732**Description:** 
     733 
     734A page that displays a form for creating an object, redisplaying the form with 
     735validation errors (if there are any) and saving the object. This uses the 
     736automatic manipulators that come with Django models. 
     737 
     738**Required arguments:**