Ce document présente le système de gabarits de Django dans une perspective technique : son fonctionnement et ses possibilités d’extension. Si vous recherchez la référence de la syntaxe du langage, consultez Le langage de gabarit de Django.
\nIl présuppose une compréhension des gabarits, des contextes, des variables, des balises et du rendu des gabarits. Commencez par l’introduction au langage de gabarit de Django si ces concepts ne vous sont pas familiers.
\nL’utilisation du système de gabarits en Python est un processus à trois étapes :
\nVous configurez un moteur Engine.
Vous compilez le code du gabarit en un objet Template.
Vous produisez ce gabarit en fonction d’un Context.
Les projets Django se basent généralement sur l’API de haut niveau et indépendante du moteur pour chacune de ces étapes plutôt que d’employer l’API de bas niveau du système des gabarits :
\nPour chaque moteur DjangoTemplates du réglage TEMPLATES, Django crée une instance Engine. DjangoTemplates englobe Engine et l’adapte à l’API commune des moteurs de gabarits.
Le module django.template.loader fournit des fonctions telles que get_template() pour le chargement des gabarits. Elles renvoient un django.template.backends.django.Template qui adapte l’objet django.template.Template réel.
Le gabarit Template obtenu à l’étape précédente possède une méthode render() qui produit un contexte et éventuellement une requête dans un objet Context et délègue le rendu à l’objet Template sous-jacent.
Si vous utilisez le moteur DjangoTemplates, cette documentation n’est probablement pas celle que vous cherchez. Une instance de la classe Engine décrite ci-dessous est accessible en utilisant l’attribut engine du moteur, et toute valeur par défaut d’attribut mentionnée plus bas est remplacée par ce qui est transmis par DjangoTemplates.
Lors de la création d’une instance de Engine, tous les paramètres doivent être transmis sous forme de paramètres nommés :
dirs définit une liste de répertoires dans lesquels le moteur recherche des fichiers sources de gabarits. Cette liste est utilisée pour configurer filesystem.Loader.
La valeur par défaut est une liste vide.
\napp_dirs n’affecte que la valeur par défaut de loaders. Voir ci-dessous.
Sa valeur par défaut est False.
autoescape contrôle si l’auto-échappement HTML est activé.
Sa valeur par défaut est True.
context_processors est 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.
\nVoir RequestContext pour plus d’informations.
debug est une valeur booléenne qui active ou désactive le mode débogage des gabarits. Quand elle vaut True, le moteur de gabarit stocke des informations de débogage supplémentaires pouvant être utilisées pour afficher un rapport détaillé lors de toute exception générée durant le rendu des gabarits.
Sa valeur par défaut est False.
loaders est une liste de classes de chargeurs de gabarits, sous forme de chaînes. 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.
Sa valeur par défaut est une liste contenant :
\n'django.template.loaders.filesystem.Loader'
'django.template.loaders.app_directories.Loader' si et seulement si app_dirs vaut True.
Ces chargeurs sont enveloppés par django.template.loaders.cached.Loader.
Voir Types de chargeurs pour les détails.
\nstring_if_invalid est le 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).
Sa valeur par défaut est une chaîne vide.
\nVoir Traitement des variables non valides pour les détails.
\nfile_charset est 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 est utilisé pour ajouter de nouvelles bibliothèques ou pour fournir des étiquettes alternatives à celles qui existent. Par exemple :
Engine(\n libraries={\n "myapp_tags": "path.to.myapp.tags",\n "admin.urls": "django.contrib.admin.templatetags.admin_urls",\n },\n)\nLes bibliothèques peuvent être chargées en passant la clé de dictionnaire correspondante à la balise {% load %}.
'builtins': une liste de chemins Python pointés de modules de balises de gabarit à ajouter aux modules intégrés. Par exemple :
Engine(\n builtins=["myapp.builtins"],\n)\nLes balises et les filtres des bibliothèques intégrées peuvent être utilisés sans devoir d’abord faire appel à la balise {% load %}.
Renvoie le moteur Engine sous-jacent du premier moteur DjangoTemplates configuré. Génère ImproperlyConfigured si aucun moteur n’a été configuré.
C’est obligatoire pour préserver les API qui comptent sur un moteur configuré implicitement et globalement disponible. Toute autre utilisation est fortement découragée.
\nCompile le code du gabarit donné et renvoie un objet Template.
Charge un gabarit ayant le nom donné, le compile et renvoie un objet Template.
Comme get_template(), sauf qu’il accepte une liste de noms et renvoie le premier gabarit existant de la liste.
La manière recommandée de créer un Template est d’appeler les méthodes de fabrication du moteur Engine: get_template(), select_template() et from_string().
Dans un projet Django où le réglage TEMPLATES définit un moteur DjangoTemplates, il est possible d’instancier directement un objet Template. Si plus d’un moteur DjangoTemplates est défini, c’est le premier qui sera utilisé.
Cette classe se trouve dans django.template.Template. Le constructeur accepte un paramètre, le code brut du gabarit :
from django.template import Template\n\ntemplate = Template("My name is {{ my_name }}.")\nÀ partir du moment où vous avez un objet Template compilé, vous pouvez procéder au rendu d’un contexte. Vous pouvez réutiliser le même gabarit pour le produire à plusieurs reprises avec différents contextes.
Le constructeur de django.template.Context accepte un paramètre facultatif — un dictionnaire faisant correspondre des noms de variables à leurs valeurs.
Trois paramètres nommés facultatifs peuvent aussi être indiqués :
\nautoescape contrôle si l’auto-échappement HTML est activé.
Sa valeur par défaut est True.
use_l10n force la régionalisation sans tenir compte du comportement par défaut. Si défini à True, les nombres et les dates seront mises en forme en fonction de la langue active.
Sa valeur par défaut est None.
Voir Contrôle de la régionalisation dans les gabarits pour plus de détails.
\nuse_tz force la conversion des dates en temps local lors de leur production dans un gabarit. Si défini à True, toutes les dates seront affichées en utilisant le fuseau horaire local. La priorité est donc plus forte que USE_TZ.
Sa valeur par défaut est None.
Voir Affichage de fuseaux horaires conscients dans les gabarits pour plus de détails.
\nPour des exemples d’utilisation, voir Manipulation des objets Context ci-dessous.
\nAppelez la méthode render() de l’objet Template avec un Context qui doit « remplir » le gabarit :
>>> from django.template import Context, Template\n>>> template = Template("My name is {{ my_name }}.")\n\n>>> context = Context({"my_name": "Adrian"})\n>>> template.render(context)\n"My name is Adrian."\n\n>>> context = Context({"my_name": "Dolores"})\n>>> template.render(context)\n"My name is Dolores."\nLes noms de variables peuvent contenir des lettres (A-Z), des chiffres (0-9), des soulignements et des points (mais elles ne peuvent pas commencer par un soulignement).
\nLes points ont une signification particulière dans le rendu des gabarits. Un point dans un nom de variable indique l’accès à un sous-élément. Plus précisément, lorsque le système de gabarit voit un point dans un nom de variable, il recherche des sous-éléments dans cet ordre :
\nAccès dictionnaire. Exemple : foo["bar"]
Accès attribut. Exemple : foo.bar
Accès par index de liste. Exemple : foo[bar]
Notez que « bar » dans une expression de gabarit comme {{ foo.bar }} est interprété comme une chaîne littérale et même si une variable « bar » existe dans le contexte du gabarit, elle ne sera pas appelée.
Le système de gabarits utilise le premier accès qui fonctionne. C’est une logique de court-circuit. Voici quelques exemples :
\n>>> from django.template import Context, Template\n>>> t = Template("My name is {{ person.first_name }}.")\n>>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}\n>>> t.render(Context(d))\n"My name is Joe."\n\n>>> class PersonClass:\n... pass\n...\n>>> p = PersonClass()\n>>> p.first_name = "Ron"\n>>> p.last_name = "Nasty"\n>>> t.render(Context({"person": p}))\n"My name is Ron."\n\n>>> t = Template("The first stooge in the list is {{ stooges.0 }}.")\n>>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})\n>>> t.render(c)\n"The first stooge in the list is Larry."\nSi un élément de la variable est un objet exécutable, le système de gabarits essaye de l’appeler. Exemple :
\n>>> class PersonClass2:\n... def name(self):\n... return "Samantha"\n...\n>>> t = Template("My name is {{ person.name }}.")\n>>> t.render(Context({"person": PersonClass2}))\n"My name is Samantha."\nLes variables exécutables sont légèrement plus complexes que les variables qui ne demandent que des accès directs. Voici quelques éléments à garder en tête :
\nSi la variable génère une exception quand elle est appelée, celle-ci est propagée, sauf si l’exception possède un attribut silent_variable_failure valant True. Dans ce dernier cas, la variable produira une chaîne équivalente au contenu de l’option de configuration string_if_invalid du moteur (chaîne vide par défaut). Exemple :
>>> t = Template("My name is {{ person.first_name }}.")\n>>> class PersonClass3:\n... def first_name(self):\n... raise AssertionError("foo")\n...\n>>> p = PersonClass3()\n>>> t.render(Context({"person": p}))\nTraceback (most recent call last):\n...\nAssertionError: foo\n\n>>> class SilentAssertionError(Exception):\n... silent_variable_failure = True\n...\n>>> class PersonClass4:\n... def first_name(self):\n... raise SilentAssertionError\n...\n>>> p = PersonClass4()\n>>> t.render(Context({"person": p}))\n"My name is ."\nNotez que django.core.exceptions.ObjectDoesNotExist, qui est la classe de base de toutes les exceptions DoesNotExist de l’API de base de données de Django, contient silent_variable_failure = True. Ainsi, si vous utilisez les gabarits de Django avec des objets modèles de Django, toute exception DoesNotExist échoue silencieusement.
Une variable ne peut être appelée que si elle ne demande pas de paramètre. Sinon le système renvoie la valeur de l’option string_if_invalid du moteur.
Des effets de bord peuvent se produire lors de l’appel à certaines variables et il serait insensé ou sécuritairement désastreux de permettre au système de gabarits d’y accéder.
\nUn bon exemple est la méthode delete() de chaque objet modèle de Django. Le système de gabarits ne devrait pas permettre de faire quelque chose comme :
I will now delete this valuable data. {{ data.delete }}\nTo prevent this, set an alters_data attribute on the callable\nvariable. The template system won’t call a variable if it has\nalters_data=True set, and will instead replace the variable with\nstring_if_invalid, unconditionally. The\ndynamically-generated delete() and\nsave() methods on Django model objects get\nalters_data=True automatically. Example:
def sensitive_function(self):\n self.database_record.delete()\n\n\nsensitive_function.alters_data = True\nOccasionally you may want to turn off this feature for other reasons,\nand tell the template system to leave a variable uncalled no matter\nwhat. To do so, set a do_not_call_in_templates attribute on the\ncallable with the value True. The template system then will act as\nif your variable is not callable (allowing you to access attributes of\nthe callable, for example).
Généralement, si une variable n’existe pas, le système des gabarits insère la valeur de l’option de configuration string_if_invalid du moteur, qui vaut '' (chaîne vide) par défaut.
Les filtres appliqués à une variable non valide ne seront appliqués que si string_if_invalid est défini à '' (la chaîne vide). Si string_if_invalid est défini à une autre valeur, les filtres de variable seront ignorés.
Ce comportement est légèrement différent pour les balises de gabarit if, for et regroup. Si une variable non valide est fournie à l’une de ces balises de gabarit, la variable sera interprétée comme None. Les filtres sont toujours appliqués aux variables non valides dans ces balises de gabarit.
Si string_if_invalid contient un substituant '%s', ce dernier sera remplacé par le nom de la variable non valide.
Tous les contextes contiennent True, False et None. Comme on peut s’y attendre, ces variables correspondent aux objets Python équivalents.
Le langage de gabarit de Django ne possède pas de moyen pour échapper les caractères utilisés pour sa propre syntaxe. Par exemple, la balise templatetag est indispensable pour afficher des séquences de caractères comme {% ou %}.
Un problème similaire survient lorsqu’il s’agit d’inclure ces séquences dans les paramètres d’un filtre ou d’une balise. Par exemple, lors de l’analyse d’un bloc de balise, l’analyseur de gabarit de Django cherche la première occurrence de %} après un {%. Cela empêche de pouvoir utiliser "%}" dans une chaîne littérale. Par exemple, une exception TemplateSyntaxError est générée pour les expressions suivantes :
{% include "template.html" tvar="Some string literal with %} in it." %}\n\n{% with tvar="Some string literal with %} in it." %}{% endwith %}\nLa même problématique est révélée quand on utilise une séquence réservée dans les paramètres d’un filtre :
\n{{ some.variable|default:"}}" }}\nSi vous avez besoin d’utiliser des chaînes qui contiennent ces séquences, vous devez les stocker dans des variables de gabarit ou utiliser une balise ou un filtre personnalisé pour détourner cette restriction.
\nContextLien vers cette rubrique#La plupart du temps, les objets Context sont créés en transmettant à Context() un dictionnaire contenant les données utiles. Mais il est toujours possible d’ajouter ou d’enlever des éléments d’un objet Context après sa création, en employant la syntaxe habituelle des dictionnaires :
>>> from django.template import Context\n>>> c = Context({"foo": "bar"})\n>>> c["foo"]\n'bar'\n>>> del c["foo"]\n>>> c["foo"]\nTraceback (most recent call last):\n...\nKeyError: 'foo'\n>>> c["newvariable"] = "hello"\n>>> c["newvariable"]\n'hello'\nRenvoie la valeur correspondant à key si key est dans le contexte, sinon renvoie otherwise.
Si key est dans le contexte, renvoie sa valeur. Sinon insère key avec la valeur default et renvoie default.
Un objet Context est une pile. C’est-à-dire que vous pouvez lui appliquer les méthodes push() et pop(). En cas de pop() en trop, une exception django.template.ContextPopException est générée :
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> c.push()\n{}\n>>> c["foo"] = "second level"\n>>> c["foo"]\n'second level'\n>>> c.pop()\n{'foo': 'second level'}\n>>> c["foo"]\n'first level'\n>>> c["foo"] = "overwritten"\n>>> c["foo"]\n'overwritten'\n>>> c.pop()\nTraceback (most recent call last):\n...\nContextPopException\nVous pouvez aussi utiliser push() comme gestionnaire de contexte pour garantir que l’instruction pop() correspondante soit effectivement appelée.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> with c.push():\n... c["foo"] = "second level"\n... c["foo"]\n...\n'second level'\n>>> c["foo"]\n'first level'\nTous les paramètres passés à push() sont transmis au constructeur de dict utilisé pour construire le nouveau niveau de contexte.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> with c.push(foo="second level"):\n... c["foo"]\n...\n'second level'\n>>> c["foo"]\n'first level'\nEn plus de push() et pop(), l’objet Context définit également une méthode update(). Elle fonctionne comme push(), mais accepte en paramètre un dictionnaire et place ce dictionnaire sur la pile, au lieu d’un dictionnaire vide.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> c.update({"foo": "updated"})\n{'foo': 'updated'}\n>>> c["foo"]\n'updated'\n>>> c.pop()\n{'foo': 'updated'}\n>>> c["foo"]\n'first level'\nComme push(), vous pouvez utiliser update() comme gestionnaire de contexte pour garantir que l’instruction pop() correspondante soit effectivement appelée.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> with c.update({"foo": "second level"}):\n... c["foo"]\n...\n'second level'\n>>> c["foo"]\n'first level'\nL’utilisation de Context comme une pile est bien pratique avec certaines balises de gabarit personnalisées.
En utilisant la méthode flatten(), vous pouvez obtenir l’ensemble de la pile de Context sous forme d’un unique dictionnaire, y compris les variables natives.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> c.update({"bar": "second level"})\n{'bar': 'second level'}\n>>> c.flatten()\n{'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}\nLa méthode flatten() est aussi utilisée en interne pour rendre les objets Context comparables.
>>> c1 = Context()\n>>> c1["foo"] = "first level"\n>>> c1["bar"] = "second level"\n>>> c2 = Context()\n>>> c2.update({"bar": "second level", "foo": "first level"})\n{'foo': 'first level', 'bar': 'second level'}\n>>> c1 == c2\nTrue\nLe résultat de flatten() peut être utile dans les tests unitaires pour comparer Context avec un dict:
class ContextTest(unittest.TestCase):\n def test_against_dictionary(self):\n c1 = Context()\n c1["update"] = "value"\n self.assertEqual(\n c1.flatten(),\n {\n "True": True,\n "None": None,\n "False": False,\n "update": "value",\n },\n )\nRequestContextLien vers cette rubrique#Django contient une classe Context spéciale, django.template.RequestContext, qui se comporte légèrement différemment de l’objet django.template.Context normal. La première différence est qu’elle demande un objet HttpRequest comme premier paramètre. Par exemple :
c = RequestContext(\n request,\n {\n "foo": "bar",\n },\n)\nLa seconde différence est qu’elle remplit automatiquement le contexte avec quelques variables, en fonction de l’option de configuration context_processors du moteur.
L’option context_processors est une liste d’objets exécutables appelés processeurs de contexte qui acceptent un objet requête en paramètre et renvoient un dictionnaire d’éléments à fusionner dans le contexte. Dans le fichier de réglages généré par défaut, le moteur de gabarit par défaut contient les processeurs de contexte suivants :
[\n "django.template.context_processors.request",\n "django.contrib.auth.context_processors.auth",\n "django.contrib.messages.context_processors.messages",\n]\nIn addition to these, RequestContext always enables\n'django.template.context_processors.csrf'. This is a security related\ncontext processor required by the admin and other contrib apps, and, in case\nof accidental misconfiguration, it is deliberately hardcoded in and cannot be\nturned off in the context_processors option.
Chaque processeur est appliqué successivement. Cela signifie que si un processeur ajoute une variable au contexte et que le processeur suivant ajoute une variable de même nom, la seconde écrase la première. Les processeurs par défaut sont présentés ci-dessous.
\n\nIl est également possible de donner à RequestContext une liste de processeurs supplémentaires en utilisant le troisième paramètre positionnel facultatif, processors. Dans cet exemple, l’instance RequestContext reçoit une variable ip_address:
from django.http import HttpResponse\nfrom django.template import RequestContext, Template\n\n\ndef ip_address_processor(request):\n return {"ip_address": request.META["REMOTE_ADDR"]}\n\n\ndef client_ip_view(request):\n template = Template("{{ title }}: {{ ip_address }}")\n context = RequestContext(\n request,\n {\n "title": "Your IP Address",\n },\n [ip_address_processor],\n )\n return HttpResponse(template.render(context))\nVoici ce que font chacun des processeurs de contexte intégrés :
\ndjango.contrib.auth.context_processors.authLien vers cette rubrique#Si ce processeur est activé, chaque RequestContext contiendra ces variables :
user – une instance auth.User représentant l’utilisateur actuellement connecté (ou une instance AnonymousUser, si le client n’est pas connecté).
perms – une instance de django.contrib.auth.context_processors.PermWrapper, représentant les permissions de l’utilisateur actuellement connecté.
django.template.context_processors.debugLien vers cette rubrique#Si ce processeur est activé, chaque RequestContext contient ces deux variables – mais seulement si le réglage DEBUG vaut True et que l’adresse IP de la requête (request.META['REMOTE_ADDR']) se trouve dans le réglage INTERNAL_IPS:
debug – True. Vous pouvez l’utiliser dans les gabarits pour tester si vous êtes en mode DEBUG.
sql_queries – une liste de dictionnaires {'sql': ..., 'time': ...} représentant chaque requête SQL effectuée jusque-là dans le traitement de la requête et le temps nécessaire à son exécution. La liste est triée par alias de base de données, puis par requête. Elle est produite de manière différée au moment de son accès.
django.template.context_processors.i18nLien vers cette rubrique#Si ce processeur est activé, chaque RequestContext contiendra ces variables :
LANGUAGES – la valeur du réglage LANGUAGES.
LANGUAGE_BIDI – True, si la langue actuelle est une langue s’écrivant de droite à gauche, comme l’hébreu ou l’arabe. False s’il s’agit d’une langue s’écrivant de gauche à droite, comme l’anglais, le français ou l’allemand.
LANGUAGE_CODE – request.LANGUAGE_CODE, si elle existe. Sinon, la valeur du réglage LANGUAGE_CODE.
Voir balises de gabarits i18n pour des balises de gabarits qui génèrent les mêmes valeurs.
\ndjango.template.context_processors.mediaLien vers cette rubrique#Si ce processeur est activé, chaque RequestContext contiendra une variable MEDIA_URL, équivalente au réglage MEDIA_URL.
django.template.context_processors.staticLien vers cette rubrique#Si ce processeur est activé, chaque RequestContext contiendra une variable STATIC_URL, équivalente au réglage STATIC_URL.
django.template.context_processors.csrfLien vers cette rubrique#Ce processeur ajoute un jeton requis par la balise de gabarit csrf_token pour se protéger des attaques de type Cross Site Request Forgeries.
This is always enabled by RequestContext and cannot\nbe disabled. You do not need to include it within context_processors.
django.template.context_processors.cspLien vers cette rubrique#If this processor is enabled, every RequestContext will contain a variable\ncsp_nonce, providing a securely generated, request-specific nonce suitable\nfor use under a Content Security Policy. See CSP nonce usage\nfor details.
django.template.context_processors.requestLien vers cette rubrique#Si ce processeur est activé, chaque RequestContext contiendra une variable request correspondant à l’objet HttpRequest actuel.
django.template.context_processors.tzLien vers cette rubrique#Si ce processeur est activé, chaque RequestContext contiendra une variable TIME_ZONE, fournissant le nom du fuseau horaire actuellement actif.
django.contrib.messages.context_processors.messagesLien vers cette rubrique#Si ce processeur est activé, chaque RequestContext contiendra ces deux variables :
messages – une liste de messages (sous forme de chaînes) qui ont été définis au travers de l’infrastructure des messages.
DEFAULT_MESSAGE_LEVELS – un tableau de correspondance entre les noms de niveaux de message et leur valeur numérique.
Un processeur de contexte possède une interface simple : il s’agit d’une fonction Python acceptant un paramètre, un objet HttpRequest, et renvoyant un dictionnaire qui est ensuite ajouté au contexte de gabarit.
Par exemple, pour ajouter le réglage DEFAULT_FROM_EMAIL à tous les contextes
from django.conf import settings\n\n\ndef from_email(request):\n return {\n "DEFAULT_FROM_EMAIL": settings.DEFAULT_FROM_EMAIL,\n }\nLes processeurs de contexte personnalisés peuvent se trouver n’importe où dans le code. Tout ce que Django demande, c’est que l’option 'context_processors' du réglage TEMPLATES (ou le paramètre context_processors d’un moteur Engine si vous l’utilisez directement) contienne le chemin vers le processeur personnalisé.
En général, il est conseillé de stocker les gabarits sur le système de fichiers plutôt que de faire appel à l’API Template de bas niveau. Les gabarits doivent se trouver dans un répertoire désigné comme répertoire de gabarits.
Django recherche les répertoires de gabarits à plusieurs endroits, en fonction des réglages de chargement des gabarits (voir « Types de chargeurs » ci-dessous), mais la façon la plus élémentaire de désigner des répertoires de gabarits est d’utiliser l’option DIRS.
DIRSLien vers cette rubrique#Indiquez à Django quels sont vos répertoires de gabarits en utilisant l’option DIRS du réglage TEMPLATES dans votre fichier de réglages, ou le paramètre dirs de Engine. Il devrait contenir une liste de chaînes contenant les chemins complets vers les répertoires de gabarits :
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "DIRS": [\n "/home/html/templates/lawrence.com",\n "/home/html/templates/default",\n ],\n },\n]\nLes gabarits peuvent se trouver n’importe où, pour autant que leur emplacement soit lisible par le serveur web. Leur extension est également à votre bon plaisir, .html, .txt, ou même sans extension du tout.
Notez que ces chemins doivent utiliser les barres obliques de style Unix, même avec Windows.
\nPar défaut, Django utilise un chargeur de gabarit basé sur le système de fichiers, mais il existe également quelques autres chargeurs de gabarit, qui savent comment charger des gabarits à partir d’autres sources.
\nCertains de ces autres chargeurs sont désactivés par défaut, mais vous pouvez les activer en ajoutant une option 'loaders' à votre moteur DjangoTemplates dans le réglage TEMPLATES ou en transmettant un paramètre loaders à Engine. loaders doit contenir une liste de chaînes ou de tuples, où chaque élément représente une classe de chargeur de gabarit. Voici les chargeurs de gabarit que Django propose :
django.template.loaders.filesystem.Loader
Charge les gabarits à partir du système de fichiers, en fonction de DIRS.
Ce chargeur est actif par défaut. Cependant, il ne trouvera aucun gabarit tant que vous n’aurez pas défini DIRS à une liste non vide :
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "DIRS": [BASE_DIR / "templates"],\n }\n]\nIl est aussi possible de surcharger 'DIRS' et de définir des répertoires spécifiques à un chargeur basé sur le système de fichiers :
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "OPTIONS": {\n "loaders": [\n (\n "django.template.loaders.filesystem.Loader",\n [BASE_DIR / "templates"],\n ),\n ],\n },\n }\n]\ndjango.template.loaders.app_directories.Loader
Charge les gabarits à partir des dossiers d’applications Django sur le système de fichiers. Pour chaque application dans INSTALLED_APPS, le chargeur cherche un sous-répertoire nommé templates. S’il le trouve, Django recherche les gabarits dans ce répertoire.
Cela signifie que vous pouvez stocker les gabarits à l’intérieur des différentes applications. Cela facilite également la distribution des applications Django dotées de gabarits par défaut.
\nPar exemple, avec ce réglage :
\nINSTALLED_APPS = ["myproject.polls", "myproject.music"]\n…get_template('foo.html') recherche foo.html dans ces répertoires, dans l’ordre :
/chemin/vers/myproject/polls/templates/
/chemin/vers/myproject/music/templates/
… et utilise le premier qu’il trouve.
\nL’ordre de INSTALLED_APPS est important ! Par exemple, si vous souhaitez personnaliser l’administration de Django, il peut être utile de surcharger le gabarit admin/base_site.html standard de django.contrib.admin par votre propre admin/base_site.html dans myproject.polls. Vous devez alors vous assurer que myproject.polls apparaisse avant django.contrib.admin dans INSTALLED_APPS, sinon django.contrib.admin sera chargé en premier et votre gabarit sera ignoré.
Notez que le chargeur effectue une optimisation lors de son premier lancement : il place en cache une liste des paquets INSTALLED_APPS qui possèdent un sous-répertoire templates.
Vous pouvez activer ce chargeur en définissant APP_DIRS à True:
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "APP_DIRS": True,\n }\n]\ndjango.template.loaders.cached.Loader
Même si le système des gabarits de Django est plutôt rapide, s’il doit lire et compiler vos gabarits lors de chaque rendu, la surcharge occasionnée peut être conséquente.
\nLe chargeur de gabarits « en cache » est configuré en lui donnant une liste d’autres chargeurs qu’il va encapsuler. Les chargeurs encapsulés sont utilisés pour retrouver les gabarits inconnus la première fois qu’ils sont référencés. Le chargeur « en cache » stocke ensuite l’objet Template compilé en mémoire. Cette instance mise en cache est renvoyée lors de chaque nouvelle requête de chargement de ce même gabarit.
Ce chargeur est automatiquement activé quand OPTIONS['loaders'] n’est pas défini.
Il est possible d’activer manuellement le cache de gabarits avec des chargeurs de gabarit personnalisés en utilisant des réglages comme ceci :
\nTEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "DIRS": [BASE_DIR / "templates"],\n "OPTIONS": {\n "loaders": [\n (\n "django.template.loaders.cached.Loader",\n [\n "django.template.loaders.filesystem.Loader",\n "django.template.loaders.app_directories.Loader",\n "path.to.custom.Loader",\n ],\n ),\n ],\n },\n }\n]\ndjango.template.loaders.locmem.Loader
Charge des gabarits à partir d’un dictionnaire Python. Utile pour les tests.
\nCe chargeur prend un dictionnaire de gabarits comme premier paramètre :
\nTEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "OPTIONS": {\n "loaders": [\n (\n "django.template.loaders.locmem.Loader",\n {\n "index.html": "content here",\n },\n ),\n ],\n },\n }\n]\nCe chargeur est désactivé par défaut.
\nDjango utilise les chargeurs de gabarit dans l’ordre de leur apparition dans l’option 'loaders'. Il utilise chaque chargeur jusqu’à ce qu’il trouve une correspondance.
Il est possible de charger des gabarits provenant de sources supplémentaires en utilisant des chargeurs de gabarit personnalisés. Les classes personnalisées de Loader doivent hériter de django.template.loaders.base.Loader et définir les méthodes get_contents() et get_template_sources().
Charge des gabarits à partir d’une source donnée, telle que le système de fichier ou une base de données.
\nUne méthode acceptant un nom de gabarit template_name et renvoyant une à une des instances Origin pour chaque source possible.
For example, the filesystem loader may receive 'index.html' as a\ntemplate_name argument. This method would yield origins for the\nfull path of index.html as it appears in each template directory\nthe loader looks at.
La méthode n’a pas besoin de vérifier que le gabarit existe pour un chemin donné, mais elle doit s’assurer que le chemin est valide. Par exemple, le chargeur système de fichiers doit s’assurer que le chemin se trouve bien dans un répertoire de gabarits valide.
\nRenvoie le contenu d’un gabarit en fonction d’une instance Origin donnée.
C’est ici qu’un chargeur système de fichiers lit le contenu à partir du système de fichiers, ou qu’un chargeur base de données lit à partir de la base de données. Si aucun gabarit existant ne correspond, une erreur TemplateDoesNotExist doit être générée.
Renvoie un objet Template correspondant à template_name en passant en boucle ce que get_template_sources() renvoie et en appelant get_contents(). Le premier gabarit trouvé est renvoyé. Si aucun n’est trouvé, une exception TemplateDoesNotExist est générée.
Le paramètre facultatif skip est une liste d’origines à ignorer lors de l’extension des gabarits. Cela permet à des gabarits d’étendre d’autres gabarits du même nom. Une autre utilité est d’éviter les erreurs de récursion.
En général, il est suffisant que les chargeurs de gabarit personnalisés définissent get_template_sources() et get_contents(). get_template() n’a généralement pas besoin d’être surchargée.
Les gabarits possèdent un attribut origin contenant des attributs qui dépendent de la source à partir de laquelle ils ont été chargés.
Le chemin du gabarit tel que renvoyé par le chargeur de gabarit. Pour les chargeurs qui lisent à partir du système de fichiers, il s’agit du chemin complet correspondant au gabarit.
\nSi le gabarit est instancié directement plutôt que par l’intermédiaire d’un chargeur de gabarits, ce chemin contient <unknown_source> (source inconnue).
Le chemin relatif du gabarit tel que transmis au chargeur de gabarits.
\nSi le gabarit est instancié directement plutôt que par l’intermédiaire d’un chargeur de gabarits, cette valeur vaut None.
L’instance de chargeur de gabarits qui a construit cette Origin.
Si le gabarit est instancié directement plutôt que par l’intermédiaire d’un chargeur de gabarits, cette valeur vaut None.
django.template.loaders.cached.Loader exige que tous les chargeurs qu’elle enveloppe définissent cet attribut, typiquement en créant l’instance Origin avec loader=self.