diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.txt | 4 | ||||
| -rw-r--r-- | docs/ref/class-based-views.txt | 46 | ||||
| -rw-r--r-- | docs/ref/index.txt | 1 | ||||
| -rw-r--r-- | docs/ref/template-response.txt | 211 | ||||
| -rw-r--r-- | docs/releases/1.3.txt | 21 | ||||
| -rw-r--r-- | docs/topics/http/middleware.txt | 36 |
6 files changed, 285 insertions, 34 deletions
diff --git a/docs/index.txt b/docs/index.txt index 55e6cda983..632adc8da3 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -93,7 +93,9 @@ The view layer :doc:`View functions <topics/http/views>` | :doc:`Shortcuts <topics/http/shortcuts>` - * **Reference:** :doc:`Request/response objects <ref/request-response>` + * **Reference:** + :doc:`Request/response objects <ref/request-response>` | + :doc:`TemplateResponse objects <ref/template-response>` * **File uploads:** :doc:`Overview <topics/http/file-uploads>` | diff --git a/docs/ref/class-based-views.txt b/docs/ref/class-based-views.txt index 1b9a9f99ea..150ffff2e1 100644 --- a/docs/ref/class-based-views.txt +++ b/docs/ref/class-based-views.txt @@ -76,39 +76,25 @@ TemplateResponseMixin The path to the template to use when rendering the view. - .. method:: render_to_response(context) + .. attribute:: response_class - Returns a full composed HttpResponse instance, ready to be returned to - the user. + The response class to be returned by ``render_to_response`` method. + Default is + :class:`TemplateResponse <django.template.response.TemplateResponse>`. + The template and context of TemplateResponse instances can be + altered later (e.g. in + :ref:`template response middleware <template-response-middleware>`). - Calls :meth:`~TemplateResponseMixin.render_template()` to build the - content of the response, and - :meth:`~TemplateResponseMixin.get_response()` to construct the - :class:`~django.http.HttpResponse` object. + Create TemplateResponse subclass and pass set it to + ``template_response_class`` if you need custom template loading or + custom context object instantiation. - .. method:: get_response(content, **httpresponse_kwargs) + .. method:: render_to_response(context, **response_kwargs) - Constructs the :class:`~django.http.HttpResponse` object around the - given content. If any keyword arguments are provided, they will be - passed to the constructor of the :class:`~django.http.HttpResponse` - instance. + Returns a ``self.template_response_class`` instance. - .. method:: render_template(context) - - Calls :meth:`~TemplateResponseMixin.get_context_instance()` to obtain - the :class:`Context` instance to use for rendering, and calls - :meth:`TemplateReponseMixin.get_template()` to load the template that - will be used to render the final content. - - .. method:: get_context_instance(context) - - Turns the data dictionary ``context`` into an actual context instance - that can be used for rendering. - - By default, constructs a :class:`~django.template.RequestContext` - instance. - - .. method:: get_template() + If any keyword arguments are provided, they will be + passed to the constructor of the response instance. Calls :meth:`~TemplateResponseMixin.get_template_names()` to obtain the list of template names that will be searched looking for an existent @@ -123,10 +109,6 @@ TemplateResponseMixin default implementation will return a list containing :attr:`TemplateResponseMixin.template_name` (if it is specified). - .. method:: load_template(names) - - Loads and returns a template found by searching the list of ``names`` - for a match. Uses Django's default template loader. Single object mixins -------------------- diff --git a/docs/ref/index.txt b/docs/ref/index.txt index 7b59589e74..f544e3cd98 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -16,6 +16,7 @@ API Reference middleware models/index request-response + template-response settings signals templates/index diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt new file mode 100644 index 0000000000..09bcd16378 --- /dev/null +++ b/docs/ref/template-response.txt @@ -0,0 +1,211 @@ +=========================================== +TemplateResponse and SimpleTemplateResponse +=========================================== + +.. versionadded:: 1.3 + +.. module:: django.template.response + :synopsis: Classes dealing with lazy-rendered HTTP responses. + +Standard HttpResponse objects are static structures. They are provided +with a block of pre-rendered content at time of construction, and +while that content can be modified, it isn't in a form that makes it +easy to perform modifications. + +However, it can sometimes be beneficial to allow decorators or +middleware to modify a response *after* it has been constructed by the +view. For example, you may want to change the template that is used, +or put additional data into the context. + +TemplateResponse provides a way to do just that. Unlike basic +HttpResponse objects, TemplateResponse objects retain the details of +the template and context that was provided by the view to compute the +response. The final output of the response is not computed until +it is needed, later in the response process. + +TemplateResponse objects +======================== + +.. class:: SimpleTemplateResponse() + +Attributes +---------- + +.. attribute:: SimpleTemplateResponse.template_name + + The name of the template to be rendered. Accepts + :class:`django.template.Template` object, path to template or list + of paths. + + Example: ``['foo.html', 'path/to/bar.html']`` + +.. attribute:: SimpleTemplateResponse.context_data + + The context data to be used when rendering the template. It can be + a dictionary or a context object. + + Example: ``{'foo': 123}`` + +.. attr:: SimpleTemplateResponse.rendered_content: + + The current rendered value of the response content, using the current + template and context data. + +.. attr:: SimpleTemplateResponse.is_rendered: + + A boolean indicating whether the response content has been rendered. + + +Methods +------- + +.. method:: SimpleTemplateResponse.__init__(template, context=None, mimetype=None, status=None, content_type=None) + + Instantiates an + :class:`~django.template.response.SimpleTemplateResponse` object + with the given template, context, MIME type and HTTP status. + + ``template`` is a full name of a template, or a sequence of + template names. :class:`django.template.Template` instances can + also be used. + + ``context`` is a dictionary of values to add to the template + context. By default, this is an empty dictionary. + :class:`~django.template.Context` objects are also accepted as + ``context`` values. + + ``status`` is the HTTP Status code for the response. + + ``content_type`` is an alias for ``mimetype``. Historically, this + parameter was only called ``mimetype``, but since this is actually + the value included in the HTTP ``Content-Type`` header, it can + also include the character set encoding, which makes it more than + just a MIME type specification. If ``mimetype`` is specified (not + ``None``), that value is used. Otherwise, ``content_type`` is + used. If neither is given, the ``DEFAULT_CONTENT_TYPE`` setting is + used. + + +.. method:: SimpleTemplateResponse.resolve_context(context) + + Converts context data into a context instance that can be used for + rendering a template. Accepts a dictionary of context data or a + context object. Returns a :class:`~django.template.Context` + instance containing the provided data. + + Override this method in order to customize context instantiation. + +.. method:: SimpleTemplateResponse.resolve_template(template) + + Resolves the template instance to use for rendering. Accepts a + path of a template to use, or a sequence of template paths. + :class:`~django.template.Template` instances may also be provided. + Returns the :class:`~django.template.Template` instance to be + rendered. + + Override this method in order to customize template rendering. + +.. method:: SimpleTemplateResponse.render(): + + Sets :attr:`response.content` to the result obtained by + :attr:`SimpleTemplateResponse.rendered_content`. + + :meth:`~SimpleTemplateResponse.render()` will only have an effect + the first time it is called. On subsequent calls, it will return + the result obtained from the first call. + + +.. class:: TemplateResponse() + + TemplateResponse is a subclass of :class:`SimpleTemplateResponse + <django.template.response.SimpleTemplateResponse>` that uses + RequestContext instead of Context. + +.. method:: TemplateResponse.__init__(request, template, context=None, mimetype=None, status=None, content_type=None) + + Instantiates an ``TemplateResponse`` object with the given + template, context, MIME type and HTTP status. + + ``request`` is a HttpRequest instance. + + ``template`` is a full name of a template to use or sequence of + template names. :class:`django.template.Template` instances are + also accepted. + + ``context`` is a dictionary of values to add to the template + context. By default, this is an empty dictionary; context objects + are also accepted as ``context`` values. + + ``status`` is the HTTP Status code for the response. + + ``content_type`` is an alias for ``mimetype``. Historically, this + parameter was only called ``mimetype``, but since this is actually + the value included in the HTTP ``Content-Type`` header, it can also + include the character set encoding, which makes it more than just a + MIME type specification. If ``mimetype`` is specified (not + ``None``), that value is used. Otherwise, ``content_type`` is used. + If neither is given, the ``DEFAULT_CONTENT_TYPE`` setting is used. + + +The rendering process +===================== + +Before a :class:`TemplateResponse()` instance can be returned to the +client, it must be rendered. The rendering process takes the +intermediate representation of template and context, and turns it into +the final byte stream that can be served to the client. + +There are three circumstances under which a TemplateResponse will be +rendered: + + * When the TemplateResponse instance is explicitly rendered, using + the :meth:`SimpleTemplateResponse.render()` method. + + * When the content of the response is explicitly set by assigning + :attr:`response.content`. + + * After passing through template response middleware, but before + passing through response middleware. + +A TemplateResponse can only be rendered once. The first call to +:meth:`SimpleTemplateResponse.render()` sets the content of the +response; subsequent rendering calls do not change the response +content. + +However, when :attr:`response.content` is explicitly assigned, the +change is always applied. If you want to force the content to be +re-rendered, you can re-evaluate the rendered content, and assign +the content of the response manually:: + + # Set up a baked TemplateResponse + >>> t = TemplateResponse(request, 'original.html', {}) + >>> t.render() + >>> print t.content + Original content + + # Rebaking 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 + +Using TemplateResponse and SimpleTemplateResponse +================================================= + +A TemplateResponse object can be used anywhere that a normal +HttpResponse can be used. It can also be used as an alternative to +calling :method:`~django.shortcuts.render_to_response()`. + +For example, the following simple view returns a +:class:`TemplateResponse()` with a simple template, and a context +containing a queryset:: + + from django.template.response import TemplateResponse + + def blog_index(request): + return TemplateResponse(request, 'entry_list.html', {'entries': Entry.objects.all()}) diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 79ab8b3f16..0c2dedc481 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -133,6 +133,27 @@ can also add special translator comments in the source. For more information, see :ref:`contextual-markers` and :ref:`translator-comments`. +TemplateResponse +~~~~~~~~~~~~~~~~ + +It can sometimes be beneficial to allow decorators or middleware to +modify a response *after* it has been constructed by the view. For +example, you may want to change the template that is used, or put +additional data into the context. + +However, you can't (easily) modify the content of a basic +:class:`~django.http.HttpResponse` after it has been constructed. To +overcome this limitation, Django 1.3 adds a new +:class:`~django.template.TemplateResponse` class. Unlike basic +:class:`~django.http.HttpResponse` objects, +:class:`~django.template.TemplateResponse` objects retain the details +of the template and context that was provided by the view to compute +the response. The final output of the response is not computed until +it is needed, later in the response process. + +For more details, see the :ref:`documentation </ref/template-response>` +on the :class:`~django.template.TemplateResponse` class. + Everything else ~~~~~~~~~~~~~~~ diff --git a/docs/topics/http/middleware.txt b/docs/topics/http/middleware.txt index d376c6b1e0..c03eb155d6 100644 --- a/docs/topics/http/middleware.txt +++ b/docs/topics/http/middleware.txt @@ -97,6 +97,39 @@ calling ANY other request, view or exception middleware, or the appropriate view; it'll return that :class:`~django.http.HttpResponse`. Response middleware is always called on every response. +.. _template-response-middleware: + +``process_template_response`` +----------------------------- + +.. versionadded:: 1.3 + +.. method:: process_template_response(self, request, response) + +``request`` is an :class:`~django.http.HttpRequest` object. ``response`` is the +:class:`~django.template.response.SimpleTemplateResponse` subclass (e.g. +:class:`~django.template.response.TemplateResponse`) object returned by a +Django view. + +``process_template_response()`` must return an +:class:`~django.template.response.SimpleTemplateResponse` (or it's subclass) +object. It could alter the given ``response`` by changing +``response.template_name`` and ``response.template_context``, or it could +create and return a brand-new +:class:`~django.template.response.SimpleTemplateResponse` (or it's subclass) +instance. + +``process_template_response()`` will only be called if the response +instance has a ``render()`` method, indicating that it is a +:class:`~django.template.response.TemplateResponse`. + +You don't need to explicitly render responses -- responses will be +automatically rendered once all template response middleware has been +called. + +Middleware are run in reverse order during the response phase, which +includes process_template_response. + .. _response-middleware: ``process_response`` @@ -120,6 +153,7 @@ an earlier middleware method returned an :class:`~django.http.HttpResponse` classes are applied in reverse order, from the bottom up. This means classes defined at the end of :setting:`MIDDLEWARE_CLASSES` will be run first. + .. _exception-middleware: ``process_exception`` @@ -137,7 +171,7 @@ Django calls ``process_exception()`` when a view raises an exception. the browser. Otherwise, default exception handling kicks in. Again, middleware are run in reverse order during the response phase, which -includes ``process_exception``. If an exception middleware return a response, +includes ``process_exception``. If an exception middleware returns a response, the middleware classes above that middleware will not be called at all. ``__init__`` |