Ticket #2016: 0003-Adds-documentation-for-object_tag.diff

docs/howto/custom-template-tags.txt

@@ -783 +783 @@
 The difference here is that ``do_current_time()`` grabs the format string and
 the variable name, passing both to ``CurrentTimeNode3``.
 
+Shortcut for loading objects into template variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded: 1.2
+
+If you only need to retrieve and store an object in a template variable, it
+might seem cumbersome to write both a renderer and a compilation function
+for such an easy task.
+
+That is why Django provides yet another shortcut -- ``object_tag`` -- which
+makes it easy to write tags that loads objects into template variables.
+
+Its use is very similar to ``simple_tag`` in the way that it takes care of
+all the argument parsing for you, and only requires a single return value --
+the object you'd like to insert into the template variable.
+
+Example::
+
+    def get_latest_polls(max_num):
+        return Poll.objects.order_by('-pub_date')[:max_num]
+
+    register.object_tag(get_latest_polls)
+
+Or if you wish to use the Python 2.4 decorator syntax::
+
+    @register.object_tag
+    def get_latest_polls(max_num):
+        return Poll.objects.order_by('-pub_date')[:max_num]
+
+This tag returns the latest ``Poll``-objects, sorted by descending order, and
+limited by the value of ``max_num``. Its use in a template would look like
+this:
+
+.. code-block:: html+django
+
+    {% get_latest_polls 5 as latest_polls %}
+
+Which would retrieve the 5 latest polls and store them inside a template
+variable named "latest_polls".
+
+Note that the following syntax is *mandatory* for all object_tag's:
+
+.. code-block:: html+django
+
+    {% tag_name [args] as <var_name> %}
+
+Where ``args`` is the arguments for the templatetag ``tag_name``, and
+``var_name`` is the name of the template variable in which the returned object
+should be stored.
+
 Parsing until another block tag
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~