TemplateResponse и SimpleTemplateResponse

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

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

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

SimpleTemplateResponse объекты

class SimpleTemplateResponse

Атрибуты

SimpleTemplateResponse.template_name

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

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

SimpleTemplateResponse.context_data

Данные контекста, которые будут использованы при рендеринге шаблона. Должно быть a 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

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

content_type

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

status

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

charset

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

using

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

headers

A 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

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

content_type

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

status

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

charset

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

using

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

headers

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

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

Перед тем, как экземпляр 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()}
    )