Переменные¶

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

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

• Поиск в словаре. Например: foo["bar"]

• Поиск атрибута. Например: foo.bar

• Поиск в списке. Напрмиер: foo[bar]

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

The template system uses the first lookup type that works. It’s short-circuit logic. Here are a few examples:

>>> 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."

If any part of the variable is callable, the template system will try calling it. Example:

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

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

• If the variable raises an exception when called, the exception will be propagated, unless the exception has an attribute silent_variable_failure whose value is True. If the exception does have a silent_variable_failure attribute whose value is True, the variable will render as the value of the engine’s string_if_invalid configuration option (an empty string, by default). Example:

  >>> 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 в ORM, содержит silent_variable_failure = True. Поэтому, если вы используете объекты модели в шаблонах, исключение DoesNotExist будет проигнорировано.

• Функция из переменной может быть вызвана, только если не требует обязательных аргументов. В таком случае шаблон вставит вместо переменной значение string_if_invalid.

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

  A good example is the delete() method on each Django model object. The template system shouldn’t be allowed to do something like this:

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

  Чтобы избежать этого, укажите атрибут alters_data в функции или методе. Шаблон не будет вызывать переменную, если значение содержит alters_data=True, и будет использовать значение настройки string_if_invalid. Встроенные методы delete() и save() модели содержат атрибут 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, если необходимо вывести в шаблоне {% и %} как строки.

A similar issue exists if you want to include these sequences in template filter or tag arguments. For example, when parsing a block tag, Django’s template parser looks for the first occurrence of %} after a {%. This prevents the use of "%}" as a string literal. For example, a TemplateSyntaxError will be raised for the following expressions:

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

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

The same issue can be triggered by using a reserved sequence in filter arguments:

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

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

Классы наследники Context: RequestContext¶

class RequestContext(request, dict_=None, processors=None)¶

Django comes with a special Context class, django.template.RequestContext, that acts slightly differently from the normal django.template.Context. The first difference is that it takes an HttpRequest as its first argument. For example:

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

Еще одно отличие – он автоматически добавляет различные переменные в соответствии с опцией context_processors шаблонизатора.

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.core.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))

Встроенные процессоры контекста¶

Вот список процессоров контекста по умолчанию:

Как создать свой процессор контекста¶

A context processor has a simple interface: It’s a Python function that takes one argument, an HttpRequest object, and returns a dictionary that gets added to the template context. Each context processor must return a dictionary.

Код процессора может находится где угодно. Главное не забыть указать его в опции 'context_processors' настройки:setting: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.

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

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

django.template.loaders.cached.Loader

class cached.Loader¶

By default (when DEBUG is True), the template system reads and compiles your templates every time they’re rendered. While the Django template system is quite fast, the overhead from reading and compiling templates can add up.

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

This loader is automatically enabled if OPTIONS['loaders'] isn’t specified and OPTIONS['debug'] is False (the latter option defaults to the value of DEBUG).

You can also enable template caching with some custom template loaders using settings like this:

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