Язык шаблонов Django: для программистов Python

Переменные и обращения к данным

Имена переменных должны состоять из любых букв (A-Z), любых цифр (0-9), подчеркивания (но они не должны начинаться с подчеркивания) или точки.

Точки имеют особое значение в рендеринге шаблонов. Точка в имени переменной обозначает обращение к данным. В частности, когда система шаблонов встречает точку в имени переменной, она пытается выполнить следующие обращения в указанном порядке:

• Обращение к словарю. Пример: foo["bar"]
• Обращение к атрибуту. Пример: foo.bar
• Обращение по индексу списка. Пример: foo[bar]

Обратите внимание, что «bar» в выражении шаблона, например, {{ foo.bar }}, будет интерпретировано как буквальная строка, а не как значение переменной «bar», если она существует в контексте шаблона.

Система шаблонов использует первый тип обращения, который работает. Это логика короткого замыкания. Вот несколько примеров:

>>> from django.template import Context, Template
>>> t = Template("My name is {{ person.first_name }}.")
>>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
>>> t.render(Context(d))
"My name is Joe."

>>> class PersonClass:
...     pass
...
>>> p = PersonClass()
>>> p.first_name = "Ron"
>>> p.last_name = "Nasty"
>>> t.render(Context({"person": p}))
"My name is Ron."

>>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
>>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
>>> t.render(c)
"The first stooge in the list is Larry."

Если какая-либо часть переменной является вызываемым объектом, система шаблонов попытается вызвать его. Пример:

>>> class PersonClass2:
...     def name(self):
...         return "Samantha"
...
>>> t = Template("My name is {{ person.name }}.")
>>> t.render(Context({"person": PersonClass2}))
"My name is Samantha."

Вызываемые переменные немного сложнее, чем переменные, которые требуют только прямых обращений. Вот некоторые моменты, которые следует учитывать:

• Если при вызове переменной возникает исключение, это исключение будет передано, если у исключения нет атрибута silent_variable_failure со значением True. Если исключение имеет атрибут silent_variable_failure со значением True, переменная будет отображаться как значение конфигурации движка string_if_invalid (по умолчанию пустая строка). Пример:

  >>> t = Template("My name is {{ person.first_name }}.")
  >>> class PersonClass3:
  ...     def first_name(self):
  ...         raise AssertionError("foo")
  ...
  >>> p = PersonClass3()
  >>> t.render(Context({"person": p}))
  Traceback (most recent call last):
  ...
  AssertionError: foo
  
  >>> class SilentAssertionError(Exception):
  ...     silent_variable_failure = True
  ...
  >>> class PersonClass4:
  ...     def first_name(self):
  ...         raise SilentAssertionError
  ...
  >>> p = PersonClass4()
  >>> t.render(Context({"person": p}))
  "My name is ."
  

  Обратите внимание, что django.core.exceptions.ObjectDoesNotExist, являющийся базовым классом для всех исключений API базы данных Django DoesNotExist, имеет silent_variable_failure = True. Поэтому, если вы используете Django-шаблоны с объектами Django-моделей, любое исключение DoesNotExist будет проигнорировано.

• Переменная может быть вызвана только в случае отсутствия обязательных аргументов. В противном случае система вернёт значение параметра движка string_if_invalid.

• При вызове некоторых переменных могут возникнуть побочные эффекты, и позволить системе шаблонов к ним получить доступ было бы либо глупо, либо небезопасно.

  Хороший пример — метод delete() для каждого объекта модели Django. Системе шаблонов не следует разрешать делать что-то подобное:

  I will now delete this valuable data. {{ data.delete }}
  

  Чтобы предотвратить это, установите атрибут alters_data на вызываемую переменную. Система шаблонов не будет вызывать переменную, если у нее установлен атрибут alters_data=True, а вместо этого будет подменять переменную значением string_if_invalid безусловно. Динамически сгенерированные методы delete() и save() для объектов Django-моделей автоматически получают alters_data=True. Пример:

  def sensitive_function(self):
      self.database_record.delete()
  
  
  sensitive_function.alters_data = True
  

