Ticket #14855: template-respose-rest.diff

File template-respose-rest.diff, 9.2 KB (added by Adam Vandenberg, 14 years ago)

  • docs/ref/template-response.txt 

    diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt
index 09bcd16..4332e6e 100644
    a b TemplateResponse and SimpleTemplateResponse  
    77.. module:: django.template.response
    88   :synopsis: Classes dealing with lazy-rendered HTTP responses.
    99
    10 Standard HttpResponse objects are static structures. They are provided
    11 with a block of pre-rendered content at time of construction, and
    12 while that content can be modified, it isn't in a form that makes it
    13 easy to perform modifications.
     10Standard :class:`~django.http.HttpResponse` objects are static structures.
     11They are provided with a block of pre-rendered content at time of
     12construction, and while that content can be modified, it isn't in a form that
     13makes it easy to perform modifications.
    1414
    1515However, it can sometimes be beneficial to allow decorators or
    1616middleware to modify a response *after* it has been constructed by the
    … … view. For example, you may want to change the template that is used,  
    1818or put additional data into the context.
    1919
    2020TemplateResponse provides a way to do just that. Unlike basic
    21 HttpResponse objects, TemplateResponse objects retain the details of
    22 the template and context that was provided by the view to compute the
    23 response. The final output of the response is not computed until
     21:class:`~django.http.HttpResponse` objects, TemplateResponse objects retain
     22the details of the template and context that was provided by the view to
     23compute the response. The final output of the response is not computed until
    2424it is needed, later in the response process.
    2525
    26 TemplateResponse objects
    27 ========================
     26SimpleTemplateResponse objects
     27==============================
    2828
    2929.. class:: SimpleTemplateResponse()
    3030
    … … Attributes  
    3333
    3434.. attribute:: SimpleTemplateResponse.template_name
    3535
    36     The name of the template to be rendered. Accepts
    37     :class:`django.template.Template` object, path to template or list
    38     of paths.
     36    The name of the template to be rendered. Accepts a
     37    :class:`~django.template.Template` object, a path to a template or list
     38    of template paths.
    3939
    4040    Example: ``['foo.html', 'path/to/bar.html']``
    4141
    … … Attributes  
    4646
    4747    Example: ``{'foo': 123}``
    4848
    49 .. attr:: SimpleTemplateResponse.rendered_content:
     49.. attribute:: SimpleTemplateResponse.rendered_content
    5050
    5151    The current rendered value of the response content, using the current
    5252    template and context data.
    5353
    54 .. attr:: SimpleTemplateResponse.is_rendered:
     54.. attribute:: SimpleTemplateResponse.is_rendered
    5555
    5656    A boolean indicating whether the response content has been rendered.
    5757
    … … Methods  
    6161
    6262.. method:: SimpleTemplateResponse.__init__(template, context=None, mimetype=None, status=None, content_type=None)
    6363
    64     Instantiates an
     64    Instantiates a
    6565    :class:`~django.template.response.SimpleTemplateResponse` object
    6666    with the given template, context, MIME type and HTTP status.
    6767
    68     ``template`` is a full name of a template, or a sequence of
    69     template names. :class:`django.template.Template` instances can
    70     also be used.
     68    ``template``
     69        The full name of a template, or a sequence of template names.
     70        :class:`~django.template.Template` instances can also be used.
    7171
    72     ``context`` is a dictionary of values to add to the template
    73     context. By default, this is an empty dictionary.
    74     :class:`~django.template.Context` objects are also accepted as
    75     ``context`` values.
     72    ``context``
     73        A dictionary of values to add to the template context. By default,
     74        this is an empty dictionary. :class:`~django.template.Context` objects
     75        are also accepted as ``context`` values.
    7676
    77     ``status`` is the HTTP Status code for the response.
     77    ``status``
     78        The HTTP Status code for the response.
    7879
    79     ``content_type`` is an alias for ``mimetype``. Historically, this
    80     parameter was only called ``mimetype``, but since this is actually
    81     the value included in the HTTP ``Content-Type`` header, it can
    82     also include the character set encoding, which makes it more than
    83     just a MIME type specification. If ``mimetype`` is specified (not
    84     ``None``), that value is used. Otherwise, ``content_type`` is
    85     used. If neither is given, the ``DEFAULT_CONTENT_TYPE`` setting is
    86     used.
     80    ``content_type``
     81        An alias for ``mimetype``. Historically, this parameter was only called
     82        ``mimetype``, but since this is actually the value included in the HTTP
     83        ``Content-Type`` header, it can also include the character set encoding,
     84        which makes it more than just a MIME type specification. If ``mimetype``
     85        is specified (not ``None``), that value is used. Otherwise,
     86        ``content_type`` is used. If neither is given,
     87        :setting:`DEFAULT_CONTENT_TYPE` is used.
    8788
    8889
    8990.. method:: SimpleTemplateResponse.resolve_context(context)
    … … Methods  
    115116    the result obtained from the first call.
    116117
    117118
     119TemplateResponse objects
     120========================
     121
    118122.. class:: TemplateResponse()
    119123
    120    TemplateResponse is a subclass of :class:`SimpleTemplateResponse
    121    <django.template.response.SimpleTemplateResponse>` that uses
    122    RequestContext instead of Context.
     124   TemplateResponse is a subclass of
     125   :class:`~django.template.response.SimpleTemplateResponse` that uses
     126   a :class:`~django.template.RequestContext` instead of
     127   a :class:`~django.template.Context`.
     128
     129Methods
     130-------
    123131
    124132.. method:: TemplateResponse.__init__(request, template, context=None, mimetype=None, status=None, content_type=None)
    125133
    126    Instantiates an ``TemplateResponse`` object with the given
    127    template, context, MIME type and HTTP status.
     134    Instantiates an ``TemplateResponse`` object with the given
     135    template, context, MIME type and HTTP status.
    128136
    129    ``request`` is a HttpRequest instance.
     137    ``request``
     138        An :class:`~django.http.HttpRequest` instance.
    130139
    131    ``template`` is a full name of a template to use or sequence of
    132    template names. :class:`django.template.Template` instances are
    133    also accepted.
     140    ``template``
     141        The full name of a template, or a sequence of template names.
     142        :class:`~django.template.Template` instances can also be used.
    134143
    135    ``context`` is a dictionary of values to add to the template
    136    context. By default, this is an empty dictionary; context objects
    137    are also accepted as ``context`` values.
     144    ``context``
     145        A dictionary of values to add to the template context. By default,
     146        this is an empty dictionary. :class:`~django.template.Context` objects
     147        are also accepted as ``context`` values.
    138148
    139    ``status`` is the HTTP Status code for the response.
     149    ``status``
     150        The HTTP Status code for the response.
    140151
    141    ``content_type`` is an alias for ``mimetype``. Historically, this
    142    parameter was only called ``mimetype``, but since this is actually
    143    the value included in the HTTP ``Content-Type`` header, it can also
    144    include the character set encoding, which makes it more than just a
    145    MIME type specification. If ``mimetype`` is specified (not
    146    ``None``), that value is used. Otherwise, ``content_type`` is used.
    147    If neither is given, the ``DEFAULT_CONTENT_TYPE`` setting is used.
     152    ``content_type``
     153        An alias for ``mimetype``. Historically, this parameter was only called
     154        ``mimetype``, but since this is actually the value included in the HTTP
     155        ``Content-Type`` header, it can also include the character set encoding,
     156        which makes it more than just a MIME type specification. If ``mimetype``
     157        is specified (not ``None``), that value is used. Otherwise,
     158        ``content_type`` is used. If neither is given,
     159        :setting:`DEFAULT_CONTENT_TYPE` is used.
    148160
    149161
    150162The rendering process
    151163=====================
    152164
    153 Before a :class:`TemplateResponse()` instance can be returned to the
    154 client, it must be rendered. The rendering process takes the
    155 intermediate representation of template and context, and turns it into
    156 the final byte stream that can be served to the client.
     165Before a :class:`~django.template.response.TemplateResponse` instance can be
     166returned to the client, it must be rendered. The rendering process takes the
     167intermediate representation of template and context, and turns it into the
     168final byte stream that can be served to the client.
    157169
    158170There are three circumstances under which a TemplateResponse will be
    159171rendered:
    … … rendered:  
    168180      passing through response middleware.
    169181
    170182A TemplateResponse can only be rendered once. The first call to
    171 :meth:`SimpleTemplateResponse.render()` sets the content of the
     183:meth:`SimpleTemplateResponse.render` sets the content of the
    172184response; subsequent rendering calls do not change the response
    173185content.
    174186
    … … Using TemplateResponse and SimpleTemplateResponse  
    199211
    200212A TemplateResponse object can be used anywhere that a normal
    201213HttpResponse can be used. It can also be used as an alternative to
    202 calling :method:`~django.shortcuts.render_to_response()`.
     214calling :meth:`~django.shortcuts.render_to_response()`.
    203215
    204216For example, the following simple view returns a
    205217:class:`TemplateResponse()` with a simple template, and a context
Back to Top