Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Brushed up the custom template tag 'howto' guide by moving the assign…

…ment_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
  • Loading branch information...
commit aaf8a31e5d86f9457672511e1beb915eb83d3c3c 1 parent 8137027
@jphalip jphalip authored
Showing with 254 additions and 178 deletions.
  1. +254 −178 docs/howto/custom-template-tags.txt
View
432 docs/howto/custom-template-tags.txt
@@ -2,16 +2,13 @@
Custom template tags and filters
================================
-Introduction
-============
-
Django's template system comes with a wide variety of :doc:`built-in
tags and filters </ref/templates/builtins>` designed to address the
presentation logic needs of your application. Nevertheless, you may
find yourself needing functionality that is not covered by the core
set of template primitives. You can extend the template engine by
defining custom tags and filters using Python, and then make them
-available to your templates using the ``{% load %}`` tag.
+available to your templates using the :ttag:`{% load %}<load>` tag.
Code layout
-----------
@@ -47,18 +44,20 @@ And in your template you would use the following:
{% load poll_extras %}
The app that contains the custom tags must be in :setting:`INSTALLED_APPS` in
-order for the ``{% load %}`` tag to work. This is a security feature: It allows
-you to host Python code for many template libraries on a single host machine
-without enabling access to all of them for every Django installation.
+order for the :ttag:`{% load %}<load>` tag to work. This is a security feature:
+It allows you to host Python code for many template libraries on a single host
+machine without enabling access to all of them for every Django installation.
There's no limit on how many modules you put in the ``templatetags`` package.
-Just keep in mind that a ``{% load %}`` statement will load tags/filters for
-the given Python module name, not the name of the app.
+Just keep in mind that a :ttag:`{% load %}<load>` statement will load
+tags/filters for the given Python module name, not the name of the app.
To be a valid tag library, the module must contain a module-level variable
named ``register`` that is a ``template.Library`` instance, in which all the
tags and filters are registered. So, near the top of your module, put the
-following::
+following:
+
+.. code-block:: python
from django import template
@@ -89,10 +88,12 @@ Filter functions should always return something. They shouldn't raise
exceptions. They should fail silently. In case of error, they should return
either the original input or an empty string -- whichever makes more sense.
-Here's an example filter definition::
+Here's an example filter definition:
+
+.. code-block:: python
def cut(value, arg):
- "Removes all values of arg from the given string"
+ """Removes all values of arg from the given string"""
return value.replace(arg, '')
And here's an example of how that filter would be used:
@@ -102,17 +103,21 @@ And here's an example of how that filter would be used:
{{ somevariable|cut:"0" }}
Most filters don't take arguments. In this case, just leave the argument out of
-your function. Example::
+your function. Example:
+
+.. code-block:: python
def lower(value): # Only one argument.
- "Converts a string into all lowercase"
+ """Converts a string into all lowercase"""
return value.lower()
Registering custom filters
~~~~~~~~~~~~~~~~~~~~~~~~~~
Once you've written your filter definition, you need to register it with
-your ``Library`` instance, to make it available to Django's template language::
+your ``Library`` instance, to make it available to Django's template language:
+
+.. code-block:: python
register.filter('cut', cut)
register.filter('lower', lower)
@@ -123,7 +128,9 @@ The ``Library.filter()`` method takes two arguments:
2. The compilation function -- a Python function (not the name of the
function as a string).
-You can use ``register.filter()`` as a decorator instead::
+You can use ``register.filter()`` as a decorator instead:
+
+.. code-block:: python
@register.filter(name='cut')
def cut(value, arg):
@@ -141,7 +148,9 @@ Template filters that expect strings
If you're writing a template filter that only expects a string as the first
argument, you should use the decorator ``stringfilter``. This will
-convert an object to its string value before being passed to your function::
+convert an object to its string value before being passed to your function:
+
+.. code-block:: python
from django import template
from django.template.defaultfilters import stringfilter
@@ -175,14 +184,17 @@ passed around inside the template code:
Internally, these strings are of type ``SafeString`` or ``SafeUnicode``.
They share a common base class of ``SafeData``, so you can test
- for them using code like::
+ for them using code like:
+
+ .. code-block:: python
if isinstance(value, SafeData):
# Do something with the "safe" string.
+ ...
* **Strings marked as "needing escaping"** are *always* escaped on
- output, regardless of whether they are in an ``autoescape`` block or not.
- These strings are only escaped once, however, even if auto-escaping
+ output, regardless of whether they are in an :ttag:`autoescape` block or
+ not. These strings are only escaped once, however, even if auto-escaping
applies.
Internally, these strings are of type ``EscapeString`` or
@@ -195,7 +207,9 @@ Template filter code falls into one of two situations:
``'``, ``"`` or ``&``) into the result that were not already present. In
this case, you can let Django take care of all the auto-escaping
handling for you. All you need to do is put the ``is_safe`` attribute on
- your filter function and set it to ``True``, like so::
+ your filter function and set it to ``True``, like so:
+
+ .. code-block:: python
@register.filter
def myfilter(value):
@@ -215,10 +229,12 @@ Template filter code falls into one of two situations:
them all, which would be very difficult, Django repairs the damage after
the filter has completed.
- 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``::
+ 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
@register.filter
def add_xx(value):
@@ -226,8 +242,8 @@ Template filter code falls into one of two situations:
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.
@@ -271,7 +287,9 @@ Template filter code falls into one of two situations:
auto-escaping is in effect and ``False`` otherwise.
For example, let's write a filter that emphasizes the first character of
- a string::
+ a string:
+
+ .. code-block:: python
from django.utils.html import conditional_escape
from django.utils.safestring import mark_safe
@@ -346,7 +364,9 @@ anything else. In our case, let's say the tag should be used like this:
<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>
The parser for this function should grab the parameter and create a ``Node``
-object::
+object:
+
+.. code-block:: python
from django import template
def do_current_time(parser, token):
@@ -399,7 +419,9 @@ Writing the renderer
The second step in writing custom tags is to define a ``Node`` subclass that
has a ``render()`` method.
-Continuing the above example, we need to define ``CurrentTimeNode``::
+Continuing the above example, we need to define ``CurrentTimeNode``:
+
+.. code-block:: python
from django import template
import datetime
@@ -441,7 +463,9 @@ as such.
Also, if your template tag creates a new context for performing some
sub-rendering, set the auto-escape attribute to the current context's value.
The ``__init__`` method for the ``Context`` class takes a parameter called
-``autoescape`` that you can use for this purpose. For example::
+``autoescape`` that you can use for this purpose. For example:
+
+.. code-block:: python
def render(self, context):
# ...
@@ -449,7 +473,9 @@ The ``__init__`` method for the ``Context`` class takes a parameter called
# ... Do something with new_context ...
This is not a very common situation, but it's useful if you're rendering a
-template yourself. For example::
+template yourself. For example:
+
+.. code-block:: python
def render(self, context):
t = template.loader.get_template('small_fragment.html')
@@ -458,7 +484,7 @@ template yourself. For example::
If we had neglected to pass in the current ``context.autoescape`` value to our
new ``Context`` in this example, the results would have *always* been
automatically escaped, which may not be the desired behavior if the template
-tag is used inside a ``{% autoescape off %}`` block.
+tag is used inside a :ttag:`{% autoescape off %}<autoescape>` block.
.. _template_tag_thread_safety:
@@ -474,8 +500,11 @@ requests. Therefore, it's important to make sure your template tags are thread
safe.
To make sure your template tags are thread safe, you should never store state
-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::
+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
{% for o in some_list %}
<tr class="{% cycle 'row1' 'row2' %}>
@@ -483,7 +512,9 @@ template tag that cycles among a list of given strings each time it's rendered::
</tr>
{% endfor %}
-A naive implementation of ``CycleNode`` might look something like this::
+A naive implementation of ``CycleNode`` might look something like this:
+
+.. code-block:: python
class CycleNode(Node):
def __init__(self, cyclevars):
@@ -509,10 +540,12 @@ obviously not what we want!
To address this problem, Django provides a ``render_context`` that's associated
with the ``context`` of the template that is currently being rendered. The
-``render_context`` behaves like a Python dictionary, and should be used to store
-``Node`` state between invocations of the ``render`` method.
+``render_context`` behaves like a Python dictionary, and should be used to
+store ``Node`` state between invocations of the ``render`` method.
-Let's refactor our ``CycleNode`` implementation to use the ``render_context``::
+Let's refactor our ``CycleNode`` implementation to use the ``render_context``:
+
+.. code-block:: python
class CycleNode(Node):
def __init__(self, cyclevars):
@@ -534,16 +567,18 @@ like the current iteration of the ``CycleNode``, should be stored in the
.. note::
Notice how we used ``self`` to scope the ``CycleNode`` specific information
within the ``render_context``. There may be multiple ``CycleNodes`` in a
- given template, so we need to be careful not to clobber another node's state
- information. The easiest way to do this is to always use ``self`` as the key
- into ``render_context``. If you're keeping track of several state variables,
- make ``render_context[self]`` a dictionary.
+ given template, so we need to be careful not to clobber another node's
+ state information. The easiest way to do this is to always use ``self`` as
+ the key into ``render_context``. If you're keeping track of several state
+ variables, make ``render_context[self]`` a dictionary.
Registering the tag
~~~~~~~~~~~~~~~~~~~
Finally, register the tag with your module's ``Library`` instance, as explained
-in "Writing custom template filters" above. Example::
+in "Writing custom template filters" above. Example:
+
+.. code-block:: python
register.tag('current_time', do_current_time)
@@ -554,15 +589,17 @@ The ``tag()`` method takes two arguments:
2. The compilation function -- a Python function (not the name of the
function as a string).
-As with filter registration, it is also possible to use this as a decorator::
+As with filter registration, it is also possible to use this as a decorator:
+
+.. code-block:: python
@register.tag(name="current_time")
def do_current_time(parser, token):
- # ...
+ ...
@register.tag
def shout(parser, token):
- # ...
+ ...
If you leave off the ``name`` argument, as in the second example above, Django
will use the function's name as the tag name.
@@ -576,8 +613,9 @@ string literals. A little more work is required in order to pass dynamic
content (a template variable) to a template tag as an argument.
While the previous examples have formatted the current time into a string and
-returned the string, suppose you wanted to pass in a ``DateTimeField`` from an
-object and have the template tag format that date-time:
+returned the string, suppose you wanted to pass in a
+:class:`~django.db.models.DateTimeField` from an object and have the template
+tag format that date-time:
.. code-block:: html+django
@@ -586,12 +624,15 @@ object and have the template tag format that date-time:
Initially, ``token.split_contents()`` will return three values:
1. The tag name ``format_time``.
- 2. The string "blog_entry.date_updated" (without the surrounding quotes).
- 3. The formatting string "%Y-%m-%d %I:%M %p". The return value from
+ 2. The string ``"blog_entry.date_updated"`` (without the surrounding
+ quotes).
+ 3. The formatting string ``"%Y-%m-%d %I:%M %p"``. The return value from
``split_contents()`` will include the leading and trailing quotes for
string literals like this.
-Now your tag should begin to look like this::
+Now your tag should begin to look like this:
+
+.. code-block:: python
from django import template
def do_format_time(parser, token):
@@ -610,7 +651,9 @@ accomplished by using the ``Variable()`` class in ``django.template``.
To use the ``Variable`` class, simply instantiate it with the name of the
variable to be resolved, and then call ``variable.resolve(context)``. So,
-for example::
+for example:
+
+.. code-block:: python
class FormatTimeNode(template.Node):
def __init__(self, date_to_be_formatted, format_string):
@@ -624,13 +667,13 @@ for example::
except template.VariableDoesNotExist:
return ''
-Variable resolution will throw a ``VariableDoesNotExist`` exception if it cannot
-resolve the string passed to it in the current context of the page.
+Variable resolution will throw a ``VariableDoesNotExist`` exception if it
+cannot resolve the string passed to it in the current context of the page.
.. _howto-custom-template-tags-simple-tags:
-Shortcut for simple tags
-~~~~~~~~~~~~~~~~~~~~~~~~
+Simple tags
+~~~~~~~~~~~
Many template tags take a number of arguments -- strings or template variables
-- and return a string after doing some processing based solely on
@@ -644,20 +687,24 @@ To ease the creation of these types of tags, Django provides a helper function,
arguments, wraps it in a ``render`` function and the other necessary bits
mentioned above and registers it with the template system.
-Our earlier ``current_time`` function could thus be written like this::
+Our earlier ``current_time`` function could thus be written like this:
+
+.. code-block:: python
def current_time(format_string):
return datetime.datetime.now().strftime(format_string)
register.simple_tag(current_time)
-The decorator syntax also works::
+The decorator syntax also works:
+
+.. code-block:: python
@register.simple_tag
def current_time(format_string):
...
-A couple of things to note about the ``simple_tag`` helper function:
+A few things to note about the ``simple_tag`` helper function:
* Checking for the required number of arguments, etc., has already been
done by the time our function is called, so we don't need to do that.
@@ -669,7 +716,9 @@ A couple of things to note about the ``simple_tag`` helper function:
.. versionadded:: 1.3
If your template tag needs to access the current context, you can use the
-``takes_context`` argument when registering your tag::
+``takes_context`` argument when registering your tag:
+
+.. code-block:: python
# The first argument *must* be called "context" here.
def current_time(context, format_string):
@@ -678,7 +727,9 @@ If your template tag needs to access the current context, you can use the
register.simple_tag(takes_context=True)(current_time)
-Or, using decorator syntax::
+Or, using decorator syntax:
+
+.. code-block:: python
@register.simple_tag(takes_context=True)
def current_time(context, format_string):
@@ -690,13 +741,15 @@ on :ref:`inclusion tags<howto-custom-template-tags-inclusion-tags>`.
.. versionadded:: 1.4
-If you need to rename your tag, you can provide a custom name for it::
+If you need to rename your tag, you can provide a custom name for it:
+
+.. code-block:: python
register.simple_tag(lambda x: x - 1, name='minusone')
@register.simple_tag(name='minustwo')
def some_function(value):
- return value - 1
+ return value - 2
.. versionadded:: 1.4
@@ -714,97 +767,13 @@ arguments. For example:
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:
+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 %}
-.. _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 %}
-
.. _howto-custom-template-tags-inclusion-tags:
Inclusion tags
@@ -813,10 +782,10 @@ Inclusion tags
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.)
These sorts of tags are called "inclusion tags".
@@ -841,7 +810,9 @@ created in the :ref:`tutorials <creating-models>`. We'll use the tag like this:
First, define the function that takes the argument and produces a dictionary of
data for the result. The important point here is we only need to return a
dictionary, not anything more complex. This will be used as a template context
-for the template fragment. Example::
+for the template fragment. Example:
+
+.. code-block:: python
def show_results(poll):
choices = poll.choice_set.all()
@@ -861,8 +832,10 @@ designer. Following our example, the template is very simple:
Now, create and register the inclusion tag by calling the ``inclusion_tag()``
method on a ``Library`` object. Following our example, if the above template is
-in a file called ``results.html`` in a directory that's searched by the template
-loader, we'd register the tag like this::
+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
# Here, register is a django.template.Library instance, as before
register.inclusion_tag('results.html')(show_results)
@@ -870,13 +843,17 @@ loader, we'd register the tag like this::
.. versionchanged:: 1.4
Alternatively it is possible to register the inclusion tag using a
- :class:`django.template.Template` instance::
+ :class:`django.template.Template` instance:
+
+ .. code-block:: python
from django.template.loader import get_template
t = get_template('results.html')
register.inclusion_tag(t)(show_results)
-As always, decorator syntax works as well, so we could have written::
+As always, decorator syntax works as well, so we could have written:
+
+.. code-block:: python
@register.inclusion_tag('results.html')
def show_results(poll):
@@ -893,7 +870,9 @@ will have one argument -- the template context as of when the tag was called.
For example, say you're writing an inclusion tag that will always be used in a
context that contains ``home_link`` and ``home_title`` variables that point
-back to the main page. Here's what the Python function would look like::
+back to the main page. Here's what the Python function would look like:
+
+.. code-block:: python
# The first argument *must* be called "context" here.
def jump_link(context):
@@ -924,9 +903,9 @@ without any arguments, like so:
Note that when you're using ``takes_context=True``, there's no need to pass
arguments to the template tag. It automatically gets access to the context.
-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.
+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.
.. versionadded:: 1.4
@@ -944,8 +923,8 @@ arguments. For example:
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:
+are set using the equal sign ("``=``") and must be provided after the
+positional arguments. For example:
.. code-block:: html+django
@@ -961,7 +940,9 @@ template authors can reuse the values that your template tags create.
To set a variable in the context, just use dictionary assignment on the context
object in the ``render()`` method. Here's an updated version of
``CurrentTimeNode`` that sets a template variable ``current_time`` instead of
-outputting it::
+outputting it:
+
+.. code-block:: python
class CurrentTimeNode2(template.Node):
def __init__(self, format_string):
@@ -982,10 +963,10 @@ Here's how you'd use this new version of the tag:
.. admonition:: Variable scope in context
- Any variable set in the context will only be available in the same ``block``
- of the template in which it was assigned. This behavior is intentional;
- it provides a scope for variables so that they don't conflict with
- context in other blocks.
+ Any variable set in the context will only be available in the same
+ ``block`` of the template in which it was assigned. This behavior is
+ intentional; it provides a scope for variables so that they don't conflict
+ with context in other blocks.
But, there's a problem with ``CurrentTimeNode2``: The variable name
``current_time`` is hard-coded. This means you'll need to make sure your
@@ -1000,7 +981,9 @@ like so:
<p>The current time is {{ my_current_time }}.</p>
To do that, you'll need to refactor both the compilation function and ``Node``
-class, like so::
+class, like so:
+
+.. code-block:: python
class CurrentTimeNode3(template.Node):
def __init__(self, format_string, var_name):
@@ -1029,14 +1012,104 @@ class, like so::
The difference here is that ``do_current_time()`` grabs the format string and
the variable name, passing both to ``CurrentTimeNode3``.
+Finally, if you only need to have a simple syntax for your custom
+context-updating template tag, you might want to consider using an
+:ref:`assignment tag <howto-custom-template-tags-assignment-tags>`.
+
+.. _howto-custom-template-tags-assignment-tags:
+
+Assignment tags
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.4
+
+To ease the creation of tags setting a variable in the context, 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 %}
+
Parsing until another block tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Template tags can work in tandem. For instance, the standard ``{% comment %}``
-tag hides everything until ``{% endcomment %}``. To create a template tag such
-as this, use ``parser.parse()`` in your compilation function.
+Template tags can work in tandem. For instance, the standard
+:ttag:`{% comment %}<comment>` tag hides everything until ``{% endcomment %}``.
+To create a template tag such as this, use ``parser.parse()`` in your
+compilation function.
-Here's how the standard ``{% comment %}`` tag is implemented::
+Here's how the standard :ttag:`{% comment %}<comment>` tag is implemented:
+
+.. code-block:: python
def do_comment(parser, token):
nodelist = parser.parse(('endcomment',))
@@ -1081,7 +1154,9 @@ Usage:
{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %}
As in the previous example, we'll use ``parser.parse()``. But this time, we
-pass the resulting ``nodelist`` to the ``Node``::
+pass the resulting ``nodelist`` to the ``Node``:
+
+.. code-block:: python
def do_upper(parser, token):
nodelist = parser.parse(('endupper',))
@@ -1098,6 +1173,7 @@ pass the resulting ``nodelist`` to the ``Node``::
The only new concept here is the ``self.nodelist.render(context)`` in
``UpperNode.render()``.
-For more examples of complex rendering, see the source code for ``{% if %}``,
-``{% for %}``, ``{% ifequal %}`` and ``{% ifchanged %}``. They live in
+For more examples of complex rendering, see the source code for
+:ttag:`{% if %}<if>`, :ttag:`{% for %}<for>`, :ttag:`{% ifequal %}<ifequal>`
+or :ttag:`{% ifchanged %}<ifchanged>`. They live in
``django/template/defaulttags.py``.
Please sign in to comment.
Something went wrong with that request. Please try again.