  
  Another common type of template tag is the type that displays some data by
  rendering *another* template. For example, Django's admin interface uses custom
  template tags to display the buttons along the bottom of the "add/change" form
  pages. Those buttons always look the same, but the link targets change depending
  on the object being edited -- so they're a perfect case for using a small
  template that is filled with details from the current object. (In the admin's
  case, this is the ``submit_row`` tag.)
  
  These sorts of tags are called "inclusion tags".
  
  Writing inclusion tags is probably best demonstrated by example. Let's write a
  tag that outputs a list of choices for a given ``Poll`` object, such as was
 
</s> remove Shortcut for simple tags
~~~~~~~~~~~~~~~~~~~~~~~~
 </s> add Simple tags
~~~~~~~~~~~ </s> remove information on the node itself. For example, Django provides a builtin ``cycle``
template tag that cycles among a list of given strings each time it's rendered::
 </s> add information on the node itself. For example, Django provides a builtin
``cycle`` template tag that cycles among a list of given strings each time it's
rendered:

.. code-block:: html+django </s> remove .. _howto-custom-template-tags-assignment-tags:

Assignment tags
~~~~~~~~~~~~~~~

.. versionadded:: 1.4

Another common type of template tag is the type that fetches some data and
stores it in a context variable. To ease the creation of this type of tags,
Django provides a helper function, ``assignment_tag``. This function works
the same way as :ref:`simple_tag<howto-custom-template-tags-simple-tags>`,
except that it stores the tag's result in a specified context variable instead
of directly outputting it.

Our earlier ``current_time`` function could thus be written like this:

.. code-block:: python

    def get_current_time(format_string):
        return datetime.datetime.now().strftime(format_string)

    register.assignment_tag(get_current_time)

The decorator syntax also works:

.. code-block:: python

    @register.assignment_tag
    def get_current_time(format_string):
        ...

You may then store the result in a template variable using the ``as`` argument
followed by the variable name, and output it yourself where you see fit:

.. code-block:: html+django

    {% get_current_time "%Y-%m-%d %I:%M %p" as the_time %}
    <p>The time is {{ the_time }}.</p>

If your template tag needs to access the current context, you can use the
``takes_context`` argument when registering your tag:

.. code-block:: python

    # The first argument *must* be called "context" here.
    def get_current_time(context, format_string):
        timezone = context['timezone']
        return your_get_current_time_method(timezone, format_string)

    register.assignment_tag(takes_context=True)(get_current_time)

Or, using decorator syntax:

.. code-block:: python

    @register.assignment_tag(takes_context=True)
    def get_current_time(context, format_string):
        timezone = context['timezone']
        return your_get_current_time_method(timezone, format_string)

For more information on how the ``takes_context`` option works, see the section
on :ref:`inclusion tags<howto-custom-template-tags-inclusion-tags>`.

``assignment_tag`` functions may accept any number of positional or keyword
arguments. For example:

.. code-block:: python

    @register.assignment_tag
    def my_tag(a, b, *args, **kwargs):
        warning = kwargs['warning']
        profile = kwargs['profile']
        ...
        return ...

Then in the template any number of arguments, separated by spaces, may be
passed to the template tag. Like in Python, the values for keyword arguments
are set using the equal sign ("``=``") and must be provided after the positional
arguments. For example:

.. code-block:: html+django

    {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile as the_result %}

 </s> add  </s> remove in a file called ``results.html`` in a directory that's searched by the template
loader, we'd register the tag like this::
 </s> add in a file called ``results.html`` in a directory that's searched by the
template loader, we'd register the tag like this:

.. code-block:: python </s> remove back to the main page. Here's what the Python function would look like::
 </s> add back to the main page. Here's what the Python function would look like:

.. code-block:: python
pages. Those buttons always look the same, but the link targets change
depending on the object being edited -- so they're a perfect case for using a
small template that is filled with details from the current object. (In the
admin's case, this is the ``submit_row`` tag.)
  
  Another common type of template tag is the type that displays some data by
  rendering *another* template. For example, Django's admin interface uses custom
  template tags to display the buttons along the bottom of the "add/change" form
pages. Those buttons always look the same, but the link targets change
depending on the object being edited -- so they're a perfect case for using a
small template that is filled with details from the current object. (In the
admin's case, this is the ``submit_row`` tag.)
pages. Those buttons always look the same, but the link targets change
depending on the object being edited -- so they're a perfect case for using a
small template that is filled with details from the current object. (In the
admin's case, this is the ``submit_row`` tag.)
pages. Those buttons always look the same, but the link targets change
depending on the object being edited -- so they're a perfect case for using a
small template that is filled with details from the current object. (In the
admin's case, this is the ``submit_row`` tag.)
pages. Those buttons always look the same, but the link targets change
depending on the object being edited -- so they're a perfect case for using a
small template that is filled with details from the current object. (In the
admin's case, this is the ``submit_row`` tag.)
  
  These sorts of tags are called "inclusion tags".
  
  Writing inclusion tags is probably best demonstrated by example. Let's write a
  tag that outputs a list of choices for a given ``Poll`` object, such as was
keep keep keep keep replace replace replace replace keep keep keep keep keep
 Brushed up the custom template tag 'howto' guide by moving the assignment_tag doc to a more appropriate place (i.e. under the "Setting a variable in the context" section), adding cross references, fixing a few minor inaccuracies and doing a little PEP8 cleanup.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16909 bcc190cf-cafb-0310-a4f2-bffc1f526a37 
docs/howto/custom-template-tags.txt