• Иногда по каким-то причинам может потребоваться отключить эту функцию и указать системе шаблонов не вызывать переменную независимо от чего. Для этого установите атрибут do_not_call_in_templates на вызываемой переменной со значением True. Система шаблонов затем будет действовать так, как если бы ваша переменная не была вызываемой (позволяя вам получать доступ к атрибутам вызываемого объекта, например).

Обработка недопустимых переменных

В общем случае, если переменная не существует, система шаблонов вставляет значение конфигурации движка string_if_invalid, которое по умолчанию установлено в '' (пустая строка).

Фильтры, применяемые к невалидной переменной, будут применяться только если string_if_invalid установлено в '' (пустая строка). Если string_if_invalid установлено в любое другое значение, фильтры переменных будут проигнорированы.

Это поведение немного отличается для тегов шаблонов if, for и regroup. Если невалидная переменная предоставляется одному из этих тегов шаблонов, переменная будет интерпретирована как None. Фильтры всегда применяются к недопустимым переменным внутри этих тегов шаблонов.

Если string_if_invalid содержит '%s', маркер формата будет заменён именем невалидной переменной.

Встроенные переменные

Каждый контекст содержит True, False и None. Как можно было ожидать, эти переменные разрешаются до соответствующих объектов Python.

Ограничения с буквальными строками

Язык шаблонов Django не имеет способа экранировать символы, используемые для его собственной синтаксической конструкции. Например, тег templatetag необходим, если вам нужно вывести последовательности символов, такие как {% и %}.

Аналогичная проблема возникает, если вы хотите включить эти последовательности в аргументы фильтров или тегов шаблонов. Например, при разборе тега блока Django-парсер шаблонов ищет первое вхождение %} после {%. Это предотвращает использование "%}" в качестве буквальной строки. Например, произойдёт исключение TemplateSyntaxError для следующих выражений:

{% include "template.html" tvar="Some string literal with %} in it." %}

{% with tvar="Some string literal with %} in it." %}{% endwith %}

Та же проблема может возникнуть при использовании зарезервированной последовательности в аргументах фильтра:

{{ some.variable|default:"}}" }}

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

Использование RequestContext

class RequestContext(request, dict_=None, processors=None, use_l10n=None, use_tz=None, autoescape=True) [source]

Django поставляется со специальным классом объекта контекста, django.template.RequestContext, который ведет себя немного иначе, чем обычный django.template.Context. Первое отличие заключается в том, что он принимает объект запроса в качестве первого аргумента. Например:

c = RequestContext(
    request,
    {
        "foo": "bar",
    },
)

Второе отличие заключается в том, что он автоматически заполняет контекст несколькими переменными в соответствии с настройкой context_processors движка.

Настройка context_processors представляет собой список вызовов — обработчиков контекста — которые принимают объект запроса в качестве аргумента и возвращают словарь элементов, которые нужно объединить в контекст. В файле настроек по умолчанию сгенерированный по умолчанию движок шаблонов содержит следующие обработчики контекста:

[
    "django.template.context_processors.request",
    "django.contrib.auth.context_processors.auth",
    "django.contrib.messages.context_processors.messages",
]

Помимо этого, RequestContext всегда включает 'django.template.context_processors.csrf'. Это связанный с безопасностью обработчик контекста, необходимый для админки и других приложений contrib, и, в случае случайной неправильной настройки, он преднамеренно жёстко закодирован и не может быть отключен в настройке context_processors.

Каждый обработчик применяется в порядке следования. Это означает, что если один обработчик добавляет переменную в контекст, а второй обработчик добавляет переменную с тем же именем, второй перепишет первый. Обработчики по умолчанию описаны ниже.

from django.template import RequestContext

request_context = RequestContext(request)
request_context.push({"my_name": "Adrian"})

Также вы можете предоставить RequestContext список дополнительных обработчиков, используя необязательный третий позиционный аргумент, processors. В этом примере экземпляр RequestContext получает переменную ip_address:

from django.http import HttpResponse
from django.template import RequestContext, Template


def ip_address_processor(request):
    return {"ip_address": request.META["REMOTE_ADDR"]}


def client_ip_view(request):
    template = Template("{{ title }}: {{ ip_address }}")
    context = RequestContext(
        request,
        {
            "title": "Your IP Address",
        },
        [ip_address_processor],
    )
    return HttpResponse(template.render(context))

Встроенные обработчики контекста

Вот что делает каждый из встроенных обработчиков:

Создание собственных обработчиков контекста

Обработчик контекста имеет простой интерфейс: это функция Python, которая принимает один аргумент, объект HttpRequest, и возвращает словарь, который добавляется в контекст шаблона.

Например, чтобы добавить настройку DEFAULT_FROM_EMAIL в каждый контекст:

from django.conf import settings


def from_email(request):
    return {
        "DEFAULT_FROM_EMAIL": settings.DEFAULT_FROM_EMAIL,
    }

Пользовательские обработчики контекста могут находиться где угодно в вашем коде. Django интересует только то, что ваши пользовательские обработчики контекста указаны в опции 'context_processors' в настройке TEMPLATES — или аргументе context_processors метода Engine, если вы используете его напрямую.

Параметр DIRS

Укажите Django свои каталоги шаблонов, используя параметр DIRS в настройке TEMPLATES в вашем файле настроек — или аргумент dirs для Engine. Он должен быть установлен в список строк, содержащих полные пути к вашим каталогам шаблонов:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            "/home/html/templates/lawrence.com",
            "/home/html/templates/default",
        ],
    },
]

