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.
• После прохождения через 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()})