From 690f9ad8f091d5f5da97c12f8871aa7e1ade8307 Mon Sep 17 00:00:00 2001 From: Malcolm Tredinnick Date: Sun, 21 May 2006 12:44:58 +0000 Subject: [PATCH] Improved the advice on using QuerySets in extra_context based on feedback from Luke Plant. git-svn-id: http://code.djangoproject.com/svn/django/trunk@2949 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/generic_views.txt | 77 ++++++++++++------------------------------ 1 file changed, 21 insertions(+), 56 deletions(-) diff --git a/docs/generic_views.txt b/docs/generic_views.txt index cca990e4f6..5b978af1de 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -62,6 +62,15 @@ 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: http://www.djangoproject.com/documentation/db_api/ "Simple" generic views @@ -161,13 +170,9 @@ a date in the *future* are not included. 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 + context. By default, this is an empty dictionary. dictionary is callable, the generic view will call it - just before rendering the template. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + 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, @@ -232,11 +237,7 @@ with a date in the *future* are not displayed. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + 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, @@ -298,11 +299,7 @@ date in the *future* are not displayed. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + 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, @@ -375,11 +372,7 @@ in the *future* are not displayed. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + 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, @@ -455,11 +448,7 @@ a 404 error, regardless of whether any objects exist for future days. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + 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, @@ -566,11 +555,7 @@ A page representing an individual object. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + just before rendering the template. * ``context_processors``: A list of template-context processors to apply to the view's template. See the `RequestContext docs`_. @@ -627,11 +612,7 @@ A page representing a list of objects. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + 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, @@ -728,11 +709,7 @@ A page representing an individual object. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + just before rendering the template. * ``context_processors``: A list of template-context processors to apply to the view's template. See the `RequestContext docs`_. @@ -799,11 +776,7 @@ automatic manipulators that come with Django models. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + just before rendering the template. * ``context_processors``: A list of template-context processors to apply to the view's template. See the `RequestContext docs`_. @@ -882,11 +855,7 @@ object. This uses the automatic manipulators that come with Django models. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + just before rendering the template. * ``context_processors``: A list of template-context processors to apply to the view's template. See the `RequestContext docs`_. @@ -967,11 +936,7 @@ contain a form that POSTs to the same URL. * ``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. If it is not callable, it will be - evaluated once, at import time. Note that QuerySets are not callable, so - if you want to pass in a QuerySet in ``extra_context`` and have it - evaluated at render time, you need to wrap it in a function (that - returns the QuerySet). + just before rendering the template. * ``context_processors``: A list of template-context processors to apply to the view's template. See the `RequestContext docs`_.