                 return '%sxx' % value
             add_xx.is_safe = True
  
         When this filter is used in a template where auto-escaping is enabled,
         Django will escape the output whenever the input is not already marked as
         "safe".
  
         By default, ``is_safe`` defaults to ``False``, and you can omit it from
         any filters where it isn't required.
  
         Be careful when deciding if your filter really does leave safe strings
 
</s> remove        your filter function and set it to ``True``, like so::
 </s> add        your filter function and set it to ``True``, like so:

       .. code-block:: python </s> remove        For example, suppose you have a filter that adds the string ``xx`` to the
       end of any input. Since this introduces no dangerous HTML characters to
       the result (aside from any that were already present), you should mark
       your filter with ``is_safe``::
 </s> add        For example, suppose you have a filter that adds the string ``xx`` to
       the end of any input. Since this introduces no dangerous HTML characters
       to the result (aside from any that were already present), you should
       mark your filter with ``is_safe``:

       .. code-block:: python </s> remove The ``takes_context`` parameter defaults to ``False``. When it's set to *True*,
the tag is passed the context object, as in this example. That's the only
difference between this case and the previous ``inclusion_tag`` example.
 </s> add The ``takes_context`` parameter defaults to ``False``. When it's set to
``True``, the tag is passed the context object, as in this example. That's the
only difference between this case and the previous ``inclusion_tag`` example. </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 convert an object to its string value before being passed to your function::
 </s> add convert an object to its string value before being passed to your function:

.. code-block:: python
       Django will escape the output whenever the input is not already marked
       as "safe".
                 return '%sxx' % value
             add_xx.is_safe = True
  
         When this filter is used in a template where auto-escaping is enabled,
       Django will escape the output whenever the input is not already marked
       as "safe".
       Django will escape the output whenever the input is not already marked
       as "safe".
  
         By default, ``is_safe`` defaults to ``False``, and you can omit it from
         any filters where it isn't required.
  
         Be careful when deciding if your filter really does leave safe strings
keep keep keep keep 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