Шаблоны могут располагаться где угодно, при условии, что каталоги и шаблоны доступны для веб-сервера. Они могут иметь любое расширение, например .html или .txt, или вообще не иметь расширения.

Обратите внимание, что эти пути должны использовать косые черты в стиле Unix, даже в Windows.

Типы загрузчиков

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

Некоторые из этих других загрузчиков по умолчанию отключены, но вы можете активировать их, добавив параметр 'loaders' в свой бэкенд DjangoTemplates в настройке TEMPLATES или передав аргумент loaders в Engine. loaders должен быть списком строк или кортежей, где каждый элемент представляет класс загрузчика шаблонов. Вот загрузчики шаблонов, поставляемые с Django:

django.template.loaders.filesystem.Loader

class filesystem.Loader

Загружает шаблоны с файловой системы в соответствии с DIRS.

Этот загрузчик включен по умолчанию. Однако он не найдет никаких шаблонов, пока вы не зададите DIRS непустым списком:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
    }
]

Вы также можете переопределить 'DIRS' и указать определенные каталоги для конкретного загрузчика файловой системы:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.filesystem.Loader",
                    [BASE_DIR / "templates"],
                ),
            ],
        },
    }
]

django.template.loaders.app_directories.Loader

class app_directories.Loader

Загружает шаблоны из приложений Django с файловой системы. Для каждого приложения в INSTALLED_APPS загрузчик ищет подкаталог templates. Если каталог существует, Django ищет шаблоны в нем.

Это означает, что вы можете хранить шаблоны вместе со своими отдельными приложениями. Это также помогает распространять приложения Django с предустановленными шаблонами.

Например, для этой настройки:

INSTALLED_APPS = ["myproject.polls", "myproject.music"]

…тогда get_template('foo.html') будет искать foo.html в этих каталогах в этом порядке:

• /path/to/myproject/polls/templates/
• /path/to/myproject/music/templates/

… и воспользуется первым найденным.

