Le langage de gabarit de Django

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.

Le 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.

Philosophie

Si vous avez un arrière-plan de programmation ou que vous êtes habitué aux langages qui mélangent le code de programmation directement dans le code HTML, vous devrez garder à l’esprit que le système des gabarits de Django n’est pas simplement du code Python intégré dans du code HTML. C’est un concept volontaire : le système des gabarits est conçu pour exprimer de la présentation, et non pas de la logique de programmation.

Le système des gabarits de Django fournit des balises dont les fonctions sont semblables à certaines structures de programmation (une balise if pour les tests booléens, une balise for pour les boucles, etc.), mais celles-ci ne sont pas simplement exécutées comme le code Python correspondant ; le système des gabarits de Django n’exécute pas n’importe quelle expression Python. Seuls les balises, les filtres et la syntaxe présentés ci-dessous sont pris en charge par défaut (même si vous pouvez ajouter vos propres extensions au langage de gabarit selon vos besoins).

Gabarits

Un gabarit est un fichier texte. Il peut générer tout format basé sur du texte (HTML, XML, CSV, etc.).

Un 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.

Voici un gabarit minimal illustrant quelques principes de base. Chaque élément sera ensuite expliqué plus loin dans ce document.

{% extends "base_generic.html" %}

{% block title %}{{ section.title }}{% endblock %}

{% block content %}
<h1>{{ section.title }}</h1>

{% for story in story_list %}
<h2>
  <a href="{{ story.get_absolute_url }}">
    {{ story.headline|upper }}
  </a>
</h2>
<p>{{ story.tease|truncatewords:"100" }}</p>
{% endfor %}
{% endblock %}

Philosophie

Pourquoi utiliser des gabarits basés sur du texte plutôt qu’en XML (comme le langage TAL de Zope) ? Nous avons souhaité que le langage de gabarit de Django ne soit pas uniquement utilisable pour des gabarits XML/HTML. Vous pouvez utiliser le langage de gabarit pour tout format basé sur du texte, tel que des courriels, du JavaScript ou du CSV.

Variables

Les 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.

En coulisses

Techniquement, lorsque le système de gabarits rencontre un point, il essaie les méthodes d’accès suivantes, dans l’ordre :

• Consultation de dictionnaire
• Consultation d’attribut ou de méthode
• Consultation d’indice numérique

Si la valeur résultante est exécutable, elle est appelée sans paramètre. Le résultat de l’appel devient la valeur de gabarit.

Cet ordre de consultation peut aboutir à un comportement inattendu avec des objets qui surchargent la consultation de dictionnaire. Par exemple, considérez l’extrait de code suivant qui essaie de faire une boucle sur un objet collections.defaultdict:

{% for k, v in defaultdict.items %}
    Do something with k and v here...
{% endfor %}

Comme la consultation de dictionnaire s’effectue en premier, c’est ce qui arrive ici et une valeur par défaut en résulte au lieu de la méthode .items() attendue. Dans ce cas, il faut envisager de convertir l’objet en dictionnaire simple au préalable.

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.

Filtres

Vous pouvez modifier l’affichage des variables en utilisant des filtres.

Les 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 :

default

Si 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 :

{{ value|default:"nothing" }}

Si value n’est pas fournie ou qu’elle est vide, le code ci-dessus affiche « nothing ».

length

Renvoie la longueur de la valeur. Cela fonctionne aussi bien pour du texte que des listes. Par exemple :

{{ value|length }}

Si value vaut ['a', 'b', 'c', 'd'], le résultat sera 4.

filesizeformat

Met 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 }}

SI 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.

Vous pouvez aussi créer vos propres filtres de gabarit ; voir Création de balises et filtres de gabarit personnalisés.

Voir aussi

L’interface d’administration de Django peut inclure une référence complète de tous les filtres et balises de gabarit disponibles pour un site donné. Voir Le générateur de documentation de l’administration de Django.

