Ticket #1065: fragment_caching_docs.diff

docs/cache.txt

@@ -277 +277 @@
 above example, the result of the ``slashdot_this()`` view will be cached for 15
 minutes.
 
+Fragment caching
+================
+
+If you're after even more control, you can also easily cache template fragments
+using the ``cache`` template tag. To give your template access to this tag, put
+``{% load fragment_caching %}`` near the top of your template.
+
+The ``{% cache %}`` template tag caches the contents of the block for a given
+amount of time and takes at least two arguments. The first argument is the
+cache timeout, in seconds. The second argument is the name to give the cache
+fragment. For example::
+
+    {% load fragment_caching %}
+    {% 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 fragment_caching %}
+    {% 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
 =======================