Для каждого встречающегося тега шаблонный парсер вызывает функцию, передавая ей содержимое тега и ссылку на себя. Эта функция отвечает за возвращение экземпляра класса Node, построенного по переданной информации.

Например, давайте реализуем шаблонный тег {% current_time %}, который отображает текущую дату и время, отформатированную в соответствии с параметром тега, используя синтаксис strftime (см. http://docs.python.org/library/datetime.html#datetime.date.strftime). Неплохо будет сначала продумать синтаксис тега. В нашем случае, пусть будет так:

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

Парсер должен выделять параметр и создавать объект Node для этой функции:

from django import template

def do_current_time(parser, token):
    try:
        # метод split_contents() знает, что не надо разделять строки в кавычках
        tag_name, format_string = token.split_contents()
    except ValueError:
        # камрады с мест сообщают, что в следующей строке должно использоваться
        # token.split_contents()[0], требуется дополнительное подтверждение.
        msg = '%r tag requires a single argument' % token.contents[0]
        raise template.TemplateSyntaxError(msg)
    return CurrentTimeNode(format_string[1:-1])

Разберём этот код:

На втором шаге следует определить подкласс Node, который должен иметь метод render(). Продолжая наш пример, нам надо определить CurrentTimeNode:

import datetime

class CurrentTimeNode(template.Node):

    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        now = datetime.datetime.now()
        return now.strftime(self.format_string)

Эти два метода (__init__ и render) соответствую двум шагам обработки (компиляция и рендеринг). Таким образом, метод инициализации применяется только для сохранения строки формата для дальнейшего использования, а метод render() делает основную работу.

Аналогично шаблонным фильтрам, эти методы должны тихо игнорировать ошибки. Единственный момент, когда шаблонные теги могут вызвать исключение — момент компиляции.

В конце, следует зарегистрировать тег в экземпляре класса Library. Регистрация собственных тегов очень похожа на регистрацию своих фильтров. Создайте экземпляр template.Library и вызовите метод tag(). Например:

register.tag('current_time', do_current_time)

Метод tag() принимает два аргумента:

Как и при регистрации фильтра, также возможно использование декоратора (необходим Python версии 2.4+):

@register.tag(name="current_time")
def do_current_time(parser, token):
    # ...

@register.tag
def shout(parser, token):
    # ...

Если вы не укажете аргумент name, как было во втором примере, Django будет использовать имя функции в качестве имени тега.

Пример из предыдущей секции просто возвращал значение. Часто бывает полезным устанавливать шаблонную переменную вместо возвращения значения. Для этого авторы шаблонов могут использовать переменные, устанавливаемые их шаблонными тегами.

Для того, чтобы установить переменную в контексте, используйте словарное назначение для контекстного объекта в методе render(). Ниже показана обновлённая версия класса CurrentTimeNode:

class CurrentTimeNode2(template.Node):

    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        now = datetime.datetime.now()
        context['current_time'] = now.strftime(self.format_string)
        return ''

Следует отметить, что метод render() возвращает пустую строку. Данный метод должен всегда возвращать строку. Раз шаблонный тег устанавливает переменную, то метод должен возвращать пустую строку.

Вот так теперь это можно использовать:

{% current_time2 "%Y-%M-%d %I:%M %p" %}
<p>The time is {{ current_time }}.</p>

Но с классом CurrentTimeNode2 есть одна проблема — имя переменной current_time жёстко определено. Это означает, что вам придётся проверять ваши шаблоны, что они не используют {{ current_time }}, так как {% current_time2 %} слепо перепишет значение этой переменной.

Более явное решение — позволить шаблонному тегу указывать имя устанавливаемой переменной, например так:

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

Для этого потребуется провести рефакторинг функции компиляции и класса Node:

import re

class CurrentTimeNode3(template.Node):

    def __init__(self, format_string, var_name):
        self.format_string = format_string
        self.var_name = var_name

    def render(self, context):
        now = datetime.datetime.now()
        context[self.var_name] = now.strftime(self.format_string)
        return ''

def do_current_time(parser, token):
    # This version uses a regular expression to parse tag contents.
    try:
        # Splitting by None == splitting by spaces.
        tag_name, arg = token.contents.split(None, 1)
    except ValueError:
        msg = '%r tag requires arguments' % token.contents[0]
        raise template.TemplateSyntaxError(msg)

    m = re.search(r'(.*?) as (\w+)', arg)
    if m:
        fmt, var_name = m.groups()
    else:
        msg = '%r tag had invalid arguments' % tag_name
        raise template.TemplateSyntaxError(msg)

    if not (fmt[0] == fmt[-1] and fmt[0] in ('"', "'")):
        msg = "%r tag's argument should be in quotes" % tag_name
        raise template.TemplateSyntaxError(msg)

    return CurrentTimeNode3(fmt[1:-1], var_name)

Теперь do_current_time() передаёт строку формата и имя переменной в CurrentTimeNode3.

Шаблонные теги могут работать как блоки, содержащие другие теги (типа {% if %}, {% for %} и так далее). Для создания такого шаблонного тега следует использовать parser.parse() в вашей функции компиляции.

Ниже показана реализация стандартного тега {% comment %}:

def do_comment(parser, token):
    nodelist = parser.parse(('endcomment',))
    parser.delete_first_token()
    return CommentNode()

class CommentNode(template.Node):
    def render(self, context):
        return ''

Метод parse() получает кортеж имён блочных тегов, до которых он должен вести обработку. Метод возвращает экземпляр django.template.NodeList, который является списком всех объектов класса Node, которые парсер обнаружил на обработки любого тега из переданного кортежа.

Таким образом, в предыдущем примере nodelist является списком всех узлов между {% comment %} и {% endcomment %}.

После вызова метода parse() парсер ещё не «использовал» тег {% endcomment %}, поэтому необходимо явно вызвать метод delete_first_token(), чтобы не обрабатывать этот тег дважды.

Затем CommentNode.render() просто возвращает пустую строку. Всё, что находилось между тегами {% comment %} и {% endcomment %} игнорируется.

В предыдущем примере, метод do_comment() отбрасывал всё, что находилось между тегами {% comment %} и {% endcomment %}. Можно так не делать.

Например, здесь представлен шаблонный тег {% upper %}, который преобразует все буквы в заглавные между собой и тегом {% endupper %}:

{% upper %}
    This will appear in uppercase, {{ your_name }}.
{% endupper %}

Как и в предыдущем примере мы будет использовать parser.parse(). В этот раз мы передадим nodelist в Node:

@register.tag
def do_upper(parser, token):
    nodelist = parser.parse(('endupper',))
    parser.delete_first_token()
    return UpperNode(nodelist)

class UpperNode(template.Node):

    def __init__(self, nodelist):
        self.nodelist = nodelist

    def render(self, context):
        output = self.nodelist.render(context)
        return output.upper()

Единственная новая концепция в этом коде это использование self.nodelist.render(context) в UpperNode.render(). Он просто вызывает метод render() у каждого экземпляра класса Node в списке.

Примеры более сложной обработки можно подсмотреть в исходном коде {% if %}, {% for %}, {% ifequal %} и {% ifchanged %}. Их код можно найти в django/template/defaulttags.py.