Fixed #1065 -- Added a "cache" template tag. Thanks, Ian Maurer and, particularly, Nick Lane.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6580 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/cache.txt b/docs/cache.txt
index 20c59bfe97..3b53260c91 100644
--- a/docs/cache.txt
+++ b/docs/cache.txt
@@ -288,6 +288,36 @@ Or, using Python 2.4's decorator syntax::
 above example, the result of the ``slashdot_this()`` view will be cached for 15
 minutes.
 
+Template fragment caching
+=========================
+
+If you're after even more control, you can also cache template fragments using
+the ``cache`` template tag. To give your template access to this tag, put ``{%
+load cache %}`` near the top of your template.
+
+The ``{% cache %}`` template tag caches the contents of the block for a given
+amount of time. It takes at least two arguments: the cache timeout, in
+seconds, and the name to give the cache fragment. For example::
+
+    {% load cache %}
+    {% cache 500 sidebar %}
+        .. sidebar ..
+    {% endcache %}
+
+Sometimes you might want to cache multiple copies of a fragment depending on
+some dynamic data that appears inside the fragment. For example you may want a
+separate cached copy of the sidebar used in the previous example for every user
+of your site. This can be easily achieved by passing additional arguments to
+the ``{% cache %}`` template tag to uniquely identify the cache fragment::
+
+    {% load cache %}
+    {% cache 500 sidebar request.user.username %}
+        .. sidebar for logged in user ..
+    {% endcache %}
+
+If you need more than one argument to identify the fragment that's fine, simply
+pass as many arguments to ``{% cache %}`` as you need!
+
 The low-level cache API
 =======================