| ============= |
| Generic views |
| ============= |
| |
| Writing Web applications can be monotonous, because we repeat certain patterns |
| again and again. In Django, the most common of these patterns have been |
| abstracted into "generic views" that let you quickly provide common views of |
| an object without actually needing to write any Python code. |
| |
| Django's generic views contain the following: |
| |
| * A set of views for doing list/detail interfaces (for example, |
| Django's `documentation index`_ and `detail pages`_). |
| |
| * A set of views for year/month/day archive pages and associated |
| detail and "latest" pages (for example, the Django weblog's year_, |
| month_, day_, detail_, and latest_ pages). |
| |
| * A set of views for creating, editing, and deleting objects. |
| |
| .. _`documentation index`: http://www.djangoproject.com/documentation/ |
| .. _`detail pages`: http://www.djangoproject.com/documentation/faq/ |
| .. _year: http://www.djangoproject.com/weblog/2005/ |
| .. _month: http://www.djangoproject.com/weblog/2005/jul/ |
| .. _day: http://www.djangoproject.com/weblog/2005/jul/20/ |
| .. _detail: http://www.djangoproject.com/weblog/2005/jul/20/autoreload/ |
| .. _latest: http://www.djangoproject.com/weblog/ |
| |
| All of these views are used by creating configuration dictionaries in |
| your URLconf files and passing those dictionaries as the third member of the |
| URLconf tuple for a given pattern. For example, here's the URLconf for the |
| simple weblog app that drives the blog on djangoproject.com:: |
| |
| from django.conf.urls.defaults import * |
| from django_website.apps.blog.models import Entry |
| |
| info_dict = { |
| 'queryset': Entry.objects.all(), |
| 'date_field': 'pub_date', |
| } |
| |
| urlpatterns = patterns('django.views.generic.date_based', |
| (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/(?P<slug>[-\w]+)/$', 'object_detail', dict(info_dict, slug_field='slug')), |
| (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/$', 'archive_day', info_dict), |
| (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$', 'archive_month', info_dict), |
| (r'^(?P<year>\d{4})/$', 'archive_year', info_dict), |
| (r'^/?$', 'archive_index', info_dict), |
| ) |
| |
| As you can see, this URLconf defines a few options in ``info_dict``. |
| ``'queryset'`` gives the generic view a ``QuerySet`` of objects to use (in this |
| case, all of the ``Entry`` objects) and tells the generic view which model is |
| being used. |
| |
| Documentation of each generic view follows, along with a list of all keyword |
| arguments that a generic view expects. Remember that as in the example above, |
| arguments may either come from the URL pattern (as ``month``, ``day``, |
| ``year``, etc. do above) or from the additional-information dictionary (as for |
| ``queryset``, ``date_field``, etc.). |
| |
| Most generic views require the ``queryset`` key, which is a ``QuerySet`` |
| instance; see the `database API docs`_ for more information about ``Queryset`` |
| objects. |
| |
| Most views also take an optional ``extra_context`` dictionary that you can use |
| to pass any auxiliary information you wish to the view. The values in the |
| ``extra_context`` dictionary can be either functions (or other callables) or |
| other objects. Functions are evaluated just before they are passed to the |
| template. However, note that QuerySets retrieve and cache their data when they |
| are first evaluated, so if you want to pass in a QuerySet via |
| ``extra_context`` that is always fresh you need to wrap it in a function or |
| lambda that returns the QuerySet. |
| |
| .. _database API docs: ../db_api/ |
| |
| "Simple" generic views |
| ====================== |
| |
| The ``django.views.generic.simple`` module contains simple views to handle a |
| couple of common cases: rendering a template when no view logic is needed, |
| and issuing a redirect. |
| |
| ``django.views.generic.simple.direct_to_template`` |
| -------------------------------------------------- |
| |
| **Description:** |
| |
| Renders a given template, passing it a ``{{ params }}`` template variable, |
| which is a dictionary of the parameters captured in the URL. |
| |
| **Required arguments:** |
| |
| * ``template``: The full name of a template to use. |
| |
| **Optional arguments:** |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| **Example:** |
| |
| Given the following URL patterns:: |
| |
| urlpatterns = patterns('django.views.generic.simple', |
| (r'^foo/$', 'direct_to_template', {'template': 'foo_index.html'}), |
| (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}), |
| ) |
| |
| ... a request to ``/foo/`` would render the template ``foo_index.html``, and a |
| request to ``/foo/15/`` would render the ``foo_detail.html`` with a context |
| variable ``{{ params.id }}`` that is set to ``15``. |
| |
| ``django.views.generic.simple.redirect_to`` |
| ------------------------------------------- |
| |
| **Description:** |
| |
| Redirects to a given URL. |
| |
| The given URL may contain dictionary-style string formatting, which will be |
| interpolated against the parameters captured in the URL. |
| |
| If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410). |
| |
| **Required arguments:** |
| |
| * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410 |
| (Gone) HTTP error. |
| |
| **Example:** |
| |
| This example redirects from ``/foo/<id>/`` to ``/bar/<id>/``:: |
| |
| urlpatterns = patterns('django.views.generic.simple', |
| ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}), |
| ) |
| |
| This example returns a 410 HTTP error for requests to ``/bar/``:: |
| |
| urlpatterns = patterns('django.views.generic.simple', |
| ('^bar/$', 'redirect_to', {'url': None}), |
| ) |
| |
| Date-based generic views |
| ======================== |
| |
| Date-based generic views (in the module ``django.views.generic.date_based``) |
| are views for displaying drilldown pages for date-based data. |
| |
| ``django.views.generic.date_based.archive_index`` |
| ------------------------------------------------- |
| |
| **Description:** |
| |
| A top-level index page showing the "latest" objects, by date. Objects with |
| a date in the *future* are not included unless you set ``allow_future`` to |
| ``True``. |
| |
| **Required arguments:** |
| |
| * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
| |
| * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
| the ``QuerySet``'s model that the date-based archive should use to |
| determine the objects on the page. |
| |
| **Optional arguments:** |
| |
| * ``num_latest``: The number of latest objects to send to the template |
| context. By default, it's 15. |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``allow_empty``: A boolean specifying whether to display the page if no |
| objects are available. If this is ``False`` and no objects are available, |
| the view will raise a 404 instead of displaying an empty page. By |
| default, this is ``False``. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``mimetype``: The MIME type to use for the resulting document. Defaults |
| to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
| |
| * ``allow_future``: A boolean specifying whether to include "future" |
| objects on this page, where "future" means objects in which the field |
| specified in ``date_field`` is greater than the current date/time. By |
| default, this is ``False``. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_archive.html`` by default, where: |
| |
| * ``<model_name>`` is your model's name in all lowercase. For a model |
| ``StaffMember``, that'd be ``staffmember``. |
| |
| * ``<app_label>`` is the right-most part of the full Python path to |
| your model's app. For example, if your model lives in |
| ``apps/blog/models.py``, that'd be ``blog``. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``date_list``: A list of ``datetime.date`` objects representing all |
| years that have objects available according to ``queryset``. These are |
| ordered in reverse. This is equivalent to |
| ``queryset.dates(date_field, 'year')[::-1]``. |
| * ``latest``: The ``num_latest`` objects in the system, ordered descending |
| by ``date_field``. For example, if ``num_latest`` is ``10``, then |
| ``latest`` will be a list of the latest 10 objects in ``queryset``. |
| |
| .. _RequestContext docs: ../templates_python/#subclassing-context-djangocontext |
| |
| ``django.views.generic.date_based.archive_year`` |
| ------------------------------------------------ |
| |
| **Description:** |
| |
| A yearly archive page showing all available months in a given year. Objects |
| with a date in the *future* are not displayed unless you set ``allow_future`` |
| to ``True``. |
| |
| **Required arguments:** |
| |
| * ``year``: The four-digit year for which the archive serves. |
| |
| * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
| |
| * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
| the ``QuerySet``'s model that the date-based archive should use to |
| determine the objects on the page. |
| |
| **Optional arguments:** |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``allow_empty``: A boolean specifying whether to display the page if no |
| objects are available. If this is ``False`` and no objects are available, |
| the view will raise a 404 instead of displaying an empty page. By |
| default, this is ``False``. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. The |
| view will append ``'_list'`` to the value of this parameter in |
| determining the variable's name. |
| |
| * ``make_object_list``: A boolean specifying whether to retrieve the full |
| list of objects for this year and pass those to the template. If ``True``, |
| this list of objects will be made available to the template as |
| ``object_list``. (The name ``object_list`` may be different; see the docs |
| for ``object_list`` in the "Template context" section below.) By default, |
| this is ``False``. |
| |
| * ``mimetype``: The MIME type to use for the resulting document. Defaults |
| to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
| |
| * ``allow_future``: A boolean specifying whether to include "future" |
| objects on this page, where "future" means objects in which the field |
| specified in ``date_field`` is greater than the current date/time. By |
| default, this is ``False``. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_archive_year.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``date_list``: A list of ``datetime.date`` objects representing all |
| months that have objects available in the given year, according to |
| ``queryset``, in ascending order. |
| |
| * ``year``: The given year, as a four-character string. |
| |
| * ``object_list``: If the ``make_object_list`` parameter is ``True``, this |
| will be set to a list of objects available for the given year, ordered by |
| the date field. This variable's name depends on the |
| ``template_object_name`` parameter, which is ``'object'`` by default. If |
| ``template_object_name`` is ``'foo'``, this variable's name will be |
| ``foo_list``. |
| |
| If ``make_object_list`` is ``False``, ``object_list`` will be passed to |
| the template as an empty list. |
| |
| ``django.views.generic.date_based.archive_month`` |
| ------------------------------------------------- |
| |
| **Description:** |
| |
| A monthly archive page showing all objects in a given month. Objects with a |
| date in the *future* are not displayed unless you set ``allow_future`` to |
| ``True``. |
| |
| **Required arguments:** |
| |
| * ``year``: The four-digit year for which the archive serves (a string). |
| |
| * ``month``: The month for which the archive serves, formatted according to |
| the ``month_format`` argument. |
| |
| * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
| |
| * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
| the ``QuerySet``'s model that the date-based archive should use to |
| determine the objects on the page. |
| |
| **Optional arguments:** |
| |
| * ``month_format``: A format string that regulates what format the |
| ``month`` parameter uses. This should be in the syntax accepted by |
| Python's ``time.strftime``. (See the `strftime docs`_.) It's set to |
| ``"%b"`` by default, which is a three-letter month abbreviation. To |
| change it to use numbers, use ``"%m"``. |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``allow_empty``: A boolean specifying whether to display the page if no |
| objects are available. If this is ``False`` and no objects are available, |
| the view will raise a 404 instead of displaying an empty page. By |
| default, this is ``False``. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. The |
| view will append ``'_list'`` to the value of this parameter in |
| determining the variable's name. |
| |
| * ``mimetype``: The MIME type to use for the resulting document. Defaults |
| to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
| |
| * ``allow_future``: A boolean specifying whether to include "future" |
| objects on this page, where "future" means objects in which the field |
| specified in ``date_field`` is greater than the current date/time. By |
| default, this is ``False``. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_archive_month.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``month``: A ``datetime.date`` object representing the given month. |
| |
| * ``next_month``: A ``datetime.date`` object representing the first day of |
| the next month. If the next month is in the future, this will be |
| ``None``. |
| |
| * ``previous_month``: A ``datetime.date`` object representing the first day |
| of the previous month. Unlike ``next_month``, this will never be |
| ``None``. |
| |
| * ``object_list``: A list of objects available for the given month. This |
| variable's name depends on the ``template_object_name`` parameter, which |
| is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, |
| this variable's name will be ``foo_list``. |
| |
| .. _strftime docs: http://www.python.org/doc/current/lib/module-time.html#l2h-1941 |
| |
| ``django.views.generic.date_based.archive_week`` |
| ------------------------------------------------ |
| |
| **Description:** |
| |
| A weekly archive page showing all objects in a given week. Objects with a date |
| in the *future* are not displayed unless you set ``allow_future`` to ``True``. |
| |
| **Required arguments:** |
| |
| * ``year``: The four-digit year for which the archive serves (a string). |
| |
| * ``week``: The week of the year for which the archive serves (a string). |
| Weeks start with Sunday. |
| |
| * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
| |
| * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
| the ``QuerySet``'s model that the date-based archive should use to |
| determine the objects on the page. |
| |
| **Optional arguments:** |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``allow_empty``: A boolean specifying whether to display the page if no |
| objects are available. If this is ``False`` and no objects are available, |
| the view will raise a 404 instead of displaying an empty page. By |
| default, this is ``True``. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. The |
| view will append ``'_list'`` to the value of this parameter in |
| determining the variable's name. |
| |
| * ``mimetype``: The MIME type to use for the resulting document. Defaults |
| to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
| |
| * ``allow_future``: A boolean specifying whether to include "future" |
| objects on this page, where "future" means objects in which the field |
| specified in ``date_field`` is greater than the current date/time. By |
| default, this is ``False``. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_archive_week.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``week``: A ``datetime.date`` object representing the first day of the |
| given week. |
| |
| * ``object_list``: A list of objects available for the given week. This |
| variable's name depends on the ``template_object_name`` parameter, which |
| is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, |
| this variable's name will be ``foo_list``. |
| |
| ``django.views.generic.date_based.archive_day`` |
| ----------------------------------------------- |
| |
| **Description:** |
| |
| A day archive page showing all objects in a given day. Days in the future throw |
| a 404 error, regardless of whether any objects exist for future days, unless |
| you set ``allow_future`` to ``True``. |
| |
| **Required arguments:** |
| |
| * ``year``: The four-digit year for which the archive serves (a string). |
| |
| * ``month``: The month for which the archive serves, formatted according to |
| the ``month_format`` argument. |
| |
| * ``day``: The day for which the archive serves, formatted according to the |
| ``day_format`` argument. |
| |
| * ``queryset``: A ``QuerySet`` of objects for which the archive serves. |
| |
| * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
| the ``QuerySet``'s model that the date-based archive should use to |
| determine the objects on the page. |
| |
| **Optional arguments:** |
| |
| * ``month_format``: A format string that regulates what format the |
| ``month`` parameter uses. This should be in the syntax accepted by |
| Python's ``time.strftime``. (See the `strftime docs`_.) It's set to |
| ``"%b"`` by default, which is a three-letter month abbreviation. To |
| change it to use numbers, use ``"%m"``. |
| |
| * ``day_format``: Like ``month_format``, but for the ``day`` parameter. |
| It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``allow_empty``: A boolean specifying whether to display the page if no |
| objects are available. If this is ``False`` and no objects are available, |
| the view will raise a 404 instead of displaying an empty page. By |
| default, this is ``False``. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. The |
| view will append ``'_list'`` to the value of this parameter in |
| determining the variable's name. |
| |
| * ``mimetype``: The MIME type to use for the resulting document. Defaults |
| to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
| |
| * ``allow_future``: A boolean specifying whether to include "future" |
| objects on this page, where "future" means objects in which the field |
| specified in ``date_field`` is greater than the current date/time. By |
| default, this is ``False``. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_archive_day.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``day``: A ``datetime.date`` object representing the given day. |
| |
| * ``next_day``: A ``datetime.date`` object representing the next day. If |
| the next day is in the future, this will be ``None``. |
| |
| * ``previous_day``: A ``datetime.date`` object representing the given day. |
| Unlike ``next_day``, this will never be ``None``. |
| |
| * ``object_list``: A list of objects available for the given day. This |
| variable's name depends on the ``template_object_name`` parameter, which |
| is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, |
| this variable's name will be ``foo_list``. |
| |
| ``django.views.generic.date_based.archive_today`` |
| ------------------------------------------------- |
| |
| **Description:** |
| |
| A day archive page showing all objects for *today*. This is exactly the same as |
| ``archive_day``, except the ``year``/``month``/``day`` arguments are not used, |
| and today's date is used instead. |
| |
| ``django.views.generic.date_based.object_detail`` |
| ------------------------------------------------- |
| |
| **Description:** |
| |
| A page representing an individual object. If the object has a date value in the |
| future, the view will throw a 404 error by default, unless you set |
| ``allow_future`` to ``True``. |
| |
| **Required arguments:** |
| |
| * ``year``: The object's four-digit year (a string). |
| |
| * ``month``: The object's month , formatted according to the |
| ``month_format`` argument. |
| |
| * ``day``: The object's day , formatted according to the ``day_format`` |
| argument. |
| |
| * ``queryset``: A ``QuerySet`` that contains the object. |
| |
| * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in |
| the ``QuerySet``'s model that the generic view should use to look up the |
| object according to ``year``, ``month`` and ``day``. |
| |
| * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. |
| |
| If you provide ``object_id``, it should be the value of the primary-key |
| field for the object being displayed on this page. |
| |
| Otherwise, ``slug`` should be the slug of the given object, and |
| ``slug_field`` should be the name of the slug field in the ``QuerySet``'s |
| model. |
| |
| **Optional arguments:** |
| |
| * ``month_format``: A format string that regulates what format the |
| ``month`` parameter uses. This should be in the syntax accepted by |
| Python's ``time.strftime``. (See the `strftime docs`_.) It's set to |
| ``"%b"`` by default, which is a three-letter month abbreviation. To |
| change it to use numbers, use ``"%m"``. |
| |
| * ``day_format``: Like ``month_format``, but for the ``day`` parameter. |
| It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_name_field``: The name of a field on the object whose value is |
| the template name to use. This lets you store template names in the data. |
| In other words, if your object has a field ``'the_template'`` that |
| contains a string ``'foo.html'``, and you set ``template_name_field`` to |
| ``'the_template'``, then the generic view for this object will use the |
| template ``'foo.html'``. |
| |
| It's a bit of a brain-bender, but it's useful in some cases. |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. |
| |
| * ``mimetype``: The MIME type to use for the resulting document. Defaults |
| to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
| |
| * ``allow_future``: A boolean specifying whether to include "future" |
| objects on this page, where "future" means objects in which the field |
| specified in ``date_field`` is greater than the current date/time. By |
| default, this is ``False``. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_detail.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``object``: The object. This variable's name depends on the |
| ``template_object_name`` parameter, which is ``'object'`` by default. If |
| ``template_object_name`` is ``'foo'``, this variable's name will be |
| ``foo``. |
| |
| List/detail generic views |
| ========================= |
| |
| The list-detail generic-view framework (in the |
| ``django.views.generic.list_detail`` module) is similar to the date-based one, |
| except the former simply has two views: a list of objects and an individual |
| object page. |
| |
| ``django.views.generic.list_detail.object_list`` |
| ------------------------------------------------ |
| |
| **Description:** |
| |
| A page representing a list of objects. |
| |
| **Required arguments:** |
| |
| * ``queryset``: A ``QuerySet`` that represents the objects. |
| |
| **Optional arguments:** |
| |
| * ``paginate_by``: An integer specifying how many objects should be |
| displayed per page. If this is given, the view will paginate objects with |
| ``paginate_by`` objects per page. The view will expect either a ``page`` |
| query string parameter (via ``GET``) containing a 1-based page |
| number, or a ``page`` variable specified in the URLconf. See |
| "Notes on pagination" below. |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``allow_empty``: A boolean specifying whether to display the page if no |
| objects are available. If this is ``False`` and no objects are available, |
| the view will raise a 404 instead of displaying an empty page. By |
| default, this is ``False``. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. The |
| view will append ``'_list'`` to the value of this parameter in |
| determining the variable's name. |
| |
| * ``mimetype``: The MIME type to use for the resulting document. Defaults |
| to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_list.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``object_list``: The list of objects. This variable's name depends on the |
| ``template_object_name`` parameter, which is ``'object'`` by default. If |
| ``template_object_name`` is ``'foo'``, this variable's name will be |
| ``foo_list``. |
| |
| * ``is_paginated``: A boolean representing whether the results are |
| paginated. Specifically, this is set to ``False`` if the number of |
| available objects is less than or equal to ``paginate_by``. |
| |
| If the results are paginated, the context will contain these extra variables: |
| |
| * ``results_per_page``: The number of objects per page. (Same as the |
| ``paginate_by`` parameter.) |
| |
| * ``has_next``: A boolean representing whether there's a next page. |
| |
| * ``has_previous``: A boolean representing whether there's a previous page. |
| |
| * ``page``: The current page number, as an integer. This is 1-based. |
| |
| * ``next``: The next page number, as an integer. If there's no next page, |
| this will still be an integer representing the theoretical next-page |
| number. This is 1-based. |
| |
| * ``previous``: The previous page number, as an integer. This is 1-based. |
| |
| * `last_on_page`: The number of the |
| last result on the current page. This is 1-based. |
| |
| * `first_on_page`: The number of the |
| first result on the current page. This is 1-based. |
| |
| * ``pages``: The total number of pages, as an integer. |
| |
| * ``hits``: The total number of objects across *all* pages, not just this |
| page. |
| |
| Notes on pagination |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| If ``paginate_by`` is specified, Django will paginate the results. You can |
| specify the page number in the URL in one of two ways: |
| |
| * Use the ``page`` parameter in the URLconf. For example, this is what |
| your URLconf might look like:: |
| |
| (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict)) |
| |
| * Pass the page number via the ``page`` query-string parameter. For |
| example, a URL would look like this: |
| |
| /objects/?page=3 |
| |
| In both cases, ``page`` is 1-based, not 0-based, so the first page would be |
| represented as page ``1``. |
| |
| ``django.views.generic.list_detail.object_detail`` |
| -------------------------------------------------- |
| |
| A page representing an individual object. |
| |
| **Description:** |
| |
| A page representing an individual object. |
| |
| **Required arguments:** |
| |
| * ``queryset``: A ``QuerySet`` that contains the object. |
| |
| * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. |
| |
| If you provide ``object_id``, it should be the value of the primary-key |
| field for the object being displayed on this page. |
| |
| Otherwise, ``slug`` should be the slug of the given object, and |
| ``slug_field`` should be the name of the slug field in the ``QuerySet``'s |
| model. |
| |
| **Optional arguments:** |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_name_field``: The name of a field on the object whose value is |
| the template name to use. This lets you store template names in the data. |
| In other words, if your object has a field ``'the_template'`` that |
| contains a string ``'foo.html'``, and you set ``template_name_field`` to |
| ``'the_template'``, then the generic view for this object will use the |
| template ``'foo.html'``. |
| |
| It's a bit of a brain-bender, but it's useful in some cases. |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. |
| |
| * ``mimetype``: The MIME type to use for the resulting document. Defaults |
| to the value of the ``DEFAULT_CONTENT_TYPE`` setting. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_detail.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``object``: The object. This variable's name depends on the |
| ``template_object_name`` parameter, which is ``'object'`` by default. If |
| ``template_object_name`` is ``'foo'``, this variable's name will be |
| ``foo``. |
| |
| Create/update/delete generic views |
| ================================== |
| |
| The ``django.views.generic.create_update`` module contains a set of functions |
| for creating, editing and deleting objects. |
| |
| ``django.views.generic.create_update.create_object`` |
| ---------------------------------------------------- |
| |
| **Description:** |
| |
| A page that displays a form for creating an object, redisplaying the form with |
| validation errors (if there are any) and saving the object. This uses the |
| automatic manipulators that come with Django models. |
| |
| **Required arguments:** |
| |
| * ``model``: The Django model class of the object that the form will |
| create. |
| |
| **Optional arguments:** |
| |
| * ``post_save_redirect``: A URL to which the view will redirect after |
| saving the object. By default, it's ``object.get_absolute_url()``. |
| |
| ``post_save_redirect`` may contain dictionary string formatting, which |
| will be interpolated against the object's field attributes. For example, |
| you could use ``post_save_redirect="/polls/%(slug)s/"``. |
| |
| * ``login_required``: A boolean that designates whether a user must be |
| logged in, in order to see the page and save changes. This hooks into the |
| Django `authentication system`_. By default, this is ``False``. |
| |
| If this is ``True``, and a non-logged-in user attempts to visit this page |
| or save the form, Django will redirect the request to ``/accounts/login/``. |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_form.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``form``: A ``django.oldforms.FormWrapper`` instance representing the form |
| for editing the object. This lets you refer to form fields easily in the |
| template system. |
| |
| For example, if ``model`` has two fields, ``name`` and ``address``:: |
| |
| <form action="" method="post"> |
| <p><label for="id_name">Name:</label> {{ form.name }}</p> |
| <p><label for="id_address">Address:</label> {{ form.address }}</p> |
| </form> |
| |
| See the `manipulator and formfield documentation`_ for more information |
| about using ``FormWrapper`` objects in templates. |
| |
| .. _authentication system: ../authentication/ |
| .. _manipulator and formfield documentation: ../forms/ |
| |
| ``django.views.generic.create_update.update_object`` |
| ---------------------------------------------------- |
| |
| **Description:** |
| |
| A page that displays a form for editing an existing object, redisplaying the |
| form with validation errors (if there are any) and saving changes to the |
| object. This uses the automatic manipulators that come with Django models. |
| |
| **Required arguments:** |
| |
| * ``model``: The Django model class of the object that the form will |
| create. |
| |
| * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. |
| |
| If you provide ``object_id``, it should be the value of the primary-key |
| field for the object being displayed on this page. |
| |
| Otherwise, ``slug`` should be the slug of the given object, and |
| ``slug_field`` should be the name of the slug field in the ``QuerySet``'s |
| model. |
| |
| **Optional arguments:** |
| |
| * ``post_save_redirect``: A URL to which the view will redirect after |
| saving the object. By default, it's ``object.get_absolute_url()``. |
| |
| ``post_save_redirect`` may contain dictionary string formatting, which |
| will be interpolated against the object's field attributes. For example, |
| you could use ``post_save_redirect="/polls/%(slug)s/"``. |
| |
| * ``login_required``: A boolean that designates whether a user must be |
| logged in, in order to see the page and save changes. This hooks into the |
| Django `authentication system`_. By default, this is ``False``. |
| |
| If this is ``True``, and a non-logged-in user attempts to visit this page |
| or save the form, Django will redirect the request to ``/accounts/login/``. |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_form.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``form``: A ``django.oldforms.FormWrapper`` instance representing the form |
| for editing the object. This lets you refer to form fields easily in the |
| template system. |
| |
| For example, if ``model`` has two fields, ``name`` and ``address``:: |
| |
| <form action="" method="post"> |
| <p><label for="id_name">Name:</label> {{ form.name }}</p> |
| <p><label for="id_address">Address:</label> {{ form.address }}</p> |
| </form> |
| |
| See the `manipulator and formfield documentation`_ for more information |
| about using ``FormWrapper`` objects in templates. |
| |
| * ``object``: The original object being edited. This variable's name |
| depends on the ``template_object_name`` parameter, which is ``'object'`` |
| by default. If ``template_object_name`` is ``'foo'``, this variable's |
| name will be ``foo``. |
| |
| ``django.views.generic.create_update.delete_object`` |
| ---------------------------------------------------- |
| |
| **Description:** |
| |
| A view that displays a confirmation page and deletes an existing object. The |
| given object will only be deleted if the request method is ``POST``. If this |
| view is fetched via ``GET``, it will display a confirmation page that should |
| contain a form that POSTs to the same URL. |
| |
| **Required arguments:** |
| |
| * ``model``: The Django model class of the object that the form will |
| create. |
| |
| * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. |
| |
| If you provide ``object_id``, it should be the value of the primary-key |
| field for the object being displayed on this page. |
| |
| Otherwise, ``slug`` should be the slug of the given object, and |
| ``slug_field`` should be the name of the slug field in the ``QuerySet``'s |
| model. |
| |
| * ``post_delete_redirect``: A URL to which the view will redirect after |
| deleting the object. |
| |
| **Optional arguments:** |
| |
| * ``login_required``: A boolean that designates whether a user must be |
| logged in, in order to see the page and save changes. This hooks into the |
| Django `authentication system`_. By default, this is ``False``. |
| |
| If this is ``True``, and a non-logged-in user attempts to visit this page |
| or save the form, Django will redirect the request to ``/accounts/login/``. |
| |
| * ``template_name``: The full name of a template to use in rendering the |
| page. This lets you override the default template name (see below). |
| |
| * ``template_loader``: The template loader to use when loading the |
| template. By default, it's ``django.template.loader``. |
| |
| * ``extra_context``: A dictionary of values to add to the template |
| context. By default, this is an empty dictionary. If a value in the |
| dictionary is callable, the generic view will call it |
| just before rendering the template. |
| |
| * ``context_processors``: A list of template-context processors to apply to |
| the view's template. See the `RequestContext docs`_. |
| |
| * ``template_object_name``: Designates the name of the template variable |
| to use in the template context. By default, this is ``'object'``. |
| |
| **Template name:** |
| |
| If ``template_name`` isn't specified, this view will use the template |
| ``<app_label>/<model_name>_confirm_delete.html`` by default. |
| |
| **Template context:** |
| |
| In addition to ``extra_context``, the template's context will be: |
| |
| * ``object``: The original object that's about to be deleted. This |
| variable's name depends on the ``template_object_name`` parameter, which |
| is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, |
| this variable's name will be ``foo``. |