# Documentation Django 5.2.8

# `TemplateResponse` et `SimpleTemplateResponse`

Les objets `HttpResponse` standards sont des structures statiques. Ils disposent d’un bloc de contenu pré-rendu au moment de la construction de l’objet, et même si ce contenu peut être modifié, il ne l’est pas dans une forme permettant d’effectuer aisément des modifications.

Cependant, il peut parfois être avantageux de permettre à des décorateurs ou des intergiciels de modifier une réponse après sa construction par la vue. Par exemple, on peut vouloir modifier le gabarit utilisé ou ajouter des données supplémentaires dans le contexte.

Les objets `TemplateResponse` permettent justement de faire cela. Au contraire des objets `HttpResponse` basiques, les objets `TemplateResponse` conservent les informations de gabarit et de contexte fournis par la vue pour produire la réponse. Le résultat final de la réponse n’est produit qu’au dernier moment, plus tard dans le processus de réponse.

## Objets `SimpleTemplateResponse`

class SimpleTemplateResponse

### Attributs

SimpleTemplateResponse.template_name

  The name of the template to be rendered. Accepts a backend-dependent template object (such as those returned by `get_template()`), the name of a template, or a list of template names.

  Exemple : `['foo.html', 'chemin/vers/bar.html']`

SimpleTemplateResponse.context_data

  Les données de contexte à utiliser lors de la production du gabarit. Cela doit être un `dict`.

  Exemple : `{'foo': 123}`

SimpleTemplateResponse.rendered_content

  La valeur produite actuellement du contenu de la réponse, en utilisant le gabarit en cours et les données de contexte.

SimpleTemplateResponse.is_rendered

  Une valeur booléenne indiquant si le contenu de la réponse a été produit.

### Méthodes

SimpleTemplateResponse.__init__(template, context=None, content_type=None, status=None, charset=None, using=None, headers=None)

  Crée une instance d’objet `SimpleTemplateResponse` avec le gabarit, le contexte, le type de contenu, le statut HTTP et le jeu de caractères indiqués.

  `template`

    A backend-dependent template object (such as those returned by `get_template()`), the name of a template, or a list of template names.

  `context`

    Un `dictionnaire` de valeurs à ajouter au contexte du gabarit. Par défaut, ce dictionnaire est vide.

  `content_type`

    La valeur incluse dans l’en-tête HTTP `Content-Type`, y compris le type MIME et le codage de caractères. Si `content_type` est indiqué, sa valeur est utilisée. Sinon, c’est `'text/html'` qui est utilisé.

  `status`

    Le code de statut HTTP de la réponse.

  `charset`

    Le jeu de caractères dans lequel la réponse sera codée. S’il n’est pas fourni, il sera extrait à partir de `content_type`, et si ce n’est pas fructueux, c’est le réglage `DEFAULT_CHARSET` qui est utilisé.

  `using`

    Le nom `NAME` d’un moteur de gabarit à utiliser pour charger le gabarit.

  `headers`

    Un `dict` d’en-têtes HTTP à ajouter à la réponse.

SimpleTemplateResponse.resolve_context(context)

  Prétraite les données de contexte qui seront utilisées pour la production d’un gabarit. Accepte un `dict` de données de contexte. Par défaut, renvoie le même `dict`.

  Surchargez cette méthode afin de personnaliser le contexte.

SimpleTemplateResponse.resolve_template(template)

  Resolves the template instance to use for rendering. Accepts a backend-dependent template object (such as those returned by `get_template()`), the name of a template, or a list of template names.

  Renvoie l’instance d’objet gabarit, dépendante du moteur, qu’il faut afficher.

  Surchargez cette méthode afin de personnaliser le chargement des gabarits.

SimpleTemplateResponse.add_post_render_callback()

  Ajoute une fonction de rappel qui sera appelée après la fin du rendu. Ce point d’entrée peut être utilisé pour reporter certaines opérations de traitement (comme le cache) à la fin de l’étape de rendu.

  Si l’objet `SimpleTemplateResponse` a déjà été rendu, la fonction de rappel est immédiatement appelée.

  Lorsqu’elles sont appelées, les fonctions de rappel reçoivent un seul paramètre, l’instance `SimpleTemplateResponse` rendue.

  Si la fonction de rappel renvoie une valeur autre que `None`, cette valeur est utilisée comme réponse en lieu et place de l’objet réponse original (et sera transmise à la fonction de rappel « post-rendu » suivante, etc.).

SimpleTemplateResponse.render()

  Définit `response.content` au résultat obtenu par `SimpleTemplateResponse.rendered_content`, exécute toutes les fonctions de rappel « post-rendu » et renvoie l’objet réponse résultant.

  `render()` n’a d’effet que lors de son premier appel. Pour les appels suivants, elle renvoie le résultat obtenu lors du premier appel.

