[soc2009/model-validation] Merget to trunk at r11229

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/model-validation@11233 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/ref/contrib/admin/index.txt

@@ -704,6 +704,8 @@ objects. Templates can override or extend base admin templates as described in
 If you don't specify this attribute, a default template shipped with Django
 that provides the standard appearance is used.
 
+.. _model-admin-methods:
+
 ``ModelAdmin`` methods
 ----------------------
 
@@ -760,12 +762,19 @@ documented in :ref:`topics-http-urls`::
     anything, so you'll usually want to prepend your custom URLs to the built-in
     ones.
 
-Note, however, that the ``self.my_view`` function registered above will *not*
-have any permission check done; it'll be accessible to the general public. Since
-this is usually not what you want, Django provides a convience wrapper to check
-permissions. This wrapper is :meth:`AdminSite.admin_view` (i.e.
-``self.admin_site.admin_view`` inside a ``ModelAdmin`` instance); use it like
-so::
+However, the ``self.my_view`` function registered above suffers from two
+problems:
+
+  * It will *not* perform and permission checks, so it will be accessible to
+    the general public.
+  * It will *not* provide any header details to prevent caching. This means if
+    the page retrieves data from the database, and caching middleware is
+    active, the page could show outdated information.
+
+Since this is usually not what you want, Django provides a convenience wrapper
+to check permissions and mark the view as non-cacheable. This wrapper is
+:meth:`AdminSite.admin_view` (i.e.  ``self.admin_site.admin_view`` inside a
+``ModelAdmin`` instance); use it like so:
 
     class MyModelAdmin(admin.ModelAdmin):
         def get_urls(self):
@@ -779,7 +788,14 @@ Notice the wrapped view in the fifth line above::
 
     (r'^my_view/$', self.admin_site.admin_view(self.my_view))
 
-This wrapping will protect ``self.my_view`` from unauthorized access.
+This wrapping will protect ``self.my_view`` from unauthorized access and will
+apply the ``django.views.decorators.cache.never_cache`` decorator to make sure
+it is not cached if the cache middleware is active.
+
+If the page is cacheable, but you still want the permission check to be performed,
+you can pass a ``cacheable=True`` argument to :meth:`AdminSite.admin_view`::
+
+    (r'^my_view/$', self.admin_site.admin_view(self.my_view, cacheable=True))
 
 .. method:: ModelAdmin.formfield_for_foreignkey(self, db_field, request, **kwargs)
 
@@ -792,7 +808,7 @@ return a subset of objects for this foreign key field based on the user::
     class MyModelAdmin(admin.ModelAdmin):
         def formfield_for_foreignkey(self, db_field, request, **kwargs):
             if db_field.name == "car":
-                kwargs["queryset"] = Car.object.filter(owner=request.user)
+                kwargs["queryset"] = Car.objects.filter(owner=request.user)
                 return db_field.formfield(**kwargs)
             return super(MyModelAdmin, self).formfield_for_foreignkey(db_field, request, **kwargs)
 
@@ -847,7 +863,7 @@ provided some extra mapping data that would not otherwise be available::
                 'osm_data': self.get_osm_info(),
             }
             return super(MyModelAdmin, self).change_view(request, object_id,
-                extra_context=my_context))
+                extra_context=my_context)
 
 ``ModelAdmin`` media definitions
 --------------------------------