Язык шаблонов 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 необходим, если вам нужно вывести последовательности символов типа {% и %}.

Аналогичная проблема возникает, если вы хотите включить эти последовательности в фильтр шаблона или аргументы тегов. Например, при разборе тега block, анализатор шаблонов 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)[исходный код]¶

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

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

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

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

[
    'django.template.context_processors.debug',
    'django.template.context_processors.request',
    'django.contrib.auth.context_processors.auth',
    'django.contrib.messages.context_processors.messages',
]

В дополнение к ним, RequestContext всегда включает 'django.template.context_processors.csrf'. Это контекстный процессор, связанный с безопасностью, необходимый администратору и другим приложениям, и, на случай случай случайной неправильной конфигурации, он намеренно жестко закодирован и не может быть отключен в опции 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 для каждого тега является потокобезопасной. Для получения дополнительной информации см. раздел template tag thread safety considerations.

Changed in Django 4.1:

Кэшированный загрузчик шаблонов был включен всякий раз, когда OPTIONS['loaders'] не указан. Ранее он был включен только тогда, когда DEBUG был False.

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() обычно не нужно переопределять.