Порядок следования INSTALLED_APPS важен! Например, если вы хотите настроить Django admin, вы можете переопределить стандартный admin/base_site.html шаблон из django.contrib.admin своим собственным admin/base_site.html в myproject.polls. Тогда вы должны убедиться, что ваше myproject.polls стоит перед django.contrib.admin в INSTALLED_APPS, иначе django.contrib.admin будут загружены первыми, и ваши будут проигнорированы.

Обратите внимание, что загрузчик выполняет оптимизацию при первом запуске: он кэширует список пакетов INSTALLED_APPS, у которых есть подкаталог templates.

Вы можете включить этот загрузчик, установив APP_DIRS в True:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
    }
]

django.template.loaders.cached.Loader

class cached.Loader

Хотя система шаблонов Django довольно быстрая, если ей нужно читать и компилировать ваши шаблоны каждый раз, когда они рендерятся, накладные расходы от этого могут накапливаться.

Вы настраиваете загрузчик кэшированных шаблонов списком других загрузчиков, которые он должен обернуть. Обернутые загрузчики используются для поиска неизвестных шаблонов, когда они впервые встречаются. Затем загрузчик кэширует скомпилированные Template в памяти. Для последующих запросов на загрузку того же шаблона возвращается экземпляр кэшированного Template.

Этот загрузчик автоматически включён, если OPTIONS['loaders'] не указан.

Вы можете вручную указать кэширование шаблонов с помощью некоторых пользовательских загрузчиков шаблонов, используя настройки, например так:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.cached.Loader",
                    [
                        "django.template.loaders.filesystem.Loader",
                        "django.template.loaders.app_directories.Loader",
                        "path.to.custom.Loader",
                    ],
                ),
            ],
        },
    }
]

Примечание

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

django.template.loaders.locmem.Loader

class locmem.Loader

Загружает шаблоны из словаря Python. Это полезно для тестирования.

Этот загрузчик принимает словарь шаблонов в качестве первого аргумента:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.locmem.Loader",
                    {
                        "index.html": "content here",
                    },
                ),
            ],
        },
    }
]

Этот загрузчик по умолчанию отключён.

Django использует загрузчики шаблонов в порядке, указанном в параметре 'loaders'. Он использует каждый загрузчик, пока один из них не найдет соответствие.

Методы загрузчика

class Loader [source]

Загружает шаблоны из заданного источника, такого как файловая система или база данных.

get_template_sources(template_name) [source]

Метод, который принимает template_name и возвращает Origin объекты для каждого возможного источника.

Например, загрузчик файловой системы может получить 'index.html' в качестве template_name аргумента. Этот метод вернёт объекты `Origin` для полного пути к index.html, как он отображается в каждом каталоге шаблонов, который просматривает загрузчик.

Методу не нужно проверять, существует ли шаблон по заданному пути, но он должен убедиться, что путь корректен. Например, загрузчик файловой системы проверяет, лежит ли путь в пределах допустимого каталога шаблонов.

get_contents(origin)

Возвращает содержимое шаблона, заданного объектом Origin.

Здесь загрузчик файловой системы читает содержимое из файловой системы, а загрузчик базы данных — из базы данных. Если соответствующего шаблона не существует, должно быть выброшено исключение TemplateDoesNotExist.

get_template(template_name, skip=None) [source]

Возвращает объект Template для заданного template_name, перебирая результаты из get_template_sources() и вызывая get_contents(). Это возвращает первый соответствующий шаблон. Если шаблон не найден, поднимается исключение TemplateDoesNotExist.

Необязательный аргумент skip — список объектов `Origin`, которые нужно пропустить при расширении шаблонов. Это позволяет шаблонам расширять другие шаблоны с тем же именем. Это также используется для предотвращения рекурсивных ошибок.

В общем случае достаточно определить get_template_sources() и get_contents() для настраиваемых загрузчиков шаблонов. get_template() обычно переопределять не нужно.