Django_-_podrobnoe_rukovodstvo

После создания модуля Python вам предстоит написать код, зависящий от того, что именно реализуется: фильтр или тег.

Чтобы считаться корректной библиотекой тегов, модуль должен содержать переменную уровня модуля register, которая является экземпляром класса template.Library. Это структура данных, в которой регистрируются все теги и фильтры. Поэтому в начале модуля поместите такой код:

from django import template

register = template.Library()

Примечание

Ряд хороших примеров тегов и фильтров можно найти в исходном коде Django. Они находятся соответственно в файлах django/template/defaultfilters.py

и django/template/defaulttags.py. Некоторые приложения в django.contrib

также содержат библиотеки шаблонов­.

Переменная register будет использоваться при создании шаблонных­ фильтров и тегов.

Создание собственных шаблонных­ фильтров

Фильтры – это обычные функции Python, принимающие один или два аргумента:

•• Значение переменной (входные данные).

•• Значение аргумента, который может иметь значение по умолчанию или вообще отсутствовать.

Например, в случае {{ var|foo:”bar” }} фильтру foo будет передано содержимое переменной var и аргумент “bar”.

Функция фильтра обязана что-то вернуть. Она не должна возбуждать исключение и не может молчаливо игнорировать ошибки. В случае ошибки функция должна вернуть либо переданные ей входные данные, либо пустую строку – в зависимости от того, что лучше отвечает ситуации.

Приведем пример определения фильтра:

def cut(value, arg):

“Удаляет вcе вхождения arg из данной строки” return value.replace(arg, ‘’)

А вот пример использования этого фильтра для удаления пробелов из значения переменной:

{{ somevariable|cut:” “ }}

Большинство фильтров не принимают аргумент. В таком случае можете опустить его в определении функции:

Привет, {{ person.name }}.

{% ifequal name.birthday today %} С днем рождения!

{% else %}

Не забудьте заглянуть сюда в свой день рождения, вас ждет приятный сюрприз.

{% endifequal %}

В откомпилированном виде этот шаблон­ представлен таким списком узлов:

•• Текстовый узел: “Привет”

•• Узел переменной: person.name

•• Текстовый узел: “.\n\n”

•• Узел IfEqual: name.birthday и today

При вызове метода render()откомпилированного шаблона­ он вызывает метод render() каждого объекта Node в списке узлов с заданным контекстом. Возвращаемые ими значения объединяются и формируют результат отображения шаблона­. Следовательно, чтобы определить шаблонный­ тег, необходимо описать, как его текстовое представление преобразуется в объект Node (функция компиляции) и что делает метод render().

В следующих разделах мы опишем все этапы создания собственного тега.

Функция компиляции

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

Напишем, к примеру, шаблонный­ тег {% current_time %} для вывода текущих даты и времени, отформатированных в соответствии с указанным в теге параметром, который должен быть задан, как принято в функции strftime (см. http://www.djangoproject.com/r/python/strftime/). Прежде всего определимся с синтаксисом тега. Допустим, что в нашем случае он будет выглядеть так:

<p>Сейчас {% current_time “%Y-%m-%d %I:%M %p” %}.</p>

Примечание

На самом деле этот тег избыточен – имеющийся в Django тег {% now %} делает то же самое и к тому же имеет более простой синтаксис. Мы привели этот пример исключительно в учебных целях.

Функция компиляции этого тега должна принять параметр и создать объект Node:

from django import template

register = template.Library()

def do_current_time(parser, token): try:

#split_contents() знает, что строки в кавычках разбивать

#не нужно.

tag_name, format_string = token.split_contents() except ValueError:

msg = ‘Тег %r требует один аргумент’ % token.split_contents()[0] raise template.TemplateSyntaxError(msg)

return CurrentTimeNode(format_string[1:-1])

Разберемся, что здесь делается:

•• Любая функция компиляции шаблонного­ тега принимает два аргумента: parser и token. Аргумент parser – это объект, представляющий синтаксический анализатор шаблона­. В этом примере он не используется. Аргумент token – это текущая выделенная анализатором лексема.

•• Атрибут token.contents содержит исходный текст тега. В нашем случае это строка ‘current_time “%Y-%m-%d %I:%M %p”’.

•• Метод token.split_contents() разбивает строку по пробелам, оставляя нетронутыми фрагменты, заключенные в кавычки. Не пользуйтесь методом token.contents.split() (в нем применяется стандартная для Python семантика разбиения строк). Он выполняет разбиение по всем пробелам, в том числе и по пробелам, находящимся внутри кавычек.

•• При обнаружении любой синтаксической ошибки эта функция должна возбудить исключение django.template.TemplateSyntaxError с содержательным сообщением.

•• Не «зашивайте» имя тега в текст сообщения об ошибке, потому что тем самым вы привязываете имя тега к функции. Имя тега всегда можно получить из элемента token.split_contents()[0], даже когда тег не имеет параметров.

•• Функция возвращает объект класса CurrentTimeNode (который мы создадим чуть ниже), содержащий все, что узел должен знать о теге. В данном случае передается только аргумент “%Y-%m-%d %I:%M %p”. Кавычки в начале и в конце строки удаляются с помощью конструкции format_string[1:-1].

•• Функция компиляции шаблонного­ тега обязана вернуть подкласс класса Node; любое другое значение приведет к ошибке.

Создание класса узла шаблона­

Далее мы должны определить подкласс класса Node, имеющий метод render(). В нашем примере этот класс будет называться CurrentTimeNode.

import datetime

class CurrentTimeNode(template.Node): def __init__(self, format_string):

self.format_string = str(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 можно использовать в качестве декоратора:

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

# ...

@register.tag

def shout(parser, token):

# ...

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

Запись переменной в контекст

В примере из предыдущего раздела функция отображения тега просто возвращает некоторое значение. Однако вместо этого часто бывает удобно установить значение какой-либо шаблонной­ переменной. Это по-

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

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

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

Разбор до обнаружения следующего шаблонного­ тега с сохранением содержимого

В предыдущем примере функция do_comment() отбрасывала все, что находится между тегами {% comment %} и {% endcomment %}. Но точно так же можно что-то сделать с кодом, расположенным между шаблонными­ тегами.

Рассмотрим в качестве примера шаблонный­ тег {% upper %}, который переводит в верхний регистр все символы, находящиеся между ним и тегом {% endupper %}:

{% upper %}

Это будет выведено в верхнем регистре, {{ user_name }}. {% endupper %}

Как и в предыдущем примере, мы вызываем метод parser.parse(). Но на этот раз полученный список nodelist передается конструктору Node:

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()

Из нового в методе UpperNode.render() есть только обращение к методу self.nodelist.render(context), который вызывает метод render() каждого узла в списке.

Другие примеры сложных реализаций метода отображения можно найти в исходном коде тегов {% if %}, {% for %}, {% ifequal %} и {% ifchanged %}, в файле django/template/defaulttags.py.

Вспомогательная функция для создания простых тегов

Многие шаблонные­ теги принимают единственный аргумент – строку или ссылку на шаблонную­ переменную – и возвращают строку после