Синтаксис¶

Шаблон Django – это просто текстовый файл, или строка Python, которые следуют языку шаблонов Django. Определенные конструкции распознаются и интерпретируются шаблонизатором. Основные – это переменные и теги.

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

Синтаксис языка шаблонов Django использует четыре конструкции.

My first name is {{ first_name }}. My last name is {{ last_name }}.

My first name is John. My last name is Doe.

{{ my_dict.key }}
{{ my_object.attribute }}
{{ my_list.0 }}

{% csrf_token %}

{% cycle 'odd' 'even' %}

{% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}

{{ django|title }}

The Web Framework For Perfectionists With Deadlines

{{ my_date|date:"Y-m-d" }}

{# this won't be rendered #}

Компоненты¶

Настройки¶

Шаблоны можно настроить с помощью настройки TEMPLATES. Это список, который содержит настройки для систем шаблонов. По умолчанию настройка пустая. settings.py, сгенерированный командой startproject, содержит более полезное значение:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {
            # ... some options here ...
        },
    },
]

BACKEND путь для импорта Python к классу бэкенда шаблонов. Встроенные бэкенды это django.template.backends.django.DjangoTemplates и django.template.backends.jinja2.Jinja2.

Т.к. большинство систем шаблонов загружают шаблоны с файлов, настройки содержат:

• DIRS, которая содержим список каталогов с шаблонами. Бэкенд ищет в них шаблон в указанном порядке.

• APP_DIRS указывает бэкенду искать ли шаблоны в установленных приложениях. Каждый бэкенд определяет определенное название для каталога с шаблонами в приложении.

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

OPTIONS содержит настройки специфические для бэкенда.

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

Модуль django.template.loader предоставляет две функции для загрузки шаблонов.

get_template(template_name, using=None)¶

Эта функция загружает шаблон с указанным названием и возвращает объект Template.

Возвращаемое значение зависит от используемого бэкенда т.к. каждый бэкенд использует свой класс Template.

get_template() пытается загрузить шаблон каждым из бэкендов, пока шаблон не будет загружен. Если шаблон не найден, будет вызвано исключение TemplateDoesNotExist. Если шаблон найден, но синтаксис не верен, будет вызвано TemplateSyntaxError.

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

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

select_template(template_name_list, using=None)¶

select_template() как и get_template(), но принимает список названий шаблонов. Пытается загрузить по очереди каждый из шаблонов, возвращает первый загруженный.

Если не удалось загрузить шаблон, вызываются исключения, описанные в django.template:

exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)¶

Это исключение вызывается, если шаблоне не был найден. Принимает дополнительные параметры, которые отображаются на странице ошибки:

backend

Бэкенд шаблонов, который вызывал исключение.

tried

Список источников шаблонов, которые проверялись при поиске шаблона. Состоит из списка кортежей вида (origin, status), где origin – это объект Origin, а status – строка, которая описывает ошибку.

chain

Список промежуточных ошибок TemplateDoesNotExist, которые были вызваны при поиске шаблона. Используется функцией, например get_template(), которая пытается загрузить шаблон, используя разные бэкенды.

exception TemplateSyntaxError(msg)¶

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

Объекты Template, которые возвращают get_template() и select_template(), должны содержать метод render() со следующей сигнатурой:

Template.render(context=None, request=None)¶

Рендерит шаблон с переданным контекстом.

Если context передан, это должен быть dict. Если не передан, используется пустой контекст.

Если передан request, это должен быть экземпляр HttpRequest. Шаблонизатор должен добавить его в шаблон, как и CSRF токен. Как это должно происходит определяет шаблонизатор.

Пример алгоритма поиска шаблона. Возьмем следующую настройку TEMPLATES:

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

Если вызвать get_template('story_detail.html'), Django будет искать следующие файлы:

• /home/html/example.com/story_detail.html (шаблонизатор 'django')

• /home/html/default/story_detail.html (шаблонизатор 'django')

• /home/html/jinja2/story_detail.html (шаблонизатор 'jinja2')

Если вызвать select_template(['story_253_detail.html', 'story_detail.html']), Django бдудет искать:

• /home/html/example.com/story_253_detail.html (шаблонизатор 'django')

• /home/html/default/story_253_detail.html (шаблонизатор 'django')

