--- title: "Gabarits" version: 3.0 locale: fr source: https://docs.djangoproject.com/fr/3.0/topics/templates/ canonical: https://djangodocs.dev/fr/3.0/topics/templates/ --- # Gabarits Par sa nature liée au Web, Django a besoin d’un procédé agile de génération dynamique de HTML. L’approche la plus couramment utilisée est de se baser sur des gabarits. Un gabarit contient la partie statique du résultat HTML souhaité ainsi qu’une certaine syntaxe particulière définissant comment insérer le contenu dynamique. Pour un exemple pratique de création de pages HTML avec des gabarits, consultez la [partie 3 du tutoriel](/fr/3.0/intro/tutorial03/). Un projet Django peut être configuré avec un ou plusieurs moteurs de gabarit (ou même aucun si vous n’utilisez pas de gabarit). Django est livré avec des moteurs intégrés pour son propre système de gabarits, appelé de manière originale le langage de gabarits de Django (DTL), ainsi que pour l’alternative répandue [Jinja2](http://jinja.pocoo.org/). Des moteurs pour d’autres langages de gabarits peuvent être mis à disposition par des applications tierces. Django définit une API standard pour le chargement et la production de gabarits de manière indépendante du moteur utilisé. Le chargement consiste à trouver le gabarit correspondant à un identifiant donné et à le pré-traiter, ce qui revient généralement à le compiler dans une représentation en mémoire. La production consiste à interpoler le gabarit en fonction de données de contexte et à renvoyer le texte résultant. Le [langage de gabarits de Django](/fr/3.0/ref/templates/language/) est le système de gabarits propre à Django. Jusqu’à Django 1.8, il s’agissait de la seule option disponible. C’est une bonne bibliothèque de gabarit, même si son approche est parfois un peu rigide et présente quelques particularités. SI vous n’avez pas de motivation précise pour choisir un moteur différent, nous vous recommandons de travailler avec ce langage, à plus forte raison si vous écrivez une application réutilisable et que vous pensez distribuer des gabarits. Les applications contribuées de Django qui comprennent des gabarits, telle que [django.contrib.admin](/fr/3.0/ref/contrib/admin/), utilisent le moteur de Django. Pour des raisons historiques, la prise en charge générique des moteurs de gabarit et l’implémentation du langage de gabarit de Django se trouvent tous deux dans l’espace de noms `django.template`. > **Warning** > > Le système des gabarits n’est pas protégé contre les rédacteurs de gabarits non fiables. Par exemple, un site ne devrait pas permettre à ses utilisateurs d’écrire leurs propres gabarits, car les gabarits permettent d’effectuer des actions telles que des attaques XSS et d’accéder à des propriétés de variables de gabarits qui peuvent contenir des informations sensibles. ## Prise en charge des moteurs de gabarit ### Configuration Les moteurs de gabarit sont configurés dans le réglage [`TEMPLATES`](/fr/3.0/ref/settings/#std-setting-TEMPLATES). Il s’agit d’une liste de configurations, une par moteur. La valeur par défaut est vide. Le fichier `settings.py` généré par la commande [`startproject`](/fr/3.0/ref/django-admin/#django-admin-startproject) définit une valeur plus utile : ``` TEMPLATES = [ { 'BACKEND': 'django.template.backends.django.DjangoTemplates', 'DIRS': [], 'APP_DIRS': True, 'OPTIONS': { # ... some options here ... }, }, ] ``` [`BACKEND`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-BACKEND) est un chemin Python pointé vers ue classe de moteur de gabarit implémentant l’API de moteur de gabarit de Django. Les moteurs intégrés sont [`django.template.backends.django.DjangoTemplates`](#django.template.backends.django.DjangoTemplates) et [`django.template.backends.jinja2.Jinja2`](#django.template.backends.jinja2.Jinja2). Comme la plupart des moteurs chargent des gabarits à partir de fichiers, la configuration de chaque moteur contient au premier niveau deux réglages courants : - [`DIRS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-DIRS) définit une liste de répertoires dans lesquels le moteur recherche des fichiers sources de gabarits, dans l’ordre de leur recherche. - [`APP_DIRS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-APP_DIRS) indique si le moteur doit rechercher les gabarits dans les applications installées. Chaque moteur définit un nom conventionnel à attribuer au sous-répertoire des applications où ses gabarits devraient se trouver. Même si ce n’est pas fréquent, il est possible de configurer plusieurs instances d’un même moteur avec des options différentes. Dans ce cas, il est nécessaire de définir un nom [`NAME`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-NAME) unique pour chaque moteur. [`OPTIONS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-OPTIONS) contient des réglages spécifiques au moteur. ### Utilisation Le module `django.template.loader` définit deux fonctions pour charger des gabarits. #### `get_template(template_name, using=None)` Cette fonction charge le gabarit ayant le nom donné et renvoie un objet `Template`. Le type exact de la valeur renvoyée dépend du moteur qui a chargé le gabarit. Chaque moteur possède sa propre classe `Template`. `get_template()` essaie avec chaque moteur de gabarit dans l’ordre jusqu’à ce que l’un d’eux réussisse. Si le gabarit n’est pas trouvé, une exception [`TemplateDoesNotExist`](#django.template.TemplateDoesNotExist) est générée. Si le gabarit est trouvé mais contient une syntaxe non valable, une exception [`TemplateSyntaxError`](#django.template.TemplateSyntaxError) est générée. La façon dont les gabarits sont recherchés et chargés dépend de chaque moteur et de sa configuration. Si vous souhaitez restreindre la recherche à un moteur de gabarit particulier, passez le nom [`NAME`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-NAME) du moteur dans le paramètre `using`. #### `select_template(template_name_list, using=None)` `select_template()` est semblable à `get_template()`, sauf qu’il accepte une liste de noms de gabarits. Il essaie chaque nom dans l’ordre et renvoie le premier gabarit existant. Si le chargement d’un gabarit échoue, les deux exceptions suivantes définies dans `django.template` peuvent être générées : #### `exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)` Cette exception est générée lorsqu’aucun gabarit n’a pu être trouvé. Elle accepte les paramètres facultatifs suivants pour remplir le [gabarit postmortem](#template-postmortem) sur la page de débogage : **`backend`** L’instance de moteur de gabarit dans lequel l’exception s’est produite. **`tried`** Une liste de sources qui ont été parcourues pour la recherche du gabarit. Elle se trouve sous la forme d’une liste de tuples contenant `(origine, statut)`, où `origine` est un objet de [type origine](#template-origin-api) et `statut` est une chaîne contenant la raison expliquant l’absence du gabarit. **`chain`** Une liste d’exceptions intermédiaires [`TemplateDoesNotExist`](#django.template.TemplateDoesNotExist) générées durant le chargement du gabarit. Ceci est exploité par des fonctions comme [`get_template()`](#django.template.loader.get_template), qui essaient de charger un gabarit donné depuis plusieurs moteurs. #### `exception TemplateSyntaxError(msg)` Cette exception est générée lorsqu’un gabarit a été trouvé, mais qu’il contient des erreurs. Les objets `Template` renvoyés par `get_template()` et `select_template()` doivent fournir une méthode `render()` ayant la signature suivante : #### `Template.render(context=None, request=None)` Produit ce gabarit en fonction du contexte donné. Si `context` est fourni, il doit s’agir d’un [`dict`](https://docs.python.org/3/library/stdtypes.html#dict). S’il n’est pas fourni, le moteur va produire le gabarit avec un contexte vide. Si `request` est fourni, il doit s’agir d’un objet [`HttpRequest`](/fr/3.0/ref/request-response/#django.http.HttpRequest). Le moteur doit se charger ensuite de le rendre disponible, ainsi que le jeton CSRF, dans le gabarit. La manière de le faire dépend de chaque moteur. Voici un exemple de l’algorithme de recherche. Pour cet exemple, le réglage [`TEMPLATES`](/fr/3.0/ref/settings/#std-setting-TEMPLATES) est : ``` TEMPLATES = [ { 'BACKEND': 'django.template.backends.django.DjangoTemplates', 'DIRS': [ '/home/html/example.com', '/home/html/default', ], }, { 'BACKEND': 'django.template.backends.jinja2.Jinja2', 'DIRS': [ '/home/html/jinja2', ], }, ] ``` Si vous appelez `get_template('story_detail.html')`, voici les fichiers que Django va rechercher, dans l’ordre : - `/home/html/example.com/story_detail.html` (moteur `'django'`) - `/home/html/default/story_detail.html` (moteur `'django'`) - `/home/html/jinja2/story_detail.html` (moteur `'jinja2'`) Si vous appelez `select_template(['story_253_detail.html', 'story_detail.html'])`, voici ce que Django va rechercher : - `/home/html/example.com/story_253_detail.html` (moteur `'django'`) - `/home/html/default/story_253_detail.html` (moteur `'django'`) - `/home/html/jinja2/story_253_detail.html` (moteur `'jinja2'`) - `/home/html/example.com/story_detail.html` (moteur `'django'`) - `/home/html/default/story_detail.html` (moteur `'django'`) - `/home/html/jinja2/story_detail.html` (moteur `'jinja2'`) Lorsque Django trouve un gabarit existant, il stoppe sa recherche. > **Astuce** > > Vous pouvez utiliser [`select_template()`](#django.template.loader.select_template) pour une sélection agile des gabarits. Par exemple, si vous avez rédigé un article et que vous voulez pouvoir utiliser des gabarits spécifiques pour certains articles, utilisez quelque chose comme `select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])`. Cela vous permet d’utiliser un gabarit adapté à un article individuel, tout en se rabattant sur un gabarit standard pour les articles sans gabarit dédié. Il est possible – et préférable – d’organiser les gabarits dans des sous-répertoires de chaque répertoire contenant des gabarits. La convention est de créer un sous-répertoire par application Django, en y ajoutant d’autres sous-répertoires au besoin. Ce conseil est tout à votre avantage. Le placement de tous les gabarits au niveau racine d’un seul répertoire devient rapidement ingérable. Pour charger un gabarit se trouvant dans un sous-répertoire, utilisez la barre oblique, comme ceci : ``` get_template('news/story_detail.html') ``` Toujours avec le même réglage [`TEMPLATES`](/fr/3.0/ref/settings/#std-setting-TEMPLATES) que ci-dessus, cet exemple va tenter de charger les gabarits suivants : - `/home/html/example.com/news/story_detail.html` (moteur `'django'`) - `/home/html/default/news/story_detail.html` (moteur `'django'`) - `/home/html/jinja2/news/story_detail.html` (moteur `'jinja2'`) De plus, pour rationaliser l’aspect répétitif du chargement et de la production des gabarits, Django propose une fonction raccourci qui automatise le processus. #### `render_to_string(template_name, context=None, request=None, using=None)` `render_to_string()` charge un gabarit comme [`get_template()`](#django.template.loader.get_template) et appelle sa méthode `render()` immédiatement. Elle accepte les paramètres ci-après. **`template_name`** Le nom d’un gabarit à charger et à produire. S’il s’agit d’une liste de noms de gabarits, Django utilise [`select_template()`](#django.template.loader.select_template) au lieu de [`get_template()`](#django.template.loader.get_template) pour chercher le gabarit. **`context`** Un [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) à utiliser comme contexte de gabarit lors de la production. **`request`** Un objet [`HttpRequest`](/fr/3.0/ref/request-response/#django.http.HttpRequest) facultatif qui sera disponible durant le processus de rendu du gabarit. **`using`** Un nom [`NAME`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-NAME) de moteur de gabarit facultatif. La recherche de gabarit sera limitée à ce moteur. Exemple d’utilisation : ``` from django.template.loader import render_to_string rendered = render_to_string('my_template.html', {'foo': 'bar'}) ``` Voir aussi le raccourci [`render()`](/fr/3.0/topics/http/shortcuts/#django.shortcuts.render) qui appelle [`render_to_string()`](#django.template.loader.render_to_string) et fournit le résultat à un objet [`HttpResponse`](/fr/3.0/ref/request-response/#django.http.HttpResponse) prêt à être renvoyé depuis une vue. Finalement, vous pouvez utiliser directement des moteurs configurés : #### `engines` Les moteurs de gabarit sont disponibles dans `django.template.engines`: ``` from django.template import engines django_engine = engines['django'] template = django_engine.from_string("Hello {{ name }}!") ``` La clé de recherche, `'django'` dans cet exemple, correspond au réglage [`NAME`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-NAME) du moteur. ### Moteurs intégrés #### `class DjangoTemplates` Définissez [`BACKEND`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-BACKEND) à `'django.template.backends.django.DjangoTemplates'` pour configurer un moteur de gabarit de Django. Lorsque [`APP_DIRS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-APP_DIRS) vaut `True`, les moteurs `DjangoTemplates` cherchent les gabarits dans le sous-répertoire `templates` des applications installées. Ce nom générique a été conservé par rétrocompatibilité. Les moteurs `DjangoTemplates` acceptent les [`OPTIONS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-OPTIONS) suivantes : - `'autoescape'`: une valeur booléenne contrôlant si l’auto-échappement HTML est activé. Sa valeur par défaut est `True`. > **Warning** > > Ne la mettez à `False` que si vous produisez des gabarits non HTML ! - `'context_processors'`: une liste de chemins Python pointés vers des objets exécutables utilisés pour remplir le contexte lorsqu’un gabarit est produit avec une requête. Ces exécutables acceptent un objet requête comme paramètre et renvoient un dictionnaire d’éléments à fusionner dans le contexte. La valeur par défaut est une liste vide. Voir [`RequestContext`](/fr/3.0/ref/templates/api/#django.template.RequestContext) pour plus d’informations. - `'debug'`: une valeur booléenne qui active ou désactive le mode débogage des gabarits. Quand elle vaut `True`, une page d’erreur élaborée affiche un rapport détaillé lors de toute exception générée durant le rendu des gabarits. Ce rapport contient les extraits concernés du gabarit avec les bonnes lignes mises en évidence. La valeur par défaut correspond à la valeur du réglage [`DEBUG`](/fr/3.0/ref/settings/#std-setting-DEBUG). - `'loaders'`: une liste de chemins Python pointés vers des classes de chargeurs de gabarits. Chaque classe `Loader` sait comment importer les gabarits d’une source particulière. Il est possible d’indiquer des tuples au lieu de chaînes. Le premier élément du tuple correspond au nom de classe de `Loader` alors que les éléments suivants seront transmis à la classe `Loader` en vue de son initialisation. La valeur par défaut dépend des valeurs de [`DIRS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-DIRS) et de [`APP_DIRS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-APP_DIRS). Voir [Types de chargeurs](/fr/3.0/ref/templates/api/#template-loaders) pour les détails. - `'string_if_invalid'`: résultat, sous forme de chaîne de caractères, que le système des gabarits utilise pour remplacer le contenu de variables non valides (par ex. mal orthographiées). La valeur par défaut est une chaîne vide. Voir [Traitement des variables non valides](/fr/3.0/ref/templates/api/#invalid-template-variables) pour les détails. - `'file_charset'`: le jeu de caractères utilisé pour lire les fichiers de gabarits depuis le disque. Sa valeur par défaut est `'utf-8'`. - `'libraries'`: un dictionnaire d’étiquettes et de chemins Python pointés de modules de balises de gabarit à inscrire auprès du moteur de gabarit. Ceci peut être utilisé pour ajouter de nouvelles bibliothèques ou pour fournir des étiquettes alternatives à celles qui existent. Par exemple : ``` OPTIONS={ 'libraries': { 'myapp_tags': 'path.to.myapp.tags', 'admin.urls': 'django.contrib.admin.templatetags.admin_urls', }, } ``` Les bibliothèques peuvent être chargées en passant la clé de dictionnaire correspondante à la balise [`{% load %}`](/fr/3.0/ref/templates/builtins/#std-templatetag-load). - `'builtins'`: une liste de chemins Python pointés de modules de balises de gabarit à ajouter aux [modules intégrés](/fr/3.0/ref/templates/builtins/). Par exemple : ``` OPTIONS={ 'builtins': ['myapp.builtins'], } ``` Les balises et les filtres des bibliothèques intégrées peuvent être utilisés sans devoir d’abord faire appel à la balise [`{% load %}`](/fr/3.0/ref/templates/builtins/#std-templatetag-load). #### `class Jinja2` Nécessite que [Jinja2](http://jinja.pocoo.org/) soit installé : ```console $ python -m pip install Jinja2 ``` *Windows* ```doscon ...\> py -m pip install Jinja2 ``` Définissez [`BACKEND`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-BACKEND) à `'django.template.backends.jinja2.Jinja2'` pour configurer un moteur de gabarit [Jinja2](http://jinja.pocoo.org/). Lorsque [`APP_DIRS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-APP_DIRS) vaut `True`, les moteurs `Jinja2` cherchent les gabarits dans le sous-répertoire `jinja2` des applications installées. L’élément le plus important dans [`OPTIONS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-OPTIONS) est `'environment'`. Il s’agit d’un chemin Python pointé vers un objet exécutable renvoyant un environnement Jinja2. La valeur par défaut est `'jinja2.Environment'`. Django appelle cet objet et transmet d’autres options en tant que paramètres nommés. De plus, ajoute des valeurs par défaut qui diffèrent de celles de Jinja2 pour quelques-unes : - `'autoescape'`: `True` - `'loader'`: un chargeur configuré pour [`DIRS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-DIRS) et [`APP_DIRS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-APP_DIRS) - `'auto_reload'`: `settings.DEBUG` - `'undefined'`: `DebugUndefined` si `settings.DEBUG` sinon `Undefined` Les moteurs `Jinja2` acceptent aussi les [`OPTIONS`](/fr/3.0/ref/settings/#std-setting-TEMPLATES-OPTIONS) suivantes : - `'context_processors'`: une liste de chemins Python pointés vers des objets exécutables utilisés pour remplir le contexte lorsqu’un gabarit est produit avec une requête. Ces exécutables acceptent un objet requête comme paramètre et renvoient un dictionnaire d’éléments à fusionner dans le contexte. La valeur par défaut est une liste vide. > **L’utilisation de processeurs de contexte avec les gabarits Jinja2 est déconseillée.** > > Les processeurs de contexte sont utiles avec les gabarits Django car ceux-ci ne permettent pas d’appeler des fonctions avec paramètres. Comme Jinja2 ne connaît pas cette restriction, il est recommandé de placer la fonction qui aurait été utilisée dans un processeur de contexte dans les variables globales à disposition du gabarit en utilisant `jinja2.Environment`, comme décrit ci-dessous. Vous pouvez alors appeler cette fonction dans le gabarit : > > ```jinja > {{ function(request) }} > ``` > > Certains processeurs de contexte des gabarits Django renvoient une valeur fixe. Pour les gabarits Jinja2, ce niveau d’indirection n’est pas nécessaire car il est possible d’ajouter des constantes directement dans `jinja2.Environment`. > > Le cas d’utilisation original pour l’ajout de processeurs de contexte avec Jinja2 impliquait : > > - La réalisation de calculs intensifs dépendant de la requête. > - La disponibilité du résultat dans chaque gabarit. > - L’utilisation du résultat plusieurs fois dans chaque gabarit. > > Tant que toutes ces conditions ne sont pas respectées, il est plus en accord avec les concepts de Jinja2 de passer une fonction au gabarit. La configuration par défaut est volontairement limitée au minimum. Si un gabarit est produit avec une requête (par ex. en utilisant [`render()`](/fr/3.0/topics/http/shortcuts/#django.shortcuts.render)), le moteur `Jinja2` ajoute les éléments globaux `request`, `csrf_input` et `csrf_token` au contexte. À part ça, ce moteur ne crée pas d’environnement adapté à Django. Il n’a pas connaissance des filtres et des balises de Django. Afin de pouvoir utiliser des API spécifiques à Django, vous devez les configurer dans l’environnement. Par exemple, vous pouvez créer `monproject/jinja2.py` avec ce contenu : ``` from django.templatetags.static import static from django.urls import reverse from jinja2 import Environment def environment(**options): env = Environment(**options) env.globals.update({ 'static': static, 'url': reverse, }) return env ``` et définir l’option `'environment'` à `'monproject.jinja2.environment'`. Dès lors, vous pouvez utiliser les structures suivantes dans les gabarits Jinja2 : ```html+jinja Company Logo Administration ``` Les concepts de balises et filtres existent aussi bien dans le langage de gabarit de Django que dans Jinja2, mais ils sont utilisés différemment. Comme Jinja2 prend en charge le passage de paramètres à des objets exécutables dans les gabarits, beaucoup de fonctionnalités qui nécessitent une balise de gabarit ou un filtre dans les gabarits Django peuvent être implémentées en appelant une fonction dans les gabarits Jinja2, comme l’exemple ci-dessus le montre. L’espace de noms global de Jinja2 élimine le besoin de processeurs de contexte de gabarit. Le langage de gabarit de Django ne possède pas d’équivalent aux tests Jinja2. ### Moteurs personnalisés Voici comment implémenter un moteur de gabarit personnalisé afin d’utiliser un autre système de gabarits. Un moteur de gabarit est une classe qui hérite de `django.template.backends.base.BaseEngine`. Elle doit implémenter get\_template()\` et, facultativement, `from_string()`. Voici un exemple d’une bibliothèque de gabarit fictive `foobar`: ``` from django.template import TemplateDoesNotExist, TemplateSyntaxError from django.template.backends.base import BaseEngine from django.template.backends.utils import csrf_input_lazy, csrf_token_lazy import foobar class FooBar(BaseEngine): # Name of the subdirectory containing the templates for this engine # inside an installed application. app_dirname = 'foobar' def __init__(self, params): params = params.copy() options = params.pop('OPTIONS').copy() super().__init__(params) self.engine = foobar.Engine(**options) def from_string(self, template_code): try: return Template(self.engine.from_string(template_code)) except foobar.TemplateCompilationFailed as exc: raise TemplateSyntaxError(exc.args) def get_template(self, template_name): try: return Template(self.engine.get_template(template_name)) except foobar.TemplateNotFound as exc: raise TemplateDoesNotExist(exc.args, backend=self) except foobar.TemplateCompilationFailed as exc: raise TemplateSyntaxError(exc.args) class Template: def __init__(self, template): self.template = template def render(self, context=None, request=None): if context is None: context = {} if request is not None: context['request'] = request context['csrf_input'] = csrf_input_lazy(request) context['csrf_token'] = csrf_token_lazy(request) return self.template.render(context) ``` Voir [DEP 182](https://github.com/django/deps/blob/master/final/0182-multiple-template-engines.rst) pour plus d’informations. ### Intégration du débogage pour les moteurs personnalisés La page de débogage de Django présente des points d’entrée pour fournir des informations détaillées lorsqu’une erreur de gabarit se produit. Les moteurs de gabarit personnalisés peuvent utiliser ces points d’entrée pour améliorer les informations d’erreur qui sont présentées aux utilisateurs. Les points d’entrée suivants sont disponibles : #### Gabarit postmortem Le gabarit postmortem apparaît lorsque [`TemplateDoesNotExist`](#django.template.TemplateDoesNotExist) est générée. Il présente la liste des moteurs et chargeurs de gabarit utilisés lors de la recherche du gabarit concerné. Par exemple, si deux moteurs Django sont configurés, le gabarit postmortem ressemble à ceci : ![](topics/_images/postmortem.png) Les moteurs personnalisés peuvent remplir le gabarit postmortem en passant les paramètres `backend` et `tried` lors de la génération de [`TemplateDoesNotExist`](#django.template.TemplateDoesNotExist). Les moteurs qui utilisent le gabarit postmortem [doivent indiquer une origine](#template-origin-api) sur l’objet de gabarit. #### Information de ligne contextuelle Si une erreur se produit pendant l’analyse et le rendu d’un gabarit, Django peut afficher la ligne à laquelle s’est produite l’erreur. Par exemple : ![](topics/_images/template-lines.png) Les moteurs personnalisés peuvent fournir cette information en définissant un attribut `template_debug` sur les exceptions générées pendant l’analyse et le rendu. Cet attribut est un [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) possédant les valeurs suivantes : - `'name'`: le nom du gabarit dans lequel l’exception s’est produite. - `'message'`: le message de l’exception. - `'source_lines'`: les lignes précédentes, suivantes ainsi que la ligne elle-même où s’est produite l’exception. C’est pour fournir du contexte, il ne faut donc pas inclure plus d’une vingtaine de lignes. - `'line'`: le numéro de ligne à laquelle s’est produite l’exception. - `'before'`: le contenu de la ligne ayant provoqué l’erreur, avant le symbole qui a produit l’erreur. - `'during'`: le symbole qui a généré l’erreur. - `'after'`: le contenu de la ligne ayant provoqué l’erreur, après le symbole qui a produit l’erreur. - `'total'`: le nombre de lignes dans `source_lines`. - `'top'`: le numéro de ligne où `source_lines` commence. - `'bottom'`: le numéro de ligne où `source_lines` se termine. Étant donné l’erreur de gabarit ci-dessus, `template_debug` ressemblerait à ceci : ``` { 'name': '/path/to/template.html', 'message': "Invalid block tag: 'syntax'", 'source_lines': [ (1, 'some\n'), (2, 'lines\n'), (3, 'before\n'), (4, 'Hello {% syntax error %} {{ world }}\n'), (5, 'some\n'), (6, 'lines\n'), (7, 'after\n'), (8, ''), ], 'line': 4, 'before': 'Hello ', 'during': '{% syntax error %}', 'after': ' {{ world }}\n', 'total': 9, 'bottom': 9, 'top': 1, } ``` #### API d’origine et intégration tierce Les gabarits Django possèdent un objet [`Origin`](/fr/3.0/ref/templates/api/#django.template.base.Origin) accessible par leur attribut `template.origin`. Ceci permet aux informations de débogage d’apparaître dans le [gabarit postmortem](#template-postmortem), de même que dans des bibliothèques tierces, telle que [Django Debug Toolbar](https://github.com/jazzband/django-debug-toolbar). Les moteurs personnalisés peuvent fournir leurs propres informations `template.origin` en créant un objet qui définit les attributs suivants : - `'name'`: le chemin complet vers le gabarit. - `'template_name'`: le chemin relatif vers le gabarit tel que transmis aux méthodes de chargement de gabarits. - `'loader_name'`: une chaîne facultative identifiant la fonction ou la classe utilisée pour charger le gabarit, par exemple `django.template.loaders.filesystem.Loader`. ## Le langage de gabarit de Django ### Syntaxe > **À propos de cette section** > > Il s’agit ici d’un aperçu de la syntaxe du langage de gabarit de Django. Pour plus de détails, voir la [référence de la syntaxe du langage](/fr/3.0/ref/templates/language/). Un gabarit Django est un document texte ou un chaîne Python, balisés à l’aide du langage de gabarit de Django. Certaines structures sont reconnues et interprétées par le moteur de gabarit. Les principales sont les variables et les balises. Un gabarit est produit avec un contexte. Le processus de production remplace les variables par leurs valeurs qui sont cherchées dans le contexte, et il exécute les balises. Tout le reste est affiché tel quel. La syntaxe du langage de gabarit de Django implique quatre structures. #### Variables Une variable affiche une valeur à partir du contexte, qui est un objet de type dictionnaire faisant correspondre des clés à des valeurs. Les variables sont entourées par `{{` et `}}` comme ceci : ```html+django My first name is {{ first_name }}. My last name is {{ last_name }}. ``` Avec un contexte `{'first_name': 'John', 'last_name': 'Doe'}`, ce gabarit produit : ```html+django My first name is John. My last name is Doe. ``` La consultation de dictionnaire, d’attribut et d’indice de liste est implémentée par une notation pointée : ```html+django {{ my_dict.key }} {{ my_object.attribute }} {{ my_list.0 }} ``` Si le contenu d’une variable s’avère être un objet exécutable, le système de gabarit l’appelle sans paramètre et utilise son résultat à la place de l’objet exécutable. #### Balises Les balises permettent d’appliquer une logique arbitraire dans le processus de rendu. Cette définition est volontairement vague. Par exemple, une balise peut produire du contenu, servir de structure de contrôle telle qu’une instruction « if » ou une boucle « for », extraire du contenu d’une base de données ou même de donner accès à d’autres balises de gabarit. Les balises sont entourées par `{%` et `%}`, comme ceci : ```html+django {% csrf_token %} ``` La plupart des balises acceptent des paramètres : ```html+django {% cycle 'odd' 'even' %} ``` Certaines balises exigent des balises d’introduction et de terminaison : ```html+django {% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %} ``` Une [référence des balises intégrés](/fr/3.0/ref/templates/builtins/#ref-templates-builtins-tags) est disponible tout comme des [instructions pour écrire des balises personnalisées](/fr/3.0/howto/custom-template-tags/#howto-writing-custom-template-tags). #### Filtres Les filtres transforment les valeurs de variables et les paramètres de balises. Ils ressemblent à ceci : ```html+django {{ django|title }} ``` Avec un contexte `{'django': 'the web framework for perfectionists with deadlines'}`, ce gabarit produit le résultat suivant : ```html+django The Web Framework For Perfectionists With Deadlines ``` Certains filtres acceptent un paramètre : ```html+django {{ my_date|date:"Y-m-d" }} ``` Une [référence des filtres intégrés](/fr/3.0/ref/templates/builtins/#ref-templates-builtins-filters) est disponible tout comme des [instructions pour écrire des filtres personnalisés](/fr/3.0/howto/custom-template-tags/#howto-writing-custom-template-filters). #### Commentaires Les commentaires ressemblent à ceci : ```html+django {# this won't be rendered #} ``` Une balise [`{% comment %}`](/fr/3.0/ref/templates/builtins/#std-templatetag-comment) autorise des commentaires sur plusieurs lignes. ### Composants > **À propos de cette section** > > Il s’agit ici d’un aperçu des API du langage de gabarit de Django. Pour plus de détails, voir la [référence des API](/fr/3.0/ref/templates/api/). #### Moteur [`django.template.Engine`](/fr/3.0/ref/templates/api/#django.template.Engine) encapsule une instance du système de gabarit de Django. La raison principale de créer directement une telle instance est d’utiliser le langage de gabarit de Django en dehors d’un projet Django. [`django.template.backends.django.DjangoTemplates`](#django.template.backends.django.DjangoTemplates) est un adaptateur léger autour de [`django.template.Engine`](/fr/3.0/ref/templates/api/#django.template.Engine) pour l’adapter à l’API de moteur de gabarit de Django. #### Gabarit [`django.template.Template`](/fr/3.0/ref/templates/api/#django.template.Template) représente un gabarit compilé. Les gabarits sont obtenus par [`Engine.get_template()`](/fr/3.0/ref/templates/api/#django.template.Engine.get_template) ou [`Engine.from_string()`](/fr/3.0/ref/templates/api/#django.template.Engine.from_string) De même, `django.template.backends.django.Template` est un adaptateur léger autour de [`django.template.Template`](/fr/3.0/ref/templates/api/#django.template.Template) pour l’adapter à l’API de gabarit commune. #### Contexte [`django.template.Context`](/fr/3.0/ref/templates/api/#django.template.Context) contient des métadonnées en plus des données de contexte. Il est transmis à [`Template.render()`](/fr/3.0/ref/templates/api/#django.template.Template.render) en vue de la production d’un gabarit. [`django.template.RequestContext`](/fr/3.0/ref/templates/api/#django.template.RequestContext) est une sous-classe de [`Context`](/fr/3.0/ref/templates/api/#django.template.Context) qui stocke la requête [`HttpRequest`](/fr/3.0/ref/request-response/#django.http.HttpRequest) en cours et exécute les processeurs de contexte de gabarit. L’API commune ne possède pas de concept équivalent. Les données de contexte sont transmises dans un simple [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) et la requête [`HttpRequest`](/fr/3.0/ref/request-response/#django.http.HttpRequest) en cours est transmise séparément si nécessaire. #### Chargeurs Les chargeurs de gabarits sont responsables de la découverte des gabarits, de leur chargement et du renvoi d’objets [`Template`](/fr/3.0/ref/templates/api/#django.template.Template). Django fournit plusieurs [chargeurs de gabarits intégrés](/fr/3.0/ref/templates/api/#template-loaders) et prend en charge des [chargeurs de gabarits personnalisés](/fr/3.0/ref/templates/api/#custom-template-loaders). #### Processeurs de contexte Les processeurs de contexte sont des fonctions qui reçoivent la requête [`HttpRequest`](/fr/3.0/ref/request-response/#django.http.HttpRequest) en cours comme paramètre et renvoient un [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) de données à ajouter au contexte de production. Leur utilisation principale est d’ajouter dans le contexte des données fréquemment utilisées partagées par tous les gabarits, sans devoir répéter le code correspondant dans chaque vue. Django fournit un bon nombre de [processeurs de contexte intégrés](/fr/3.0/ref/templates/api/#context-processors). Vous pouvez également implémenter vos propres processeurs de contexte.