Язык шаблонов 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, базовый класс всех исключений DoesNotExist API базы данных Django, содержит 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) [исходный код]

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

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/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 [исходный код]

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

get_template_sources(template_name) [исходный код]

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

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

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

get_contents(origin)

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

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

get_template(template_name, skip=None) [исходный код]

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

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

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