## Objets `TemplateResponse`

class TemplateResponse

  `TemplateResponse` est une sous-classe de `SimpleTemplateResponse` conscient de la requête `HttpRequest` en cours.

### Méthodes

TemplateResponse.__init__(request, template, context=None, content_type=None, status=None, charset=None, using=None, headers=None)

  Crée une instance d’objet `TemplateResponse` avec la requête, le gabarit, le contexte, le type de contenu, le statut HTTP et le jeu de caractères indiqués.

  `request`

    Une instance `HttpRequest`.

  `template`

    A backend-dependent template object (such as those returned by `get_template()`), the name of a template, or a list of template names.

  `context`

    Un `dictionnaire` de valeurs à ajouter au contexte du gabarit. Par défaut, ce dictionnaire est vide.

  `content_type`

    La valeur incluse dans l’en-tête HTTP `Content-Type`, y compris le type MIME et le codage de caractères. Si `content_type` est indiqué, sa valeur est utilisée. Sinon, c’est `'text/html'` qui est utilisé.

  `status`

    Le code de statut HTTP de la réponse.

  `charset`

    Le jeu de caractères dans lequel la réponse sera codée. S’il n’est pas fourni, il sera extrait à partir de `content_type`, et si ce n’est pas fructueux, c’est le réglage `DEFAULT_CHARSET` qui est utilisé.

  `using`

    Le nom `NAME` d’un moteur de gabarit à utiliser pour charger le gabarit.

  `headers`

    Un `dict` d’en-têtes HTTP à ajouter à la réponse.

## Le processus de rendu

Avant qu’une instance `TemplateResponse` puisse être renvoyée au client, elle doit être rendue. Le processus de rendu se saisit de la représentation intermédiaire du gabarit et du contexte, et s’en sert pour produire le flux binaire final qui sera envoyé au client.

Trois circonstances provoquent le rendu d’un objet `TemplateResponse`:

- When the `TemplateResponse` instance is explicitly rendered, using the `SimpleTemplateResponse.render()` method.

- Lorsque le contenu de la réponse est défini explicitement en attribuant une valeur à `response.content`.

- Après avoir traversé l’intergiciel de réponse de gabarit, mais avant de passer par l’intergiciel de réponse.

Un objet `TemplateResponse` peut être rendu une seule fois. Le premier appel à `SimpleTemplateResponse.render()` définit le contenu de la réponse ; les appels de rendu suivants ne modifient pas le contenu de la réponse.

Cependant, lorsque `response.content` reçoit explicitement une valeur, la modification est toujours appliquée. Si vous souhaitez forcer le contenu à être rendu à nouveau, vous pouvez ré-évaluer le contenu à produire et attribuer manuellement ce contenu à la réponse :

    # 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

### Fonctions de rappel « post-rendu »

Certaines opérations (comme la mise en cache) ne peuvent pas opérer sur un gabarit non rendu. Elles doivent agir sur une réponse dont le rendu est complet et terminé.

Si vous utilisez un intergiciel, c’est possible de le faire. Les intergiciels offrent de multiples possibilités de traiter une réponse à la sortie d’une vue. Si vous placez une certaine logique dans l’intergiciel de réponse, elle s’exécutera à coup sûr après la phase de rendu du gabarit.

Cependant, si vous utilisez un décorateur, une telle possibilité n’existe pas. Toute logique placée dans un décorateur est traitée immédiatement.

Pour compenser cela (et d’autres cas d’utilisation similaires), `TemplateResponse` vous permet d’inscrire des fonctions de rappel qui seront invoquées après la fin du rendu. En utilisant ces fonctions de rappel, vous pouvez reporter un traitement critique à un stade où vous êtes certain que le contenu rendu sera disponible.

Pour définir une fonction de rappel « post-rendu », définissez une fonction acceptant un seul paramètre (`response`) et d’inscrire cette fonction auprès de la réponse de gabarit :

    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()` sera invoquée après que `mytemplate.html` aura été rendu et recevra en paramètre l’instance `TemplateResponse` dont le rendu sera terminé.

Si le gabarit a déjà été rendu, la fonction de rappel est immédiatement appelée.

## Utilisation de `TemplateResponse` et de `SimpleTemplateResponse`

A `TemplateResponse` object can be used anywhere that a normal `django.http.HttpResponse` can be used. It can also be used as an alternative to calling `render()`.

Par exemple, la vue suivante renvoie un objet `TemplateResponse` avec un gabarit et un contexte contenant un jeu de requête :

    from django.template.response import TemplateResponse

    def blog_index(request):
        return TemplateResponse(
            request, "entry_list.html", {"entries": Entry.objects.all()}
        )