TemplateResponse и SimpleTemplateResponse

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

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

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

SimpleTemplateResponse объекты

class SimpleTemplateResponse

Атрибуты

SimpleTemplateResponse.template_name

Имя шаблона для рендеринга. Принимает шаблон, зависящий от бэкэнда (например, такие, которые возвращаются get_template()), имя шаблона или список имён шаблонов.

Пример: ['foo.html', 'path/to/bar.html']

SimpleTemplateResponse.context_data

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

Пример: {'foo': 123}

SimpleTemplateResponse.rendered_content

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

SimpleTemplateResponse.is_rendered

Булево значение, указывающее, был ли рендер содержимого ответа.

Методы

SimpleTemplateResponse.__init__(template, context=None, content_type=None, status=None, charset=None, using=None, headers=None)

Инициализирует объект SimpleTemplateResponse заданным шаблоном, контекстом, типом содержимого, кодом HTTP-статуса и кодировкой.

template

Шаблон, зависящий от бэкэнда (например, такие, которые возвращаются get_template()), имя шаблона или список имён шаблонов.

context

dict значений для добавления в контекст шаблона. По умолчанию это пустой словарь.

content_type

Значение, включенное в заголовок HTTP Content-Type, включая спецификацию типа MIME и кодировку набора символов. Если content_type задано, то используется его значение. В противном случае используется 'text/html'.

status

Код HTTP-статуса ответа.

charset

Кодировка набора символов, в которой будет закодирован ответ. Если не указано, она будет извлечена из content_type, а если это не удастся, будет использоваться настройка DEFAULT_CHARSET.

using

Имя NAME движка шаблонов для загрузки шаблона.

headers

dict HTTP-заголовков для добавления к ответу.

Изменено в Django 3.2:

Добавлен параметр headers.

SimpleTemplateResponse.resolve_context(context)

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

Переопределите этот метод для настройки контекста.

SimpleTemplateResponse.resolve_template(template)

Решает экземпляр шаблона для использования при рендеринге. Принимает шаблон, зависящий от бэкэнда (например, такие, которые возвращаются get_template()), имя шаблона или список имён шаблонов.

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

Переопределите этот метод для настройки загрузки шаблона.

SimpleTemplateResponse.add_post_render_callback()

Добавляет обратный вызов, который будет вызван после рендеринга. Этот хук может использоваться для отсрочки определённых операций обработки (таких как кеширование) до завершения рендеринга.

Если SimpleTemplateResponse уже был отрисован, обратный вызов будет вызван немедленно.

При вызове обратные вызовы будут получать один аргумент — экземпляр отрисованного SimpleTemplateResponse.

Если обратный вызов возвращает значение, отличное от None, оно будет использоваться как ответ вместо исходного объекта ответа (и будет передано следующему обратным вызову после рендеринга и т. д.).

SimpleTemplateResponse.render()

Устанавливает response.content в результат, полученный из SimpleTemplateResponse.rendered_content, выполняет все обратные вызовы после рендеринга и возвращает полученный объект ответа.

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

TemplateResponse объекты

class TemplateResponse

TemplateResponse — подкласс SimpleTemplateResponse, который знает о текущем HttpRequest.

Методы

TemplateResponse.__init__(request, template, context=None, content_type=None, status=None, charset=None, using=None, headers=None)

Инициализирует объект TemplateResponse заданным запросом, шаблоном, контекстом, типом содержимого, кодом HTTP-статуса и кодировкой.

request

Экземпляр HttpRequest.

template

Шаблон, зависящий от бэкэнда (например, такие, которые возвращаются get_template()), имя шаблона или список имён шаблонов.

context

dict значений для добавления в контекст шаблона. По умолчанию это пустой словарь.

content_type

Значение, включенное в заголовок HTTP Content-Type, включая спецификацию типа MIME и кодировку набора символов. Если content_type задано, то используется его значение. В противном случае используется 'text/html'.

status

Код HTTP-статуса ответа.

charset

Кодировка набора символов, в которой будет закодирован ответ. Если не указано, она будет извлечена из content_type, а если это не удастся, будет использоваться настройка DEFAULT_CHARSET.

using

Имя NAME движка шаблонов для загрузки шаблона.

headers

dict HTTP-заголовков для добавления к ответу.

Изменено в Django 3.2:

Добавлен параметр headers.

Процесс рендеринга

Прежде чем экземпляр TemplateResponse может быть возвращён клиенту, он должен быть отрисован. Процесс рендеринга принимает промежуточное представление шаблона и контекста и преобразует его в конечный байтовый поток, который может быть передан клиенту.

Существует три случая, в которых TemplateResponse будет отрисован:

• Когда экземпляр TemplateResponse явно отрисовывается, используя метод SimpleTemplateResponse.render().
• Когда содержимое ответа явно устанавливается путём присвоения response.content.
• После прохождения через средний слой обработки шаблонов ответа, но перед прохождением через средний слой обработки ответов.

Экземпляр TemplateResponse может быть отрисован только один раз. Первый вызов метода SimpleTemplateResponse.render() устанавливает содержимое ответа; последующие вызовы рендеринга не изменяют содержимое ответа.

Однако, когда response.content явно присваивается, изменение всегда применяется. Если вы хотите принудительно перерисовать содержимое, вы можете повторно оценить отрисованное содержимое и вручную присвоить содержимое ответа:

# Set up a rendered TemplateResponse
>>> from django.template.response import TemplateResponse
>>> t = TemplateResponse(request, 'original.html', {})
>>> t.render()
>>> print(t.content)
Original content

# Re-rendering doesn't change content
>>> t.template_name = 'new.html'
>>> t.render()
>>> print(t.content)
Original content

# Assigning content does change, no render() call required
>>> t.content = t.rendered_content
>>> print(t.content)
New content

Обработчики после рендеринга

Некоторые операции — например, кэширование — не могут быть выполнены над неотрисованным шаблоном. Они должны быть выполнены над полностью завершённым и отрисованным ответом.

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

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

Чтобы компенсировать это (и любые другие аналогичные случаи), TemplateResponse позволяет регистрировать обработчики, которые будут вызваны после завершения рендеринга. Используя этот обработчик, вы можете отложить важную обработку до момента, когда можете гарантировать доступность отрисованного содержимого.

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

from django.template.response import TemplateResponse

def my_render_callback(response):
    # Do content-sensitive processing
    do_post_processing()

def my_view(request):
    # Create a response
    response = TemplateResponse(request, 'mytemplate.html', {})
    # Register the callback
    response.add_post_render_callback(my_render_callback)
    # Return the response
    return response

my_render_callback() будет вызван после того, как mytemplate.html будет отрисован, и получит экземпляр полностью отрисованного TemplateResponse в качестве аргумента.

Если шаблон уже отрисован, обработчик будет вызван немедленно.

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

Объект TemplateResponse может использоваться в любом месте, где можно использовать обычный django.http.HttpResponse. Он также может использоваться в качестве альтернативы вызову render().

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

from django.template.response import TemplateResponse

def blog_index(request):
    return TemplateResponse(request, 'entry_list.html', {'entries': Entry.objects.all()})