diff options
Diffstat (limited to 'docs/ref')
| -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 |
3 files changed, 226 insertions, 32 deletions
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()}) |