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

Переменные и поиск ¶

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

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

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

Обратите внимание, что «bar» в выражении шаблона, например, будет интерпретироваться как буквальная строка и не будет использовать значение переменной «bar», если она существует в контексте шаблона.{{ foo.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 . Так что, если вы используете шаблоны Django с объектами модели Django, любое исключение не сработает.silent_variable_failure = TrueDoesNotExist

• Переменная может быть вызвана только в том случае, если у нее нет обязательных аргументов. В противном случае система вернет значение 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 для следующих выражений будет повышен a :

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

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

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

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

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

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

classRequestContext ( запрос , 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'. Это связанный с безопасностью обработчик контекста, который требуется администратору и другим приложениям 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

класс 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

класс 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«s будет загружен первый и ваш будет игнорироваться.

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

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

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

django.template.loaders.cached.Loader

класс cached.Loader¶

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

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

Этот загрузчик автоматически включается , если OPTIONS['loaders']не указан и OPTIONS['debug']является False(последним вариантом по умолчанию значения DEBUG).

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

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

класс locmem.Loader¶

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

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

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

По умолчанию этот загрузчик отключен.

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

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

класс Loader¶

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

get_template_sources( имя_шаблона ) ¶

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

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

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

get_contents( происхождение ) ¶

Возвращает содержимое шаблона для данного 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() обычно не нужно переопределять.