Обновление шаблонов до Django 1.8

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

Настройки TEMPLATES

В Django 1.8 была добавлена новая настройка: TEMPLATES. Все существующие настройки, связанные с шаблонами, были устаревшими.

В период устаревания Django будет создавать обратную совместимость TEMPLATES на основе TEMPLATE_* настроек, если вы сами её не определите.

Вот как определить TEMPLATES в вашем модуле настроек.

Если вы используете значение по умолчанию TEMPLATE_LOADERS, то есть, если оно не определено в вашем файле настроек или если оно установлено в:

['django.template.loaders.filesystem.Loader',
 'django.template.loaders.app_directories.Loader']

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

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            # insert your TEMPLATE_DIRS here
        ],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                # Insert your TEMPLATE_CONTEXT_PROCESSORS here or use this
                # list if you haven't customized them:
                'django.contrib.auth.context_processors.auth',
                'django.template.context_processors.debug',
                'django.template.context_processors.i18n',
                'django.template.context_processors.media',
                'django.template.context_processors.static',
                'django.template.context_processors.tz',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Если вы не используете значение по умолчанию TEMPLATE_LOADERS, то вы должны определить TEMPLATES следующим образом:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            # insert your TEMPLATE_DIRS here
        ],
        'OPTIONS': {
            'context_processors': [
                # Insert your TEMPLATE_CONTEXT_PROCESSORS here or use this
                # list if you haven't customized them:
                'django.contrib.auth.context_processors.auth',
                'django.template.context_processors.debug',
                'django.template.context_processors.i18n',
                'django.template.context_processors.media',
                'django.template.context_processors.static',
                'django.template.context_processors.tz',
                'django.contrib.messages.context_processors.messages',
            ],
            'loaders': [
                # insert your TEMPLATE_LOADERS here
            ]
        },
    },
]

Кроме того, вам следует заменить django.core.context_processors на django.template.context_processors в именах обработчиков контекста.

Если ваш модуль настроек определяет ALLOWED_INCLUDE_ROOTS или TEMPLATE_STRING_IF_INVALID, включите их значения под ключами 'allowed_include_roots' и 'string_if_invalid' в словаре 'OPTIONS'.

Если он устанавливает TEMPLATE_DEBUG на значение, отличное от DEBUG, включите это значение под ключом 'debug' в 'OPTIONS'.

После определения TEMPLATES, вы можете безопасно удалить ALLOWED_INCLUDE_ROOTS, TEMPLATE_CONTEXT_PROCESSORS, TEMPLATE_DEBUG, TEMPLATE_DIRS, TEMPLATE_LOADERS, и TEMPLATE_STRING_IF_INVALID.

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

django.template.loader

get_template() и select_template()

В Django 1.8 get_template() и select_template() возвращают зависящий от бэкенда Template вместо django.template.Template.

Например, если get_template() загружает шаблон с DjangoTemplates бэкендом, то он возвращает django.template.backends.django.Template.

Объекты Template должны предоставить метод render() с сигнатурой, которая немного отличается от render() языка шаблонов Django.

Вместо:

from django.template import Context
from django.template.loader import get_template

template = get_template('hello.html')
html = template.render(Context({'name': 'world'}))

Вы должны написать:

from django.template.loader import get_template

template = get_template('hello.html')
html = template.render({'name': 'world'})

И вместо:

from django.template import RequestContext
from django.template.loader import get_template

template = get_template('hello.html')
html = template.render(RequestContext(request, {'name': 'world'}))

Вы должны написать:

from django.template.loader import get_template

template = get_template('hello.html')
html = template.render({'name': 'world'}, request)

Передача Context или RequestContext все еще возможна при загрузке шаблона с помощью бэкенда DjangoTemplates, но это устаревшее поведение и не будет поддерживаться в Django 1.10.

Если вы загружаете шаблон во время рендеринга другого шаблона с помощью языка шаблонов Django и имеете доступ к текущему контексту, например, в методе render() тега шаблона, вы можете использовать текущий Engine напрямую. Вместо:

from django.template.loader import get_template
template = get_template('included.html')

Вы можете написать:

template = context.template.engine.get_template('included.html')

Это загрузит шаблон с текущим движком без запуска механизма множественных движков шаблонов, что обычно является желаемым поведением. В отличие от предыдущих решений, это возвращает django.template.Template, как get_template() использовалось в Django 1.7 и ранее, избегая всех проблем обратной совместимости.

get_template_from_string()

Приватный API get_template_from_string(template_code) был удален в Django 1.8, потому что у него не было способа выбрать движок для компиляции шаблона.

Доступны три альтернативы.

Если вы контролируете настройки проекта, вы можете использовать один из настроенных движков:

from django.template import engines

template = engines['django'].from_string(template_code)

Это возвращает объект, зависящий от бэкенда Template.

Для тривиальных шаблонов, которым не нужны обработчики контекста или что-либо еще, вы можете создать базовый движок и использовать его метод from_string():

from django.template import Engine

template = Engine().from_string(template_code)

Это возвращает django.template.Template, потому что Engine является частью API языка шаблонов Django. Механизм множественных движков шаблонов здесь не участвует.

Наконец, если у вас есть доступ к текущему контексту, вы можете использовать тот же трюк, что и выше:

template = context.template.engine.from_string(template_code)

Template()

В меньшей степени создание экземпляра шаблона с помощью Template(template_code) страдает той же проблемой, что и get_template_from_string().

Он все еще работает, когда настройка TEMPLATES определяет ровно один бэкенд DjangoTemplates, но подключаемые приложения не могут контролировать это требование.

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