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

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

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

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

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

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

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