Balises

Les balises (tags en anglais) ressemblent à ceci : {% tag %}. Les balises sont plus complexes que les variables : certaines produisent du texte, d’autres contrôlent le flux en effectuant des boucles ou de la logique, et d’autres encore chargent des informations externes dans les gabarits pour que des variables puissent les utiliser ensuite.

Certains balises nécessitent une balise ouvrante et une balise fermante (par ex. {% tag %} ... contenu de la balise ... {% endtag %}).

Django fournit une vingtaine de balises de gabarit intégrées. Elles sont toutes documentées dans la référence des balises intégrées. Pour vous donner une idée de ce qui est disponible, voici quelques-unes des balises de gabarit les plus utilisées :

for

Boucle sur chaque élément d’une liste. Par exemple, pour afficher la liste des athlètes contenus dans athlete_list:

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% endfor %}
</ul>

if, elif et else

Évalue une variable, et si cette variable vaut True, le contenu du bloc est affiché :

{% if athlete_list %}
    Number of athletes: {{ athlete_list|length }}
{% elif athlete_in_locker_room_list %}
    Athletes should be out of the locker room soon!
{% else %}
    No athletes.
{% endif %}

Dans l’exemple ci-dessus, si athlete_list n’est pas vide, le nombre d’athlètes est affiché par la variable {{ athlete_list|length }}. Sinon, dans le cas où athlete_in_locker_room_list n’est pas vide, le message « Athletes should be out… » sera affiché. Si les deux listes sont vides, c’est « No athletes. » qui sera affiché.

Vous pouvez également utiliser des filtres et différents opérateurs dans la balise if:

{% if athlete_list|length > 1 %}
   Team: {% for athlete in athlete_list %} ... {% endfor %}
{% else %}
   Athlete: {{ athlete_list.0.name }}
{% endif %}

Même si l’exemple ci-dessus fonctionne, il faut savoir que la plupart des filtres de gabarit renvoient du texte, et que donc les comparaisons mathématiques impliquant des filtres fonctionnent rarement comme prévu. length est une exception.

block et extends

Définit l”héritage de gabarits (voir ci-dessous), une manière puissante d’éliminer les contenus redondants au niveau des gabarits.

Les exemples ci-dessus ne sont qu’une sélection de la liste complète ; voir la référence des balises intégrées pour une liste complète.

Vous pouvez aussi créer vos propres balises de gabarit ; voir Création de balises et filtres de gabarit personnalisés.

Voir aussi

L’interface d’administration de Django peut inclure une référence complète de tous les filtres et balises de gabarit disponibles pour un site donné. Voir Le générateur de documentation de l’administration de Django.

Commentaires