• /home/html/jinja2/story_253_detail.html (шаблонизатор 'jinja2')

• /home/html/example.com/story_detail.html (шаблонизатор 'django')

• /home/html/default/story_detail.html (шаблонизатор 'django')

• /home/html/jinja2/story_detail.html (шаблонизатор 'jinja2')

Если Django находит шаблон, поиск останавливается.

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

Хранить все шаблоны в корневом каталоге может привести к хаосу в шаблонах.

Чтобы загрузить каталог из подкаталога, просто используйте слэш:

get_template("news/story_detail.html")

При использовании настроек TEMPLATES, приведенных выше, Django будет искать следующие шаблоны:

• /home/html/example.com/news/story_detail.html (шаблонизатор 'django')

• /home/html/default/news/story_detail.html (шаблонизатор 'django')

• /home/html/jinja2/news/story_detail.html (шаблонизатор 'jinja2')

Django предоставляет несколько вспомогательных функций для работы с шаблонами.

render_to_string(template_name, context=None, request=None, using=None)¶

render_to_string() загружает шаблон как и get_template(), и вызывает метод render(). Принимает следующие аргументы.

template_name

Название шаблона, который будет загружен и выполнен. Если указать список шаблонов, для поиска шаблонов Django будет использовать select_template() вместо get_template().

context

dict, который будет использовать как контекст при рендеринге шаблона.

request

Необязательный HttpRequest, который будет использоваться при рендеринге шаблона.

using

Дополнительный механизм шаблонов NAME. Поиск шаблона будет ограничен этим движком.

Например:

from django.template.loader import render_to_string

rendered = render_to_string("my_template.html", {"foo": "bar"})

Смотрите также render() и render_to_response(), которые вызывают render_to_string() и передают результат в HttpResponse, который можно вернуть из представления.

Вы можете использовать шаблонизатор непосредственно:

engines¶

Шаблонизаторы доступны в django.template.engines:

from django.template import engines

django_engine = engines["django"]
template = django_engine.from_string("Hello {{ name }}!")

Ключ 'django' в этом примере соответствует NAME.

Встроенные бэкенды¶

class DjangoTemplates¶

Укажите 'django.template.backends.django.DjangoTemplates' в BACKEND, чтобы использовать шаблонизатор Django.

Если APP_DIRS равна True, DjangoTemplates будет искать шаблоны в подкаталогах templates установленных приложений. Такое название используется для обратной совместимости.

DjangoTemplates принимает следующие параметры OPTIONS:

• 'autoescape': логическое значение, которое определяет, включено ли автоматическое экранирование HTML.

  По умолчанию содержит пустой список.

  Предупреждение

  Устанавливайте значение «False» только в том случае, если вы отображаете шаблоны, отличные от HTML!

• 'context_processors': список путей Python, который указывают на процессоры контекста, которые добавляют дополнительные переменные в контекст при рендеринге шаблона в процессе обработки запроса. Процессоры контекста – это функции, или другие вызываемые объекты, которые принимают объект запроса и возвращают dict значений, который будут добавлены в контекст.

  По умолчанию содержит пустой список.

  Подробности смотрите в описании RequestContext.

• 'debug': булево значение, которое включает/выключает отладку шаблонов. При True будет отображаться страница с отладочной информацией, если возникнет ошибка при рендеринге шаблона. Страница показывает часть шаблона, которая вызвала ошибку.

  По умолчанию равна значению DEBUG.

• 'loaders': список путей Python к загрузчикам шаблонов. Каждый класс Loader знает как загрузить шаблон из определенного источника. Можно использовать кортеж вместо строки. Первым элементом должен быть путь к Loader, последующие элементы передаются в Loader при инициализации.

  Значение по умолчанию зависит от значений DIRS и APP_DIRS.

  Подробности смотрите в Типы загрузчиков.

• 'string_if_invalid': строка, которая будет использоваться для неправильных (например, с опечаткой) переменных в шаблоне.

  По умолчанию пустая строка.

  Подробности смотрите в Как обрабатываются неправильные переменные.

• 'file_charset': кодировка, которая используется при чтении файла шаблона с диска.

  По умолчанию содержит пустой список.

