TemplateResponse и SimpleTemplateResponse

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

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

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

SimpleTemplateResponse объекты

class SimpleTemplateResponse [source]

Атрибуты

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) [source]

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

template

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

context

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

content_type

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

status

HTTP-код состояния ответа.

charset

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

using

NAME используемого движка шаблонов для загрузки шаблона.

SimpleTemplateResponse.resolve_context(context) [source]

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

Переопределите этот метод, чтобы настроить контекст.

SimpleTemplateResponse.resolve_template(template) [source]

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

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

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

SimpleTemplateResponse.add_post_render_callback() [source]

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

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

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

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

SimpleTemplateResponse.render() [source]

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

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

TemplateResponse объекты

class TemplateResponse [source]

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

Методы

TemplateResponse.__init__(request, template, context=None, content_type=None, status=None, charset=None, using=None) [source]

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

request

Экземпляр HttpRequest.

template

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

context

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

content_type

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

status

HTTP-код состояния ответа.

charset

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

using

NAME используемого движка шаблонов для загрузки шаблона.

Процесс отрисовки

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

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

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()})