Pour commenter une partie de ligne dans un gabarit, utilisez la syntaxe de commentaire : {# #}.

Par exemple, ce gabarit produit le contenu 'hello':

{# greeting #}hello

Un commentaire peut contenir n’importe quel code de gabarit, valide ou non. Par exemple :

{# {% if foo %}bar{% else %} #}

Cette 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.

Héritage de gabarits

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.

Examinons l’héritage des gabarits en commençant par un exemple :

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="style.css">
    <title>{% block title %}My amazing site{% endblock %}</title>
</head>

<body>
    <div id="sidebar">
        {% block sidebar %}
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
        {% endblock %}
    </div>

    <div id="content">
        {% block content %}{% endblock %}
    </div>
</body>
</html>

Ce 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 :

{% extends "base.html" %}

{% block title %}My amazing blog{% endblock %}

{% block content %}
{% for entry in blog_entries %}
    <h2>{{ entry.title }}</h2>
    <p>{{ entry.body }}</p>
{% endfor %}
{% endblock %}

La 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>
<html lang="en">
<head>
    <link rel="stylesheet" href="style.css">
    <title>My amazing blog</title>
</head>

<body>
    <div id="sidebar">
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
    </div>

    <div id="content">
        <h2>Entry one</h2>
        <p>This is my first entry.</p>

        <h2>Entry two</h2>
        <p>This is my second entry.</p>
    </div>
</body>
</html>

Notez 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 :

• Cré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.

Voici quelques astuces concernant l’héritage :

• Si 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 %}
  {% block content %}{{ title }}{% endblock %}
  

• Pour une meilleure lisibilité, vous pouvez donner un nom à votre balise {% endblock %}. Par exemple :

  {% block content %}
  ...
  {% endblock content %}
  

  Dans 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 %}
      {% block title %}Hello!{% endblock title %}
  {% endif %}
  

Pour 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.

Échappement HTML automatique

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 :

Hello, {{ name }}

Au 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 :

<script>alert('hello')</script>

Avec cette valeur pour le nom, le gabarit serait produit comme ceci :

Hello, <script>alert('hello')</script>

… ce qui signifie que le navigateur afficherait une fenêtre d’alerte JavaScript !

De la même manière, que se passe-t-il si le nom contient un symbole '<' comme ceci ?

<b>username

Cela aboutit à l’affichage d’un résultat de gabarit comme ceci :

Hello, <b>username

…ce qui ferait que tout le reste de la page web serait affiché en gras !

Clairement, 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).

Pour éviter ce problème, vous avez deux options :

• Premiè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 :

• < 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é.

Comment désactiver l’échappement automatique

Si 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.

Pourquoi 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.

Pour des variables individuelles

Pour désactiver l’échappement automatique pour une variable individuelle, utilisez le filtre safe:

This will be escaped: {{ data }}
This will not be escaped: {{ data|safe }}

safe (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>
This will not be escaped: <b>

Pour des blocs de gabarits

Pour contrôler l’échappement automatique dans un gabarit, entourez le gabarit (ou une portion du gabarit) par la balise autoescape, comme ceci :

{% autoescape off %}
    Hello {{ name }}
{% endautoescape %}

La 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 }}

{% autoescape off %}
    This will not be auto-escaped: {{ data }}.

    Nor this: {{ other_data }}
    {% autoescape on %}
        Auto-escaping applies again: {{ name }}
    {% endautoescape %}
{% endautoescape %}

La 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 %}
<h1>{% block title %}{% endblock %}</h1>
{% block content %}
{% endblock %}
{% endautoescape %}

child.html

{% extends "base.html" %}
{% block title %}This & that{% endblock %}
{% block content %}{{ greeting }}{% endblock %}

Comme 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 &amp; that</h1>
<b>Hello!</b>

Notes

Gé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.

Si 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.

Texte littéral et échappement automatique

Comme mentionné précédemment, les paramètres de filtres peuvent être des chaînes de caractères :

{{ data|default:"This is a string literal." }}

Tout 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 :

{{ data|default:"3 < 2" }}

…et non pas :

{{ data|default:"3 < 2" }}  {# Bad! Don't do this. #}

Cela 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.

Accès aux appels de méthodes

La 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 :

{% for comment in task.comment_set.all %}
    {{ comment }}
{% endfor %}

De 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 }}

Vous pouvez aussi accéder aux méthodes que vous avez explicitement définies pour vos propres modèles :

models.py

class Task(models.Model):
    def foo(self):
        return "bar"

template.html

{{ task.foo }}

Comme 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.

Bibliothèques de balises et filtres personnalisés

Certaines 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 %}

{{ 45000|intcomma }}

Ci-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 %}

Consultez Création de balises et filtres de gabarit personnalisés pour obtenir des informations sur l’écriture de vos propres bibliothèques de gabarits.

Bibliothèques personnalisées et héritage de gabarits

Lorsque 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.

Par 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.

Voir aussi

La référence des gabarits

Documente les balises et filtres intégrés, l’utilisation d’un langage de gabarit alternatif, et d’autres choses encore.