• 'libraries': словарь библиотек тегов, которые зарегистрированы для бэкенда. Состоит из названия библиотеки и пути для импорта. Позволяет добавлять новые библиотеки, или поменять название для существующих. Например:

  OPTIONS = {
      "libraries": {
          "myapp_tags": "path.to.myapp.tags",
          "admin.urls": "django.contrib.admin.templatetags.admin_urls",
      },
  }
  

  Библиотеки могут быть загружены с помощью тега {% load %}, в котором нужно указать соответствующий ключ словаря.

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

  OPTIONS = {
      "builtins": ["myapp.builtins"],
  }
  

  Теги и фильтры из этих библиотек могу быть использованы без вызова {% load %}.

class Jinja2¶

Для использования необходимо установить Jinja2:

$ python -m pip install Jinja2

...\> py -m pip install Jinja2

Укажите 'django.template.backends.jinja2.Jinja2' в BACKEND для настройки шаблонизатора Jinja2.

Если APP_DIRS равна True, Jinja2 будет искать шаблоны в подкаталоге ``jinja2``установленных приложений.

Самой важной настройкой в OPTIONS является 'environment'. Это путь для импорта функции, или другого вызываемого объекта, которая возвращает Jinja2. По умолчанию 'jinja2.Environment'. Django вызывает функцию и передает другие параметры как именованные аргументы. Также Django указывает значения по умолчанию для некоторых параметров Jinja2:

• 'autoescape': True

• 'loader': загрузчик соответствующий настройкам DIRS и APP_DIRS

• 'auto_reload': settings.DEBUG

• 'undefined': DebugUndefined if settings.DEBUG else Undefined

DjangoTemplates принимает следующие параметры OPTIONS:

• 'context_processors': список путей Python, который указывают на процессоры контекста, которые добавляют дополнительные переменные в контекст при рендеринге шаблона в процессе обработки запроса. Процессоры контекста – это функции, или другие вызываемые объекты, которые принимают объект запроса и возвращают dict значений, который будут добавлены в контекст.

  По умолчанию содержит пустой список.

  Использование контекстных процессоров с шаблонами Jinja2 не рекомендуется.

  Контекстные процессоры полезны с шаблонами Django, поскольку шаблоны Django не поддерживают вызов функций с аргументами. Поскольку в Jinja2 такого ограничения нет, рекомендуется поместить функцию, которую вы будете использовать в качестве обработчика контекста, в глобальные переменные, доступные для шаблона, используя jinja2.Environment, как описано ниже. Затем вы можете вызвать эту функцию в шаблоне:

  {{ function(request) }}
  

  Некоторые процессоры контекста шаблонов Django возвращают фиксированное значение. Для шаблонов Jinja2 этот уровень косвенности не обязателен, поскольку вы можете добавлять константы непосредственно в jinja2.Environment.

  Исходный вариант использования для добавления процессоров контекста для Jinja2 включал:

  • Выполнение дорогостоящих вычислений, зависящих от запроса.

  • Нужен результат в каждом шаблоне.

  • Использование результата несколько раз в каждом шаблоне.

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

Настройки по умолчанию намерено сокращены до минимума. Jinja2 не создает окружение заточенное под Django. Шаблонизатор ничего не знает про процессоры контекста Django, фильтры и теги. Чтобы использовать API Django, необходимо настроить окружение шаблонизатора.

Например, вы можете создать следующий myproject/jinja2.py:

from django.templatetags.static import static
from django.urls import reverse

from jinja2 import Environment


def environment(**options):
    env = Environment(**options)
    env.globals.update(
        {
            "static": static,
            "url": reverse,
        }
    )
    return env

и указать в настройке 'environment' 'myproject.jinja2.environment'.

Теперь вы можете использовать в шаблонах Jinja2:

<img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">

<a href="{{ url('admin:index') }}">Administration</a>

Концепция тегов и фильтров существует как в шаблонах Django, так и Jinja2, но используется по разному. Так как Jinja2 позволяет передавать аргументы при вызове функций и методов, многие вещи, для которых необходим тег или фильтр в шаблонах Django, можно использовать напрямую в шаблонах Jinja2, как это делается в примере выше. Глобальное пространство имен Jinja2 не требует процессоров контекста. Язык шаблонов Django не имеет аналогов тестов Jinja2.