Ce document présente la syntaxe du langage du système de gabarits de Django. Si vous recherchez une perspective plus technique sur son fonctionnement et sur la manière de l’étendre, consultez Le langage de gabarit de Django : pour les programmeurs Python.
\nLe langage de gabarit de Django est conçu comme un compromis entre puissance et simplicité. Il est conçu pour que les habitués au code HTML se sentent à l’aise. Si vous avez des connaissances d’autres langages de gabarit orientés texte, tels que Smarty ou Jinja2, vous n’allez pas être dépaysés avec les gabarits de Django.
\n\nUn gabarit est un fichier texte. Il peut générer tout format basé sur du texte (HTML, XML, CSV, etc.).
\nUn gabarit contient des variables qui sont remplacées par des valeurs lorsque le gabarit est évalué, ainsi que des balises qui contrôlent la logique du gabarit.
\nVoici un gabarit minimal illustrant quelques principes de base. Chaque élément sera ensuite expliqué plus loin dans ce document.
\n{% extends "base_generic.html" %}\n\n{% block title %}{{ section.title }}{% endblock %}\n\n{% block content %}\n<h1>{{ section.title }}</h1>\n\n{% for story in story_list %}\n<h2>\n <a href="{{ story.get_absolute_url }}">\n {{ story.headline|upper }}\n </a>\n</h2>\n<p>{{ story.tease|truncatewords:"100" }}</p>\n{% endfor %}\n{% endblock %}\nLes variables apparaissent comme ceci : {{ variable }}. Lorsque le moteur de gabarit rencontre une variable, il l’évalue et la remplace par le résultat. Les noms de variables peuvent contenir tout caractère alphanumérique ainsi que le soulignement ("_") mais ne peuvent pas commencer par un soulignement et ne peuvent pas être un nombre. Le point (".") peut aussi faire partie du nom de variable, mais avec une signification particulière, comme nous l’expliquons ci-après. Il est important de relever que les espaces et la ponctuation ne sont pas autorisés dans les noms de variables.
Le point (.) est utilisé pour accéder aux attributs d’une variable.
Dans l’exemple ci-dessus, {{ section.title }} sera remplacé par l’attribut title de l’objet section.
Si vous appelez une variable qui n’existe pas, le système des gabarits insère la valeur de l’option string_if_invalid, qui vaut '' (chaîne vide) par défaut.
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.
Les attributs de variable qui commencent par un soulignement ne peuvent pas être accédés car ils sont généralement considérés comme privés.
\nVous pouvez modifier l’affichage des variables en utilisant des filtres.
\nLes filtres ressemblent à ceci : {{ nom|lower }}. Ceci affiche la valeur de la variable {{ nom }} après avoir été filtrée par le filtre lower qui convertit le texte en minuscules. Utilisez la barre verticale (|) pour appliquer un filtre.
Les filtres peuvent s’enchaîner. Le résultat d’un filtre est appliqué au suivant. {{ text|escape|linebreaks }} est un idiome courant pour échapper du contenu textuel, puis convertir les sauts de ligne en balises <p>.
Certains filtres acceptent des paramètres. Un paramètre de filtre ressemble à ceci : {{ bio|truncatewords:30 }}. Ceci affiche les 30 premiers mots de la variable bio.
Les paramètres de filtre contenant des espaces doivent être placés entre guillemets ; par exemple, pour concaténer une liste en utilisant une virgule et une espace, il faudrait écrire {{ liste|join:", " }}.
Django fournit une soixantaine de filtres de gabarit intégrés. Il sont tous documentés dans la référence des filtres intégrés. Pour vous donner une idée de ce qui est disponible, voici quelques-uns des filtres de gabarit les plus utilisés :
\ndefaultSi une variable contient la valeur faux ou est vide, ce filtre utilise la valeur par défaut indiquée. Sinon, il utilise la valeur de la variable. Par exemple :
\n{{ value|default:"nothing" }}\nSi value n’est pas fournie ou qu’elle est vide, le code ci-dessus affiche « nothing ».
lengthRenvoie la longueur de la valeur. Cela fonctionne aussi bien pour du texte que des listes. Par exemple :
\n{{ value|length }}\nSi value vaut ['a', 'b', 'c', 'd'], le résultat sera 4.
filesizeformatMet en forme la valeur sous forme de taille de fichier humainement lisible (par ex. '13 Kio', '4.1 Mio', '102 octets', etc). Par exemple :
{{ value|filesizeformat }}\nSI value contient 123456789, le résultat sera 117.7 Mio.
Ce n’était que quelques exemples ; voir la référence des filtres intégrés pour une liste complète.
\nVous pouvez aussi créer vos propres filtres de gabarit ; voir Création de balises et filtres de gabarit personnalisés.
\n\nPour commenter une partie de ligne dans un gabarit, utilisez la syntaxe de commentaire : {# #}.
Par exemple, ce gabarit produit le contenu 'hello':
{# greeting #}hello\nUn commentaire peut contenir n’importe quel code de gabarit, valide ou non. Par exemple :
\n{# {% if foo %}bar{% else %} #}\nCette syntaxe n’est utilisable que pour les commentaires d’une seule ligne (aucun saut de ligne n’est autorisé entre les délimiteurs {# et #}). Si vous avez besoin de mettre en commentaire plusieurs lignes d’un gabarit, référez-vous à la balise comment.
La partie la plus puissante, mais aussi la plus complexe, du moteur de gabarits de Django est l’héritage des gabarits. Cet héritage permet de construire un gabarit « squelette » de base contenant tous les éléments communs de votre site et de définir des blocs que les gabarits enfants peuvent surcharger.
\nExaminons l’héritage des gabarits en commençant par un exemple :
\n<!DOCTYPE html>\n<html lang="en">\n<head>\n <link rel="stylesheet" href="style.css">\n <title>{% block title %}My amazing site{% endblock %}</title>\n</head>\n\n<body>\n <div id="sidebar">\n {% block sidebar %}\n <ul>\n <li><a href="/">Home</a></li>\n <li><a href="/blog/">Blog</a></li>\n </ul>\n {% endblock %}\n </div>\n\n <div id="content">\n {% block content %}{% endblock %}\n </div>\n</body>\n</html>\nCe gabarit que nous appellerons base.html définit un squelette de document HTML qui pourrait être employé pour une page sur deux colonnes. C’est le travail des gabarits « enfants » de remplir les blocs vides avec du contenu.
Dans cet exemple, la balise block définit trois blocs que les gabarits enfants peuvent remplir. La balise block ne fait que signaler au moteur de gabarits qu’un gabarit enfant peut surcharger ces portions du gabarit.
Un gabarit enfant pourrait ressembler à ceci :
\n{% extends "base.html" %}\n\n{% block title %}My amazing blog{% endblock %}\n\n{% block content %}\n{% for entry in blog_entries %}\n <h2>{{ entry.title }}</h2>\n <p>{{ entry.body }}</p>\n{% endfor %}\n{% endblock %}\nLa balise extends est ici la clé. Elle indique au moteur de gabarits que ce gabarit « étend » un autre gabarit. Lorsque le moteur de gabarits l’évalue, il récupère d’abord le parent, dans ce cas « base.html ».
À ce stade, le moteur de gabarits remarque les trois balises block de base.html et remplace ces blocs par le contenu du gabarit enfant. En fonction de la valeur de blog_entries, le résultat pourrait ressembler à :
<!DOCTYPE html>\n<html lang="en">\n<head>\n <link rel="stylesheet" href="style.css">\n <title>My amazing blog</title>\n</head>\n\n<body>\n <div id="sidebar">\n <ul>\n <li><a href="/">Home</a></li>\n <li><a href="/blog/">Blog</a></li>\n </ul>\n </div>\n\n <div id="content">\n <h2>Entry one</h2>\n <p>This is my first entry.</p>\n\n <h2>Entry two</h2>\n <p>This is my second entry.</p>\n </div>\n</body>\n</html>\nNotez que comme le gabarit enfant n’a pas défini le bloc sidebar, c’est la valeur provenant du gabarit parent qui est utilisée. C’est toujours le contenu de la balise {% block %} du gabarit parent qui est utilisé comme contenu par défaut.
Vous pouvez utiliser autant de niveaux d’héritage que nécessaire. Une façon courante d’utiliser l’héritage est l’approche à trois niveaux suivante :
\nCréer un gabarit base.html contenant l’apparence principale du site.
Créer un gabarit base_NOMSECTION.html pour chaque section du site. Par exemple, base_actualites.html, base_sports.html. Tous ces gabarits étendent base.html et contiennent le style et l’aspect spécifiques à la section.
Créer des gabarits individuels pour chaque type de page, tel qu’un article d’actualité ou un article de blog. Ces gabarits étendent le gabarit de la section dans laquelle ils figurent.
Cette approche maximise la réutilisation de code et facilite l’ajout d’éléments aux zones de contenu partagé, telle que la navigation propre à la section.
\nVoici quelques astuces concernant l’héritage :
\nSi vous utilisez {% extends %} dans un gabarit, cela doit être la première balise dans ce gabarit. Sinon, l’héritage des gabarits ne fonctionnera pas.
Ne soyez pas économe de balises {% block %} dans vos gabarits de base. Rappelez-vous que les gabarits enfants ne doivent pas redéfinir tous les blocs du parent, vous pouvez donc placer du contenu généraliste dans certains blocs et ne redéfinir que ce qui est nécessaire dans les gabarits enfants. Il est préférable d’avoir trop de points d’insertion que d’en manquer.
Si vous vous retrouvez à dupliquer du contenu dans plusieurs gabarits, cela signifie probablement que vous devriez placer ce contenu dans un {% block %} d’un gabarit parent.
Si vous avez besoin de reproduire le contenu du bloc du gabarit parent, la variable {{ block.super }} fera l’affaire. C’est utile lorsque vous voulez compléter le contenu d’un bloc parent plutôt que de l’écraser simplement. Les données insérées par {{ block.super }} ne sont pas échappées automatiquement (voir la section suivante) puisqu’elles ont déjà été échappées dans le gabarit parent, si nécessaire.
En utilisant le même nom de gabarit que celui dont vous héritez, {% extends %} peut être utilisé pour hériter d’un gabarit tout en le surchargeant. Combiné avec {{ block.super }}, il s’agit d’un puissant moyen de faire de petits ajustements. Consultez Extension d’un gabarit surchargé dans le guide de la Surcharge de gabarits pour voir un exemple complet.
Les variables créées en dehors d’un bloc {% block %} en utilisant la syntaxe de balise de gabarit as ne peuvent pas être utilisées à l’intérieur du bloc. Par exemple, ce gabarit ne produira rien du tout :
{% translate "Title" as title %}\n{% block content %}{{ title }}{% endblock %}\nPour une meilleure lisibilité, vous pouvez donner un nom à votre balise {% endblock %}. Par exemple :
{% block content %}\n...\n{% endblock content %}\nDans les gros gabarits, cette technique permet de mieux voir quelle est la balise {% block %} que cette balise ferme.
Les balises {% block %} sont évaluées en premier. C’est pourquoi le contenu d’un bloc est toujours écrasé, quelle que soit la valeur booléenne des balises environnantes. Par exemple, ce gabarit va toujours écraser le contenu du bloc title :
{% if change_title %}\n {% block title %}Hello!{% endblock title %}\n{% endif %}\nPour terminer, notez que vous ne pouvez pas définir plusieurs balises block ayant le même nom dans le même gabarit. Cette restriction existe parce qu’une balise block fonctionne dans les « deux » sens. C’est-à-dire qu’une balise block ne fait pas que définir un vide à combler, elle définit aussi le contenu qui comble ce vide dans le parent. S’il y avait deux balises block ayant le même nom dans un gabarit, le parent de ce gabarit ne saurait pas de quel bloc le contenu doit être pris en compte.
Lors de la production de HTML avec les gabarits, il y a toujours un risque qu’une variable inclue des caractères qui altèrent le HTML produit. Par exemple, considérez cet extrait de gabarit :
\nHello, {{ name }}\nAu premier abord, cela semble une manière inoffensive d’afficher un nom d’utilisateur, mais imaginez ce qui se produit si l’utilisateur a saisi son nom comme ceci :
\n<script>alert('hello')</script>\nAvec cette valeur pour le nom, le gabarit serait produit comme ceci :
\nHello, <script>alert('hello')</script>\n… ce qui signifie que le navigateur afficherait une fenêtre d’alerte JavaScript !
\nDe la même manière, que se passe-t-il si le nom contient un symbole '<' comme ceci ?
<b>username\nCela aboutit à l’affichage d’un résultat de gabarit comme ceci :
\nHello, <b>username\n…ce qui ferait que tout le reste de la page web serait affiché en gras !
\nClairement, il ne faut pas se fier aveuglément aux données envoyées par les utilisateurs en les insérant directement dans vos pages web, car un utilisateur malveillant pourrait exploiter ce genre de faille dans une mauvaise perspective. Ce type de faille de sécurité est appelé une attaque Cross Site Scripting (XSS).
\nPour éviter ce problème, vous avez deux options :
\nPremièrement, vous pouvez vous efforcer de faire passer ces variables non sécurisées par le filtre escape (documenté ci-dessous), qui convertit les caractères HTML potentiellement dangereux en caractères inoffensifs. C’est la solution par défaut choisie par Django dans ses premières années, mais le problème est que la pression est sur vous, développeur ou auteur de gabarit, qui devez vous assurer que tout soit bien échappé. Il est très vite fait d’oublier d’échapper des données.
Deuxièmement, vous pouvez profiter de l’échappement automatique de HTML que Django effectue. Le reste de cette section décrit le fonctionnement de l’échappement automatique.
Par défaut dans Django, chaque gabarit échappe automatiquement le résultat de chaque balise de variable. Plus précisément, ces cinq caractères sont échappés :
\n< est converti en <
> est converti en >
' (apostrophe) est converti en '
" (guillemet) est converti en "
& est converti en &
Nous répétons ici que ce comportement est actif par défaut. Si vous utilisez le système des gabarits de Django, vous êtes protégé.
\nSi vous ne voulez pas que les données soient échappées automatiquement, au niveau d’un site, d’un gabarit ou d’une variable, vous pouvez le désactiver de plusieurs manières.
\nPourquoi vouloir désactiver ce comportement ? Parce qu’il peut arriver parfois que des variables de gabarit contiennent des données que vous voulez vraiment afficher comme contenu HTML brut, auquel cas vous ne souhaitez pas que ces contenus soient échappés. Par exemple, vous stockez peut-être du code HTML dans votre base de données afin de l’intégrer tel quel dans un gabarit. Un autre exemple est quand vous voulez utiliser le système des gabarits de Django pour produire du texte non HTML, comme un message électronique.
\nPour désactiver l’échappement automatique pour une variable individuelle, utilisez le filtre safe:
This will be escaped: {{ data }}\nThis will not be escaped: {{ data|safe }}\nsafe (sûr en anglais) peut être considéré comme un raccourci de sûr de ne pas nécessiter d’échappement ou peut être interprété en HTML de manière sûre. Dans cet exemple, si data contient '<b>', le résultat affiché sera :
This will be escaped: <b>\nThis will not be escaped: <b>\nPour contrôler l’échappement automatique dans un gabarit, entourez le gabarit (ou une portion du gabarit) par la balise autoescape, comme ceci :
{% autoescape off %}\n Hello {{ name }}\n{% endautoescape %}\nLa balise autoescape accepte on ou off comme paramètre. Il est parfois souhaitable de forcer l’échappement automatique dans un contexte où il est désactivé. Voici un exemple de gabarit :
Auto-escaping is on by default. Hello {{ name }}\n\n{% autoescape off %}\n This will not be auto-escaped: {{ data }}.\n\n Nor this: {{ other_data }}\n {% autoescape on %}\n Auto-escaping applies again: {{ name }}\n {% endautoescape %}\n{% endautoescape %}\nLa balise d’échappement automatique transmet ses effets aux gabarits qui étendent le gabarit en cours ainsi qu’aux gabarits inclus par la balise include, comme pour toutes les balises de bloc. Par exemple :
base.html{% autoescape off %}\n<h1>{% block title %}{% endblock %}</h1>\n{% block content %}\n{% endblock %}\n{% endautoescape %}\nchild.html{% extends "base.html" %}\n{% block title %}This & that{% endblock %}\n{% block content %}{{ greeting }}{% endblock %}\nComme l’échappement automatique est désactivé dans le gabarit de base, il sera aussi désactivé dans le gabarit enfant, ce qui aboutit par exemple au contenu HTML affiché suivant lorsque la variable greeting contient le texte <b>Hello!</b>:
<h1>This & that</h1>\n<b>Hello!</b>\nGénéralement, les rédacteurs de gabarits n’ont pas besoin de se préoccuper de l’échappement automatique. Les développeurs du côté Python (ceux qui écrivent les vues et les filtres personnalisés) doivent réfléchir aux situations dans lesquelles les données ne devraient pas subir d’échappement et marquer les données en conséquence, afin que tout fonctionne comme prévu dans les gabarits.
\nSi vous créez un gabarit pouvant être utilisé dans des situations où vous n’êtes pas sûr si l’échappement automatique est actif, ajoutez le filtre escape à toute variable nécessitant l’échappement. Quand l’échappement automatique est actif, il n’y a pas de risque que que le filtre escape échappe doublement les données car celui-ci ne touche pas aux variables ayant déjà subi l’échappement automatique.
Comme mentionné précédemment, les paramètres de filtres peuvent être des chaînes de caractères :
\n{{ data|default:"This is a string literal." }}\nTout texte littéral est inséré sans échappement automatique dans le gabarit, comme s’il était systématiquement passé par le filtre safe. La logique de ce comportement est que l’auteur du gabarit a le contrôle sur le contenu du texte, il peut donc s’assurer que le texte est correctement échappé au moment de la rédaction du gabarit.
Cela signifie qu’il faut écrire :
\n{{ data|default:"3 < 2" }}\n…et non pas :
\n{{ data|default:"3 < 2" }} {# Bad! Don't do this. #}\nCela n’affecte pas les données provenant de la variable elle-même. Le contenu de la variable est toujours échappé automatiquement, si nécessaire, parce qu’il est hors du contrôle de l’auteur du gabarit.
\nLa plupart des appels de méthodes liées aux objets sont aussi disponibles depuis les gabarits. Cela signifie que les gabarits n’ont pas uniquement accès aux attributs de classe (comme les noms de champs) ou aux variables transmises depuis les vues. Par exemple, l’ORM de Django offre la syntaxe « entry_set » pour récupérer une collection d’objets liés par une clé étrangère. Ainsi, étant donné un modèle « comment » avec une relation clé étrangère vers un modèle « task », vous pouvez effectuer une boucle sur tous les commentaires liés à une tâche donnée comme ceci :
\n{% for comment in task.comment_set.all %}\n {{ comment }}\n{% endfor %}\nDe même, les objets QuerySets offrent une méthode count() pour compter le nombre d’objets qu’ils contiennent. Vous pouvez donc obtenir le nombre de tous les commentaires liés à la tâche actuelle avec :
{{ task.comment_set.all.count }}\nVous pouvez aussi accéder aux méthodes que vous avez explicitement définies pour vos propres modèles :
\nmodels.pyclass Task(models.Model):\n def foo(self):\n return "bar"\ntemplate.html{{ task.foo }}\nComme Django limite intentionnellement les traitements logiques possibles dans le langage de gabarit, il n’est pas possible de transmettre des paramètres aux appels de méthodes depuis les gabarits. Les données doivent être calculées dans les vues, puis transmises aux gabarits pour être affichées.
\nCertaines applications contiennent leurs propres bibliothèques de balises et de filtres. Pour y accéder à partir d’un gabarit, vérifiez que l’application se trouve dans INSTALLED_APPS (nous aurions ajouté 'django.contrib.humanize' pour cet exemple), puis utilisez la balise load dans le gabarit :
{% load humanize %}\n\n{{ 45000|intcomma }}\nCi-dessus, la balise load charge la bibliothèque de balises humanize, ce qui permet ensuite d’utiliser le filtre intcomma dans le gabarit. Si django.contrib.admindocs est activée, vous pouvez consulter la section de documentation de votre interface d’administration pour trouver la liste des bibliothèques personnalisées dans votre installation.
La balise load accepte plusieurs noms de bibliothèques séparés par des espaces. Exemple :
{% load humanize i18n %}\nConsultez Création de balises et filtres de gabarit personnalisés pour obtenir des informations sur l’écriture de vos propres bibliothèques de gabarits.
\nLorsque vous chargez une bibliothèque de balises ou de filtres, ces balises/filtres ne sont disponibles que pour le gabarit concerné, et pas pour les gabarits parents ou enfants dans la chaîne d’héritage des gabarits.
\nPar exemple, si un gabarit foo.html contient {% load humanize %}, un gabarit enfant (c’est-à-dire un gabarit contenant {% extends "foo.html" %}) n’aura pas accès aux balises et filtres de gabarit de humanize. Le gabarit enfant est responsable de charger lui-même {% load humanize %}.
C’est un comportement volontaire pour une meilleure maintenance et propreté du code.
\n\n