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 заголовков для добавления в ответ.

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 заголовков для добавления в ответ.

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

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

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

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

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

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

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

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

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

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

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

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 с шаблоном и контекстом, содержащим набор данных (queryset):

from django.template.response import TemplateResponse

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