Balises et filtres de gabarit intégrés¶
Ce document décrit les balises et les filtres de gabarit intégrés dans Django. Il est recommandé d’utiliser la documentation automatique, si disponible, car elle inclura aussi la documentation de tout filtre ou balise personnalisé potentiellement installé.
Référence des balises intégrées¶
autoescape¶
Contrôle le comportement actuel de l’échappement automatique. Cette balise accepte on ou off comme paramètre et cela détermine si l’échappement automatique est actif dans le bloc concerné. Le bloc doit être fermé par la balise fermante endautoescape.
Exemple d’utilisation :
{% autoescape on %}
{{ body }}
{% endautoescape %}
Lorsque l’échappement automatique est actif, tout contenu dérivé de variables est soumis à l’échappement HTML avant d’être affiché (mais après l’application de filtres éventuels). C’est équivalent à l’application manuelle du filtre escape à chaque variable.
Les seules exceptions sont les variables qui sont déjà marquées comme «sûres» quant à l’échappement. Ce marquage pourrait avoir été appliqué par le code qui a défini la variable, par l’utilisation des filtres safe ou escape, ou encore par le fait qu’il s’agit d’un résultat d’un filtre précédent ayant marqué la chaîne comme «sûre».
Dans le contexte de la désactivation de l’échappement automatique, le chaînage de filtres, y compris escape, peut aboutir à des résultats inattendus (mais documentés) comme dans l’exemple suivant :
{% autoescape off %}
{{ my_list|join:", "|escape }}
{% endautoescape %}
Le code ci-dessus joindra les éléments de my_list sans échappement. La raison en est que la séquence de la chaîne de filtres exécute d’abord join sur my_list (sans appliquer d’échappement à chacun de ses éléments car autoescape est désactivé (off)), et marque le résultat comme sûr. Ensuite, ce résultat sûr sera transmis au filtre escape qui n’applique pas d’échappement supplémentaire à du contenu considéré comme déjà sûr.
Afin d’échapper proprement chaque élément d’une séquence, utilisez le filtre escapeseq:
{% autoescape off %}
{{ my_list|escapeseq|join:", " }}
{% endautoescape %}
block¶
Définit un bloc pouvant être surchargé par les gabarits enfants. Voir Héritage des gabarits pour plus d’informations.
comment¶
Ignore tout ce qui se trouve entre {% comment %} et {% endcomment %}. Une note facultative peut être insérée dans la première balise. Par exemple, cela peut être utile pour donner les raisons d’un bout de code que l’on place en commentaire.
Exemple d’utilisation :
<p>Rendered text with {{ pub_date|date:"c" }}</p>
{% comment "Optional note" %}
<p>Commented out text with {{ create_date|date:"c" }}</p>
{% endcomment %}
Les balises comment ne peuvent pas être imbriquées.
csrf_token¶
Cette balise est utilisée pour la protection CSRF, comme décrit dans la documentation Cross Site Request Forgeries.
cycle¶
Affiche l’un de ses paramètres à chaque apparition de la balise. Le premier paramètre est affiché lors de la première apparition, le second paramètre lors de la seconde apparition, et ainsi de suite. Une fois que tous les paramètres ont été utilisés, la balise recommence avec le premier paramètre et l’affiche de nouveau.
Cette balise est particulièrement utile dans une boucle :
{% for o in some_list %}
<tr class="{% cycle 'row1' 'row2' %}">
...
</tr>
{% endfor %}
La première itération produit du code HTML se référant à la classe row1, la deuxième à row2, la troisième de nouveau à row1 et ainsi de suite pour chaque itération de la boucle.
Vous pouvez aussi utiliser des variables. Par exemple, si vous avez deux variables de gabarit, rowvalue1 et rowvalue2, vous pouvez alterner entre leurs valeurs comme ceci :
{% for o in some_list %}
<tr class="{% cycle rowvalue1 rowvalue2 %}">
...
</tr>
{% endfor %}
Les variables incluses dans le cycle seront échappées. Vous pouvez désactiver l’échappement automatique avec :
{% for o in some_list %}
<tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}">
...
</tr>
{% endfor %}
Vous pouvez mélanger des variables et des chaînes :
{% for o in some_list %}
<tr class="{% cycle 'row1' rowvalue2 'row3' %}">
...
</tr>
{% endfor %}
Dans certains cas, il peut être souhaitable de se référer à la valeur actuelle du cycle sans passer à la valeur suivante. Pour cela, donnez un nom à la balise {% cycle %} via « as », comme ceci :
{% cycle 'row1' 'row2' as rowcolors %}
À partir de cet instance, vous pouvez insérer la valeur actuelle du cycle chaque fois que vous en avez besoin dans votre gabarit en vous référant au nom du cycle comme variable de contexte. Si vous souhaitez faire passer le cycle à la prochaine valeur indépendamment de la balise cycle d’origine, vous pouvez utiliser une autre balise cycle et indiquer le nom de la variable. Ainsi, le gabarit suivant :
<tr>
<td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td>
<td class="{{ rowcolors }}">...</td>
</tr>
<tr>
<td class="{% cycle rowcolors %}">...</td>
<td class="{{ rowcolors }}">...</td>
</tr>
affichera :
<tr>
<td class="row1">...</td>
<td class="row1">...</td>
</tr>
<tr>
<td class="row2">...</td>
<td class="row2">...</td>
</tr>
Vous pouvez utiliser autant de valeurs que nécessaire dans une balise cycle, séparées par des espaces. Les valeurs entourées de guillemets simples (') ou doubles (") sont traitées comme des chaînes littérales, alors que les valeurs sans guillemets sont traitées comme des variables de gabarit.
Par défaut, lorsque vous utilisez le mot-clé as avec la balise cycle, l’utilisation de {% cycle %} qui démarre le cycle produira elle-même la première valeur du cycle. Cela peut poser problème si vous souhaitez exploiter la valeur dans une boucle imbriquée ou un gabarit inclus. Si vous ne voulez que déclarer le cycle mais sans produire la première valeur, vous pouvez ajouter un mot-clé silent comme dernier mot-clé de la balise. Par exemple :
{% for obj in some_list %}
{% cycle 'row1' 'row2' as rowcolors silent %}
<tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr>
{% endfor %}
Ceci va afficher une liste d’éléments <tr> avec l’attribut class alternant entre row1 et row2. Le sous-gabarit aura accès à rowcolors dans son contexte et sa valeur correspondra à la valeur de class de la balise <tr> qui l’entoure. Si on avait omis d’ajouter le mot-clé silent, row1 et row2 auraient été affichés comme du texte normal, en dehors de l’élément <tr>.
Lorsque le mot-clé silent est utilisé dans une définition de cycle, cela s’applique automatiquement à toutes les utilisations ultérieures de cette balise cycle spécifique. Le gabarit suivant n’affiche rien, même si le second appel à {% cycle %} ne précise pas silent:
{% cycle 'row1' 'row2' as rowcolors silent %}
{% cycle rowcolors %}
Il est possible d’utiliser la balise resetcycle pour réinitialiser une balise {% cycle %} à sa première valeur lors de sa prochaine apparition.
debug¶
Affiche un gros bloc d’informations de débogage, y compris le contexte actuel et les modules importés. {% debug %} n’affiche rien lorsque le réglage DEBUG vaut False.
extends¶
Indique que ce gabarit étend un gabarit parent.
Cette balise peut être utilisée de deux façons :
{% extends "base.html" %}(avec guillemets) utilise la valeur littérale"base.html"comme nom du gabarit parent à étendre.{% extends variable %}utilise la valeur devariable. Si la variable contient une chaîne de caractères, Django utilise celle-ci comme nom du gabarit parent. Si la variable contient un objetTemplate, Django utilise cet objet comme gabarit parent.
Voir Héritage de gabarits pour plus d’informations.
En principe, le nom du gabarit est relatif au répertoire racine du chargeur de gabarits. Un paramètre textuel peut aussi être un chemin relatif commençant par ./ ou ../. Par exemple, en admettant la structure de répertoires suivante :
dir1/
template.html
base2.html
my/
base3.html
base1.html
Dans template.html, les chemins suivants seraient valides :
{% extends "./base2.html" %}
{% extends "../base1.html" %}
{% extends "./my/base3.html" %}
filter¶
Filtre le contenu du bloc au travers d’un ou plusieurs filtres. Plusieurs filtres doivent être séparés par la barre verticale et les filtres peuvent posséder des paramètres, tout comme dans la syntaxe des variables.
Notez que le bloc inclus tout le texte entre les balises filter et endfilter.
Exemple d’utilisation :
{% filter force_escape|lower %}
This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}
Note
Les filtres escape et safe ne sont pas des paramètres acceptables. Vous pouvez toujours utiliser la balise autoescape pour gérer l’échappement automatique dans des blocs de code de gabarit.
firstof¶
Affiche le premier paramètre qui ne vaut pas « faux » (c’est-à-dire qu’il existe, qu’il n’est pas vide, qu’il ne contient pas la valeur booléenne faux et qu’il ne contient pas la valeur numérique 0). N’affiche rien si toutes les valeurs transmises valent « faux ».
Exemple d’utilisation :
{% firstof var1 var2 var3 %}
C’est l’équivalent de :
{% if var1 %}
{{ var1 }}
{% elif var2 %}
{{ var2 }}
{% elif var3 %}
{{ var3 }}
{% endif %}
Vous pouvez aussi utiliser une chaîne littérale comme valeur de repli dans le cas où toutes les variables spécifiées valent False:
{% firstof var1 var2 var3 "fallback value" %}
Cette balise échappe automatiquement les valeurs des variables. Vous pouvez désactiver l’échappement automatique avec :
{% autoescape off %}
{% firstof var1 var2 var3 "<strong>fallback value</strong>" %}
{% endautoescape %}
Ou si seulement certaines variables doivent être échappées, vous pouvez employer :
{% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %}
Vous pouvez utiliser la syntaxe {% firstof var1 var2 var3 as value %} pour stocker le résultat dans une variable.
for¶
Effectue une boucle sur chaque élément d’une liste, rendant disponible la valeur dans une variable de contexte. Par exemple, pour afficher une liste des athlètes contenus dans athlete_list:
<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
</ul>
Vous pouvez effectuer une boucle inversée sur une liste en utilisant {% for obj in list reversed %}`.
Si vous devez effectuer une boucle sur une liste de listes, vous pouvez isoler les valeurs de chaque sous-liste dans des variables individuelles. Par exemple, si votre contexte contient une liste de coordonnées (x, y) appelée points, voici comment vous pouvez afficher la liste des points :
{% for x, y in points %}
There is a point at {{ x }},{{ y }}
{% endfor %}
Cela peut aussi être utile si vous avez besoin d’accéder aux éléments d’un dictionnaire. Par exemple, si votre contexte contient un dictionnaire data, le code suivant affiche les clés et les valeurs de ce dictionnaire :
{% for key, value in data.items %}
{{ key }}: {{ value }}
{% endfor %}
N’oubliez pas que pour l’opérateur point, la recherche de clé de dictionnaire est prioritaire par rapport à la recherche de méthode. Ainsi, si le dictionnaire data contient une clé nommée 'items', data.items renvoie data['items'] au lieu de data.items(). Évitez d’ajouter des clés qui ont le même nom que des méthodes de dictionnaire si vous voulez utilisez ces méthodes dans les gabarits (items, values, keys, etc.). Vous trouverez plus de détails sur l’ordre de recherche de l’opérateur point dans la documentation des variables de gabarit.
La boucle for définit un certain nombre de variables disponibles à l’intérieur de la boucle :
Variable |
Description |
|---|---|
|
L’itération actuelle de la boucle (index à partir de 1) |
|
L’itération actuelle de la boucle (index à partir de 0) |
|
Le nombre d’itérations à partir de la fin de la boucle (index à partir de 1) |
|
Le nombre d’itérations à partir de la fin de la boucle (index à partir de 0) |
|
|
|
|
|
Pour les boucles imbriquées, il s’agit de la boucle de niveau supérieur |
for … empty¶
La balise for accepte une clause facultative {% empty %} dont le contenu est affiché si la liste en paramètre est vide ou est introuvable :
<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% empty %}
<li>Sorry, no athletes in this list.</li>
{% endfor %}
</ul>
Le code ci-dessus est équivalent, mais plus court, plus propre et peut-être plus rapide que ceci :
<ul>
{% if athlete_list %}
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
{% else %}
<li>Sorry, no athletes in this list.</li>
{% endif %}
</ul>
if¶
La balise {% if %} évalue une variable et si celle-ci vaut True (c’est-à-dire qu’elle existe, n’est pas vide et ne contient pas la valeur booléenne faux), 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 }}.
Comme vous pouvez le voir, la balise if accepte une ou plusieurs clauses {% elif %} ou une clause {% else %} dont le contenu est affiché si toutes les conditions précédentes ont échoué. Ces clauses sont facultatives.
Opérateurs booléens¶
Les balises if peuvent utiliser and (et), or (ou) ou not (non) pour tester un certain nombre de variables ou pour inverser la valeur d’une variable donnée :
{% if athlete_list and coach_list %}
Both athletes and coaches are available.
{% endif %}
{% if not athlete_list %}
There are no athletes.
{% endif %}
{% if athlete_list or coach_list %}
There are some athletes or some coaches.
{% endif %}
{% if not athlete_list or coach_list %}
There are no athletes or there are some coaches.
{% endif %}
{% if athlete_list and not coach_list %}
There are some athletes and absolutely no coaches.
{% endif %}
L’utilisation à la fois de and et de or dans la même balise est permise, tenant compte que and a une plus grande priorité que or. Par exemple :
{% if athlete_list and coach_list or cheerleader_list %}
sera interprété comme :
if (athlete_list and coach_list) or cheerleader_list:
...
L’emploi de parenthèses dans la balise if est une erreur de syntaxe. Si vous en avez besoin pour modifier la priorité des opérateurs, vous devez passer par des balises if imbriquées.
Les balises if peuvent également utiliser les opérateurs ==, !=, <, >, <=, >=, in (dans), not in, is et is not qui fonctionnent comme suit :
Opérateur ==¶
Égalité. Exemple :
{% if somevar == "x" %}
This appears if variable somevar equals the string "x"
{% endif %}
Opérateur !=¶
Inégalité. Exemple :
{% if somevar != "x" %}
This appears if variable somevar does not equal the string "x",
or if somevar is not found in the context
{% endif %}
Opérateur <¶
Inférieur à. Exemple :
{% if somevar < 100 %}
This appears if variable somevar is less than 100.
{% endif %}
Opérateur >¶
Supérieur à. Exemple :
{% if somevar > 0 %}
This appears if variable somevar is greater than 0.
{% endif %}
Opérateur <=¶
Inférieur ou égal à. Exemple :
{% if somevar <= 100 %}
This appears if variable somevar is less than 100 or equal to 100.
{% endif %}
Opérateur >=¶
Supérieur ou égal à. Exemple :
{% if somevar >= 1 %}
This appears if variable somevar is greater than 1 or equal to 1.
{% endif %}
Opérateur in¶
Contenu dans. Cet opérateur est pris en charge par de nombreux conteneurs Python pour tester si la valeur donnée se trouve dans le conteneur. Le code suivant montre quelques exemples d’interprétation de x in y:
{% if "bc" in "abcdef" %}
This appears since "bc" is a substring of "abcdef"
{% endif %}
{% if "hello" in greetings %}
If greetings is a list or set, one element of which is the string
"hello", this will appear.
{% endif %}
{% if user in users %}
If users is a QuerySet, this will appear if user is an
instance that belongs to the QuerySet.
{% endif %}
Opérateur not in¶
Non contenu dans. C’est la négation de l’opérateur in.
Opérateur is¶
Identité d’objet. Teste si deux valeurs sont le même objet. Exemple :
{% if somevar is True %}
This appears if and only if somevar is True.
{% endif %}
{% if somevar is None %}
This appears if somevar is None, or if somevar is not found in the context.
{% endif %}
Opérateur is not¶
Négation d’identité d’objet. Teste si deux valeurs ne sont pas le même objet. C’est la négation de l’opérateur is. Exemple :
{% if somevar is not True %}
This appears if somevar is not True, or if somevar is not found in the
context.
{% endif %}
{% if somevar is not None %}
This appears if and only if somevar is not None.
{% endif %}
Filtres¶
Vous pouvez aussi utiliser des filtres dans l’expression if. Par exemple :
{% if messages|length >= 100 %}
You have lots of messages today!
{% endif %}
Expressions complexes¶
Tous les éléments ci-dessus peuvent être combinés pour former des expressions complexes. Pour de telles expressions, il peut être important de savoir comment les opérateurs sont groupés au moment de l’évaluation de l’expression, c’est-à-dire les règles de priorité appliquées. La priorité des opérateurs, de la plus faible à la plus élevée, est dans cet ordre :
orandnotin==,!=,<,>,<=,>=
(Ceci suit exactement le comportement Python). Ainsi, par exemple, la balise if complexe suivante :
{% if a == b or c == d and e %}
…sera interprétée comme :
(a == b) or ((c == d) and e)
Si vous devez modifier la priorité, il faudra imbriquer les balises if. C’est parfois plus lisible aussi, notamment pour ceux qui ne sont pas très au clair au sujet des règles de priorité.
Les opérateurs de comparaison ne peuvent pas être enchaînés comme en Python ou en notation mathématique. Par exemple, au lieu d’écrire :
{% if a > b > c %} (WRONG)
vous devez écrire :
{% if a > b and b > c %}
ifchanged¶
Vérifie si une valeur a changé depuis l’itération précédente d’une boucle.
La balise de bloc {% ifchanged %} est employée dans une boucle. Elle présente deux utilisations possibles.
Vérifie son propre contenu à afficher comparé à son état précédent et n’affiche le contenu que s’il a changé. Par exemple, le code suivant affiche une liste de jours, n’affichant le mois que lorsqu’il change :
<h1>Archive for {{ year }}</h1> {% for date in days %} {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %} <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a> {% endfor %}
Si la balise reçoit une ou plusieurs variables, elle vérifie si l’une des variables a changé. Par exemple, le code suivant affiche la date chaque fois qu’elle change et n’affiche l’heure que si l’heure ou la date a changé :
{% for date in days %} {% ifchanged date.date %} {{ date.date }} {% endifchanged %} {% ifchanged date.hour date.date %} {{ date.hour }} {% endifchanged %} {% endfor %}
La balise ifchanged accepte aussi une clause facultative {% else %} qui affiche son contenu si la valeur n’a pas changé :
{% for match in matches %}
<div style="background-color:
{% ifchanged match.ballot_id %}
{% cycle "red" "blue" %}
{% else %}
gray
{% endifchanged %}
">{{ match }}</div>
{% endfor %}
include¶
Charge un gabarit et l’affiche avec le contexte en cours. C’est une manière d’inclure d’autres gabarits dans un gabarit.
Le nom du gabarit peut être soit une variable, soit une chaîne fixe entre guillemets, simples ou doubles.
Cet exemple inclut le contenu du gabarit "foo/bar.html":
{% include "foo/bar.html" %}
En principe, le nom du gabarit est relatif au répertoire racine du chargeur de gabarits. Un paramètre textuel peut aussi être un chemin relatif commençant par ./ ou ../, comme expliqué dans la documentation de la balise extends.
Cet exemple inclut le contenu du gabarit dont le nom est contenu dans la variable template_name:
{% include template_name %}
La variable peut aussi être tout objet possédant une méthode render() acceptant un contexte. Cela permet de référencer un objet Template compilé dans votre contexte.
De plus, la variable peut être un itérable de noms de gabarits, auquel cas le premier pouvant être chargé sera utilisé, selon select_template().
Un gabarit inclus est affiché dans le contexte du gabarit qui l’inclut. Cet exemple produit le résultat "Hello, John!":
Contexte : la variable
personcontient"John"et la variablegreetingcontient"Hello".Gabarit :
{% include "name_snippet.html" %}
Le gabarit
name_snippet.html:{{ greeting }}, {{ person|default:"friend" }}!
Vous pouvez transmettre du contexte supplémentaire au gabarit en utilisant des paramètres nommés :
{% include "name_snippet.html" with person="Jane" greeting="Hello" %}
Si vous souhaitez rendre le contexte avec seulement les variables indiquées (ou même sans variable du tout), utilisez l’option only. Aucune autre variable n’est alors disponible dans le gabarit inclus :
{% include "name_snippet.html" with greeting="Hi" only %}
Note
La balise include doit être considérée comme une implémentation de « effectuer le rendu de ce sous-gabarit et inclure le HTML résultant », et non pas « analyser ce sous-gabarit et inclure son contenu comme s’il faisait partie du parent ». Cela signifie qu’il n’y a pas d’état partagé entre les gabarits inclus, chaque inclusion faisant l’objet d’un processus de rendu totalement autonome.
Les blocs sont évalués avant d’être inclus. Cela signifie qu’un gabarit qui inclut des blocs d’un autre contiendra des blocs qui ont déjà été évalués et produits, et non pas des blocs qui peuvent être surchargés, par exemple par un gabarit d’extension.
load¶
Charge un lot de balises de gabarit personnalisées.
Par exemple, le gabarit suivant charge toutes les balises et tous les filtres enregistrés dans somelibrary et dans otherlibrary se trouvant dans le paquet package:
{% load somelibrary package.otherlibrary %}
Vous pouvez aussi charger de manière sélective des filtres ou des balises à partir d’une bibliothèque avec le paramètre from. Dans cet exemple, les balises/filtres de gabarit foo et bar sont chargés à partir de somelibrary:
{% load foo bar from somelibrary %}
Voir Bibliothèques de balises et de filtres personnalisés pour plus d’informations.
lorem¶
Affiche du texte latin aléatoire « lorem ipsum ». C’est pratique pour produire des données d’exemple dans les gabarits.
Utilisation :
{% lorem [count] [method] [random] %}
La balise {% lorem %} peut être utilisée avec zéro, un, deux ou trois paramètres. Ces paramètres sont :
Paramètre |
Description |
|---|---|
|
Un nombre (ou une variable) contenant le nombre de paragraphes ou de mots à produire (1 par défaut). |
|
Indiquez |
|
Le mot |
Exemples :
{% lorem %}produit le paragraphe habituel « lorem ipsum ».{% lorem 3 p %}produit le paragraphe habituel « lorem ipsum » ainsi que deux paragraphes aléatoires, tous insérés dans des balises HTML<p>.{% lorem 2 w random %}produit deux mots latins aléatoires.
now¶
Affiche l’heure ou la date actuelle, en utilisant un format correspondant à la chaîne donnée. Cette chaîne peut contenir des spécificateurs de format comme décrit dans la section du filtre date.
Exemple :
It is {% now "jS F Y H:i" %}
Notez que vous pouvez échapper par barre oblique inverse une chaîne de format si vous souhaitez utiliser la valeur « brute ». Dans cet exemple, « f » et « o » sont tous deux échappés par barre oblique inverse, sinon ils seraient chacun interprétés comme une chaîne de format pour afficher respectivement l’année et l’heure :
It is the {% now "jS \o\f F" %}
Le résultat affiché est « It is the 4th of September ».
Note
Le format indiqué peut aussi correspondre à l’un des formats prédéfinis DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT ou SHORT_DATETIME_FORMAT. Les formats prédéfinis peuvent varier en fonction de la langue active et de l’activation de la Régionalisation des formats, par ex. :
It is {% now "SHORT_DATETIME_FORMAT" %}
Vous pouvez également utiliser la syntaxe {% now "Y" as current_year %} pour stocker le résultat dans une variable (une chaîne de caractères). Cela peut être utile lorsqu’on veut utiliser {% now %} dans une balise de gabarit telle que blocktranslate par exemple :
{% now "Y" as current_year %}
{% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %}
querystring¶
Produit une chaîne de requête codée pour les URL sur la base des paramètres fournis.
Cette balise nécessite une instance QueryDict qui est par défaut request.GET si aucune autre n’est indiquée.
Si le contenu QueryDict est vide et qu’aucun paramètre supplémentaire n’est fourni, une chaîne vide est renvoyée. Tout résultat non vide commencera toujours par "?".
Utilisation de request.GET comme valeur par défaut
Pour utiliser request.GET comme instance QueryDict par défaut, le processeur de contexte django.template.context_processors.request doit être actif. Sinon, vous devez soit passer explicitement un objet request dans le contexte du gabarit, soit fournir une instance QueryDict en appelant cette balise.
Utilisation de base¶
{% querystring %}
Produit la chaîne de requête actuelle telle quelle. Donc si la chaîne de requête est ?couleur=vert, le résultat sera aussi ?couleur=vert.
{% querystring size="M" %}
Produit la chaîne de requête actuelle en y ajoutant le paramètre size. En reprenant l’exemple précédent, le résultat sera ?couleur=vert&size=M.
QueryDict personnalisé¶
{% querystring my_query_dict %}
Vous pouvez indiquer un objet QueryDict personnalisé à utiliser à la place de request.GET. Donc si mon_query_dict est <QueryDict: {'couleur': ['bleu']}>, le résultat sera ?couleur=bleu.
Définition d’éléments¶
{% querystring color="red" size="S" %}
Ajoute ou modifie des paramètres dans la chaîne de requête. Chaque argument nommé sera ajouté à la chaîne de requête, remplaçant toute valeur éventuelle existante pour cette clé. Par exemple, si la chaîne de requête actuelle est ?color=green, le résultat sera ?color=red&size=S.
Suppression d’éléments¶
{% querystring color=None %}
En passant la valeur None, le paramètre en question est supprimé de la chaîne de requête. Par exemple, si la chaîne de requête actuelle est ?color=green&size=M, le résultat sera ?size=M.
Comportement avec des listes¶
{% querystring color=my_list %}
Si my_list est ["red", "blue"], le résultat sera ?color=red&color=blue, conservant la structure de la liste dans la chaîne de requête.
Utilisation dynamique¶
Un cas d’utilisation fréquent de cette balise est de préserver la chaîne de requête actuelle lors de l’affichage d’une page de résultats, tout en ajoutant un lien vers les pages de résultats précédente et suivante. Par exemple, si la pagination est actuellement sur la page 3 et que la chaîne de requête actuelle est ?color=blue&size=M&page=3, le code suivant produira ?color=blue&size=M&page=4:
{% querystring page=page.next_page_number %}
Il est également possible de stocker la valeur dans une variable. Par exemple, si vous avez besoin de plusieurs liens vers la même page, définissez la variable comme ceci :
{% querystring page=page.next_page_number as next_page %}
regroup¶
Regroupe une liste d’objets semblables par un attribut commun.
La meilleure façon d’illustrer cette balise complexe est de donner un exemple : disons que cities contient une liste de villes représentées par des dictionnaires contenant les clés "name", "population" et "country":
cities = [
{"name": "Mumbai", "population": "19,000,000", "country": "India"},
{"name": "Calcutta", "population": "15,000,000", "country": "India"},
{"name": "New York", "population": "20,000,000", "country": "USA"},
{"name": "Chicago", "population": "7,000,000", "country": "USA"},
{"name": "Tokyo", "population": "33,000,000", "country": "Japan"},
]
…et vous aimeriez afficher une liste hiérarchique triée par pays, comme ceci :
India
Mumbai: 19,000,000
Calcutta: 15,000,000
USA
New York: 20,000,000
Chicago: 7,000,000
Japan
Tokyo: 33,000,000
Vous pouvez utiliser la balise {% regroup %} pour grouper la liste des villes par pays. L’extrait de code de gabarit suivant effectue cela :
{% regroup cities by country as country_list %}
<ul>
{% for country in country_list %}
<li>{{ country.grouper }}
<ul>
{% for city in country.list %}
<li>{{ city.name }}: {{ city.population }}</li>
{% endfor %}
</ul>
</li>
{% endfor %}
</ul>
Parcourons cet exemple. {% regroup %} accepte trois paramètres : la liste que vous souhaitez regrouper, l’attribut sur lequel grouper et le nom de la liste résultante. Dans ce cas, nous regroupons la liste cities par l’attribut country et nommons le résultat country_list.
{% regroup %} produit une liste (dans ce cas, country_list) d”objets groupes. Les objets groupes sont des instances de namedtuple() contenant deux champs :
grouper, l’élément qui a servi au groupement (par ex. la chaîne « India » ou « Japan »).list, une liste de tous les éléments du groupe (par ex. une liste de toutes les villes ayantcountry='India').
Comme {% regroup %} produit des objets namedtuple(), il est également possible d’écrire l’exemple précédent comme ceci :
{% regroup cities by country as country_list %}
<ul>
{% for country, local_cities in country_list %}
<li>{{ country }}
<ul>
{% for city in local_cities %}
<li>{{ city.name }}: {{ city.population }}</li>
{% endfor %}
</ul>
</li>
{% endfor %}
</ul>
Notez que {% regroup %} ne trie pas ce qu’il reçoit ! Notre exemple compte sur le fait que la liste cities est préalablement triée par country. Si la liste cities n’était pas triée par pays, le regroupement aurait naïvement affiché plus d’un groupe par pays. Par exemple, si la liste cities contenait ceci (notez que les pays ne sont pas regroupés) :
cities = [
{"name": "Mumbai", "population": "19,000,000", "country": "India"},
{"name": "New York", "population": "20,000,000", "country": "USA"},
{"name": "Calcutta", "population": "15,000,000", "country": "India"},
{"name": "Chicago", "population": "7,000,000", "country": "USA"},
{"name": "Tokyo", "population": "33,000,000", "country": "Japan"},
]
Avec ce contenu dans cities, l’exemple de code de gabarit pour {% regroup %} ci-dessus produirait le résultat suivant :
India
Mumbai: 19,000,000
USA
New York: 20,000,000
India
Calcutta: 15,000,000
USA
Chicago: 7,000,000
Japan
Tokyo: 33,000,000
La solution la plus simple à ce problème est de s’assurer au niveau de la vue que les données sont triées d’après le critère que vous voulez utiliser pour l’affichage.
Un autre solution est de trier les données dans le gabarit avec le filtre dictsort, pour autant que les données soient constituées d’une liste de dictionnaires :
{% regroup cities|dictsort:"country" by country as country_list %}
Groupement selon d’autres propriétés¶
Toute consultation d’attribut acceptée dans les gabarits est utilisable comme attribut de groupement pour la balise regroup, y compris les méthodes, les attributs, les clés de dictionnaire et les éléments de liste. Par exemple, si le champ « country » est une clé étrangère vers une classe possédant un attribut « description », vous pourriez écrire :
{% regroup cities by country.description as country_list %}
Ou si country est un champ contenant des choix (choices), il disposera d’une méthode get_FOO_display() disponible comme attribut vous permettant de regrouper sur la chaîne visible plutôt que sur la clé du choix :
{% regroup cities by get_country_display as country_list %}
{{ country.grouper }} contient maintenant la partie valeur des choix choices plutôt que leur clé.
resetcycle¶
Réinitialise un cycle précédent afin qu’il recommence depuis son premier élément à la prochaine occurrence. Sans paramètre, {% resetcycle %} réinitialise le dernier {% cycle %} défini dans le gabarit.
Exemple d’utilisation :
{% for coach in coach_list %}
<h1>{{ coach.name }}</h1>
{% for athlete in coach.athlete_set.all %}
<p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>
{% endfor %}
{% resetcycle %}
{% endfor %}
Cet exemple produit le code HTML suivant :
<h1>Gareth</h1>
<p class="odd">Harry</p>
<p class="even">John</p>
<p class="odd">Nick</p>
<h1>John</h1>
<p class="odd">Andrea</p>
<p class="even">Melissa</p>
Remarquez comme le premier bloc se termine avec class="odd" et le nouveau qui commence avec class="odd". Sans la balise {% resetcycle %}, le second bloc aurait commencé avec class="even".
Il est aussi possible de réinitialiser les balises cycle nommées :
{% for item in list %}
<p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}">
{{ item.data }}
</p>
{% ifchanged item.category %}
<h1>{{ item.category }}</h1>
{% if not forloop.first %}{% resetcycle tick %}{% endif %}
{% endifchanged %}
{% endfor %}
Dans cet exemple, nous avons à la fois les lignes alternées pair/impair et une ligne « principale » toutes les cinq lignes. Seul le cycle des cinq lignes est réinitialisé lorsqu’une catégorie change.
spaceless¶
Supprime les espaces entre les balises HTML. Les caractères de tabulation et les sauts de ligne sont aussi considérés comme des espaces.
Exemple d’utilisation :
{% spaceless %}
<p>
<a href="foo/">Foo</a>
</p>
{% endspaceless %}
Cet exemple produit le code HTML suivant :
<p><a href="foo/">Foo</a></p>
Seuls les espaces entre les balises elles-mêmes sont supprimés, pas ceux entre les balises et le texte. Dans cet exemple, les espaces autour de Hello ne seront pas enlevés :
{% spaceless %}
<strong>
Hello
</strong>
{% endspaceless %}
templatetag¶
Affiche l’une des séquences de caractères utilisées dans la syntaxe des balises de gabarit.
Le système des gabarits n’a aucun concept d’échappement de caractères individuels. Vous pouvez cependant utiliser la balise {% templatetag %} pour afficher l’une des combinaisons de caractères des balises de gabarit.
Le paramètre indique quelle séquence de gabarit vous voulez afficher :
Paramètre |
Affiche |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Exemple d’utilisation :
The {% templatetag openblock %} characters open a block.
Voir aussi la balise verbatim pour une autre façon d’inclure ces caractères.
url¶
Renvoie un référence de chemin absolu (une URL sans le nom de domaine) correspondant à une vue et des paramètres facultatifs. Tout caractère spécial dans le chemin résultant sera codé avec iri_to_uri().
C’est une manière d’afficher des liens sans trahir le principe DRY (« ne pas se répéter »), évitant de devoir figer les URL dans les gabarits :
{% url 'some-url-name' v1 v2 %}
Le premier paramètre est un nom de motif d’URL. Cela peut être une chaîne littérale entre guillemets ou une variable de contexte. Des paramètres supplémentaires sont facultatifs et sont fournis sous forme de valeurs séparées par des espaces qui seront utilisées comme paramètres de l’URL. L’exemple ci-dessus montre comment passer des paramètres positionnels. Il est aussi possible d’utiliser la syntaxe par mot-clé :
{% url 'some-url-name' arg1=v1 arg2=v2 %}
Ne mélangez pas la syntaxe positionnelle avec la syntaxe par mot-clé dans le même appel. Tous les paramètres requis par la configuration d’URL doivent être présents.
Par exemple, supposons que vous avez une vue, app_views.client, dont la configuration d’URL accepte un identifiant de client (ici, client() est une méthode dans le fichier de vues app_views.py). La ligne de configuration d’URL pourrait ressembler à ceci :
path("client/<int:id>/", app_views.client, name="app-views-client")
Si la configuration d’URL de cette application est incluse dans la configuration d’URL du projet par un chemin tel que celui-ci :
path("clients/", include("project_name.app_name.urls"))
…vous pouvez alors dans le gabarit créer un lien vers cette vue comme ceci :
{% url 'app-views-client' client.id %}
La balise de gabarit affichera le texte /clients/client/123/.
Notez que si l’URL que vous résolvez n’existe pas, vous obtiendrez une exception NoReverseMatch, ce qui provoquera l’affichage d’une page d’erreur sur votre site.
Si vous aimeriez récupérer une URL sans l’afficher, vous pouvez effectuer un appel un peu différent :
{% url 'some-url-name' arg arg2 as the_url %}
<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>
La portée de la variable créée par la syntaxe as var est le {% block %} dans lequel la balise {% url %} apparaît.
Cette syntaxe {% url ... as var %} ne produira pas d’erreur si la vue est manquante. En pratique, vous allez utiliser cela pour des liens vers des vues qui sont facultatives :
{% url 'some-url-name' as the_url %}
{% if the_url %}
<a href="{{ the_url }}">Link to optional stuff</a>
{% endif %}
Si vous souhaitez récupérer une URL avec espace de noms, indiquez le nom entièrement qualifié :
{% url 'myapp:view-name' %}
La stratégie habituelle de résolution d’URL avec espace de noms sera respectée, y compris l’usage d’indicateurs fournis par le contexte comme l’application actuelle.
Avertissement
N’oubliez pas d’entourer le motif d’URL name par des guillemets, sinon la valeur sera interprétée comme une variable de contexte !
verbatim¶
Empêche le moteur de gabarits d’effectuer le rendu du contenu de cette balise de bloc.
C’est souvent employé pour permettre une couche de gabarit JavaScript qui entre en conflit avec la syntaxe Django. Par exemple :
{% verbatim %}
{{if dying}}Still alive.{{/if}}
{% endverbatim %}
Vous pouvez aussi désigner une balise de fermeture spécifique, permettant l’utilisation de {% endverbatim %} comme faisant partie du contenu non rendu :
{% verbatim myblock %}
Avoid template rendering via the {% verbatim %}{% endverbatim %} block.
{% endverbatim myblock %}
widthratio¶
Pour la création de graphiques en barres et autres usages similaires, cette balise calcule le rapport entre une valeur donnée et une valeur maximum, puis applique ce rapport à une constante.
Par exemple :
<img src="bar.png" alt="Bar"
height="10" width="{% widthratio this_value max_value max_width %}">
Si this_value vaut 175, max_value 200 et max_width 100, la largeur de l’image de l’exemple ci-dessus sera de 88 pixels (parce que 175/200 = 0,875 ; 0,875 * 100 = 87,5 qui est arrondi à 88).
Dans certains cas, il peut être souhaitable de capturer le résultat de widthratio dans une variable. Cela peut par exemple être utile dans une balise blocktranslate, comme ceci :
{% widthratio this_value max_value max_width as width %}
{% blocktranslate %}The width is: {{ width }}{% endblocktranslate %}
with¶
Place le résultat d’une expression complexe sous un nom plus simple. C’est utile lors de l’accès multiple à une méthode coûteuse (par ex. avec accès à la base de données).
Par exemple :
{% with total=business.employees.count %}
{{ total }} employee{{ total|pluralize }}
{% endwith %}
La variable créée (dans l’exemple ci-dessus, total) est uniquement disponible entre les balises {% with %} et {% endwith %}.
Vous pouvez créer plus d’une variable de contexte :
{% with alpha=1 beta=2 %}
...
{% endwith %}
Note
L’ancien format plus verbeux est toujours pris en charge : {% with business.employees.count as total %}
Référence des filtres intégrés¶
add¶
Ajoute le paramètre à la valeur.
Par exemple :
{{ value|add:"2" }}
Si value vaut 4, le résultat sera 6.
Ce filtre essaie d’abord de forcer les deux valeurs à des nombres entiers. Si cela échoue, il essaie tout de même d’additionner les deux valeurs. Cela fonctionne avec certains types de données (chaînes, listes, etc.) et échoue avec d’autres. Si cette deuxième tentative échoue, le résultat sera une chaîne vide.
Par exemple, si nous avons :
{{ first|add:second }}
et que first vaut [1, 2, 3] et second vaut [4, 5, 6], le résultat sera [1, 2, 3, 4, 5, 6].
Avertissement
Les chaînes pouvant être forcées en nombre entier seront additionnées et non pas concaténées, comme dans le premier exemple ci-dessus.
addslashes¶
Ajoute des barres obliques inverses avant les guillemets. Utile pour échapper des chaînes en CSV, par exemple.
Par exemple :
{{ value|addslashes }}
Si value contient "J'utilise Django", le résultat sera "J\'utilise Django".
capfirst¶
Met en majuscule le premier caractère de la valeur. Si le premier caractère n’est pas une lettre, ce filtre n’a aucun effet.
Par exemple :
{{ value|capfirst }}
Si value contient "django", le résultat sera "Django".
center¶
Centre la valeur dans un champ de largeur donnée.
Par exemple :
"{{ value|center:"15" }}"
Si value contient "Django", le résultat sera " Django ".
cut¶
Enlève toutes les valeurs en paramètre de la chaîne à filtrer.
Par exemple :
{{ value|cut:" " }}
Si value contient "Chaîne avec des espaces", le résultat sera "Chaîneavecdesespaces".
date¶
Met en forme une date selon le format indiqué.
Utilise un format semblable à la fonction date() de PHP avec certaines différences.
Note
Ces caractères de format ne sont pas utilisés dans Django en dehors des gabarits. Ils ont été conçus pour être compatibles avec PHP afin de faciliter la transition aux rédacteurs habitués à ce langage.
Chaînes de format disponibles :
Caractère de format |
Description |
Exemple d’affichage |
|---|---|---|
Jour |
||
|
Jour du mois, 2 chiffres complétés si nécessaire par un zéro. |
|
|
Jour du mois sans zéros initiaux. |
|
|
Jour de la semaine, abréviation de 3 caractères. |
|
|
Jour de la semaine, texte complet. |
|
|
Suffixe ordinal anglais pour le jour du mois, sur 2 caractères. |
|
|
Jour de la semaine, chiffre sans zéro initial. |
|
|
Jour de l’année. |
|
Semaine |
||
|
Numéro de semaine dans l’année selon ISO-8601, les semaines commençant le lundi. |
|
Mois |
||
|
Mois, 2 chiffres, avec zéro initial si nécessaire. |
|
|
Mois (chiffres) sans zéro initial. |
|
|
Mois, abréviation de 3 caractères. |
|
|
Mois, abréviation de 3 caractères en minuscules. |
|
|
Mois, représentation alternative spécifique à la langue active, habituellement utilisée pour les dates au format étendu. |
|
|
Mois au format texte long. |
|
|
Abréviation du mois dans le style Associated Press. Extension propriétaire. |
|
|
Nombre de jours du mois indiqué. |
|
Année |
||
|
Année, 2 chiffres avec zéros initiaux. |
|
|
Année, 4 chiffres avec zéros initiaux. |
|
|
Valeur booléenne indiquant s’il s’agit d’une année bissextile. |
|
|
Année selon numération des semaines ISO-8601 (W) utilisant la semaine intercalaire. Voir Y pour le format d’année plus habituel. |
|
Heure |
||
|
Heure, format sur 12 heures sans zéros initiaux. |
|
|
Heure, format sur 24 heures sans zéros initiaux. |
|
|
Heure, format sur 12 heures. |
|
|
Heure, format sur 24 heures. |
|
|
Minutes. |
|
|
Secondes, 2 chiffres avec zéro initial. |
|
|
Microsecondes. |
|
|
|
|
|
|
|
|
Heure, en format heures et minutes sur 12 heures, sans affichage des minutes si elles valent 0. Extension propriétaire. |
|
|
Heure, au format sur 12 heures, minutes et « a.m. »/« p.m. », sans les minutes si elles valent 0 ; le cas échéant, les chaînes « minuit » et « midi » apparaissent. Extension propriétaire. |
|
Fuseau horaire |
||
|
Nom de fuseau horaire. Différents formats peuvent apparaître, ou même une chaîne vide, en fonction de la date/heure. |
|
|
Heure d’été, indication si elle est active ou non. |
|
|
Différence en heures avec le temps de Greenwich. |
|
|
Fuseau horaire de la machine. |
|
|
Décalage de fuseau horaire en secondes. Le décalage pour les fuseaux horaires à l’ouest de UTC est toujours négatif, alors qu’il est positif pour les fuseaux à l’est de UTC. |
|
Date/heure |
||
|
Format ISO 8601 (note : contrairement à d’autres formats comme « Z », « O » ou « r », le format « c » n’ajoute pas le décalage de fuseau horaire si la valeur est une date/heure naïve (voir |
|
|
Date mise en forme selon RFC 5322. |
|
|
Secondes depuis le temps Unix initial (1er janvier 1970 00:00:00 UTC). |
Par exemple :
{{ value|date:"D d M Y" }}
Si value est un objet datetime (par ex. le résultat de datetime.datetime.now()), le résultat sera le texte 'mer 09 jan 2008'.
Le format indiqué peut correspondre à l’un des formats prédéfinis DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT ou SHORT_DATETIME_FORMAT, ou un format personnalisé utilisant les spécificateurs de format décrits dans le tableau ci-dessus. Notez que les formats prédéfinis peuvent varier en fonction de la langue active.
En supposant que LANGUAGE_CODE vaille par exemple "es", alors pour :
{{ value|date:"SHORT_DATE_FORMAT" }}
le résultat sera le texte "09/01/2008" (le format "SHORT_DATE_FORMAT" de la locale es fourni avec Django est "d/m/Y").
Lorsqu’aucune chaîne de format n’est indiquée, c’est le format DATE_FORMAT qui est utilisé. Avec des réglages semblables à l’exemple précédent :
{{ value|date }}
produit 9 de Enero de 2008 (le format DATE_FORMAT de la locale es est r'j \d\e F \d\e Y'). « d » et « e » sont tous deux échappés par la barre oblique inverse, car sinon ils seraient considérés comme des marqueurs de format affichant respectivement le jour et le nom du fuseau horaire.
Vous pouvez combiner date avec le filtre time afin de produire une représentation complète d’une valeur datetime, par ex. :
{{ value|date:"D d M Y" }} {{ value|time:"H:i" }}
default¶
Si value est évaluée à False, le paramètre de default est affiché. Sinon, c’est la valeur value qui est affichée.
Par exemple :
{{ value|default:"nothing" }}
Si value contient "" (la chaîne vide), le résultat sera nothing.
default_if_none¶
Si (et seulement si) value vaut None, le paramètre de default est affiché. Sinon, c’est la valeur value qui est affichée.
Notez que si une chaîne vide est transmise, la valeur par défaut ne sera pas utilisée. Utilisez le filtre default si vous voulez que la valeur par défaut soit aussi utilisée pour les chaînes vides.
Par exemple :
{{ value|default_if_none:"nothing" }}
Si value vaut None, le résultat sera nothing.
dictsort¶
Accepte une liste de dictionnaires et renvoie cette liste triée par la clé donnée en paramètre.
Par exemple :
{{ value|dictsort:"name" }}
Si value contient :
[
{"name": "zed", "age": 19},
{"name": "amy", "age": 22},
{"name": "joe", "age": 31},
]
le résultat sera :
[
{"name": "amy", "age": 22},
{"name": "joe", "age": 31},
{"name": "zed", "age": 19},
]
Vous pouvez également faire des choses plus compliquées comme :
{% for book in books|dictsort:"author.age" %}
* {{ book.title }} ({{ book.author.name }})
{% endfor %}
Si books est :
[
{"title": "1984", "author": {"name": "George", "age": 45}},
{"title": "Timequake", "author": {"name": "Kurt", "age": 75}},
{"title": "Alice", "author": {"name": "Lewis", "age": 33}},
]
le résultat sera :
* Alice (Lewis)
* 1984 (George)
* Timequake (Kurt)
dictsort peut aussi trier une liste de listes (ou tout autre objet implémentant __getitem__()) par des éléments à un indice donné. Par exemple :
{{ value|dictsort:0 }}
Si value contient :
[
("a", "42"),
("c", "string"),
("b", "foo"),
]
le résultat sera :
[
("a", "42"),
("b", "foo"),
("c", "string"),
]
Vous devez passer l’indice comme nombre entier et pas comme chaîne. Le code suivant produit un résultat vide :
{{ values|dictsort:"0" }}
Le tri par éléments à un indice donné n’est pas pris en charge pour les dictionnaires.
dictsortreversed¶
Accepte une liste de dictionnaires et renvoie cette liste triée par la clé donnée en paramètre dans l’ordre inverse. Le fonctionnement est le même que le filtre ci-dessus excepté que la valeur renvoyée sera triée dans l’ordre inverse.
divisibleby¶
Renvoie True si la valeur est divisible par le paramètre.
Par exemple :
{{ value|divisibleby:"3" }}
Si value contient 21, le résultat sera
escape¶
Échappe du code HTML. Plus particulièrement, il effectue les remplacements suivants :
<est converti en<>est converti en>'(apostrophe) est converti en'"(guillemet) est converti en"&est converti en&
L’application de escape à une variable qui doit normalement subir l’échappement automatique de son résultat ne fera qu’effectuer un contrôle d’échappement supplémentaire. On peut donc utiliser cette fonction sans souci même dans un contexte d’échappement automatique. Si vous souhaitez forcer l’échappement réel dans tous les cas, utilisez le filtre force_escape.
Par exemple, vous pouvez appliquer escape à certains champs lorsque autoescape n’est pas actif :
{% autoescape off %}
{{ title|escape }}
{% endautoescape %}
Chaînage de escape avec d’autres filtres
Comme mentionné dans la section autoescape, lorsque des filtres incluant escape sont enchaînés, le résultat peut être inattendu si des filtres précédents marquent une chaîne potentiellement non sûre comme sûre en raison d’un manque d’échappement causé par le fait qu”autoescape était désactivé (off).
Dans de tels cas, le chaînage avec escape ne va pas échapper à nouveau des chaînes qui auraient déjà été marquées comme sûres.
Ceci est particulièrement important lors d’utilisation de filtres qui agissent sur des séquences, par exemple join. Si vous avez besoin d’échapper chaque élément d’une séquence, utilisez le filtre dédié escapeseq.
escapejs¶
Échappe les caractères à utiliser en tant que chaîne littérale JavaScript, dans des guillemets simples ou doubles, comme ci-dessous. Ce filtre ne rend pas la chaîne sûre pour être utilisée dans des «littéraux de gabarits JavaScript» (la syntaxe JavaScript avec l’apostrophe inversée ou backtick). Aucun autre utilisation que celle mentionnée ci-dessus n’est prise en charge. Il est généralement recommandé de transmettre les données à l’aide des attributs HTML data- ou par le filtre json_script, plutôt que de l’intégrer dans du JavaScript.
Par exemple :
<script>
let myValue = '{{ value|escapejs }}'
escapeseq¶
Applique le filtre escape à chaque élément d’une liste. Utile conjointement avec d’autres filtres qui agissent sur les listes, comme join. Par exemple :
{% autoescape off %}
{{ my_list|escapeseq|join:", " }}
{% endautoescape %}
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.
Tailles de fichiers et unités SI
Strictement parlant, filesizeformat ne se conforme pas au Système international d’unités qui recommande l’usage de KiB, MiB, GiB, etc. lorsque la taille d’octet est calculée en puissances de 1024 (ce qui est le cas ici). Django utilise plutôt les noms d’unités traditionnelles (KB, MB, GB, etc.) correspondant aux noms qui sont utilisés plus couramment (NdT : la traduction en français utilise les préfixes SI Kio, Mio, etc.).
first¶
Renvoie le premier élément de la liste.
Par exemple :
{{ value|first }}
Si value contient la liste ['a', 'b', 'c'], le résultat sera 'a'.
floatformat¶
Quand le paramètre est absent, ce filtre arrondit un nombre à virgule flottante à un chiffre après la virgule, mais seulement s’il y a une partie décimale à afficher. Par exemple :
|
Gabarit |
Affichage |
|---|---|---|
|
|
|
|
|
|
|
|
|
Quand un paramètre nombre entier est transmis, floatformat arrondit le nombre au nombre de chiffres après la virgule indiqué par le paramètre. Par exemple :
|
Gabarit |
Affichage |
|---|---|---|
|
|
|
|
|
|
|
|
|
Il peut être particulièrement utile de transmettre le paramètre 0 (zéro) ce qui arrondit le nombre à virgule au nombre entier le plus proche.
|
Gabarit |
Affichage |
|---|---|---|
|
|
|
|
|
|
|
|
|
Si le paramètre passé à floatformat est négatif, le nombre sera arrondi au nombre de chiffres après la virgule indiqué, mais seulement s’il y a une partie décimale à afficher. Par exemple :
|
Gabarit |
Affichage |
|---|---|---|
|
|
|
|
|
|
|
|
|
Si l’argument transmis à floatformat possède le suffixe g, cela forcera le groupement par THOUSAND_SEPARATOR pour la locale active. Par exemple, lorsque la locale active est en (anglais) :
|
Gabarit |
Affichage |
|---|---|---|
|
|
|
|
|
|
|
|
|
Le résultat est toujours régionalisé (indépendamment de la balise {% localize off %}) sauf si le paramètre transmis à floatformat possède le suffixe u, ce qui force la désactivation de la régionalisation. Par exemple, lorsque la langue active est pl (polonais) :
|
Gabarit |
Affichage |
|---|---|---|
|
|
|
|
|
|
L’utilisation de floatformat sans paramètre est équivalent à l’utilisation de floatformat avec le paramètre -1.
force_escape¶
Applique l’échappement HTML à une chaîne de caractères (voir le filtre escape pour les détails). Ce filtre est appliqué immédiatement et renvoie une nouvelle chaîne échappée. Cela peut être utile dans les rares cas où vous avez besoin de plusieurs échappements successifs ou que vous vouliez appliquer d’autres filtres au résultat échappé. En temps normal, l’emploi du filtre escape doit suffire.
Par exemple, si vous souhaitez échapper les balises HTML <p> produites par le filtre linebreaks:
{% autoescape off %}
{{ body|linebreaks|force_escape }}
{% endautoescape %}
get_digit¶
Étant donné un nombre entier, renvoie le chiffre indiqué, où 1 est le chiffre le plus à droite, 2 le deuxième plus à droite, etc. Renvoie la valeur originale si les entrées ne sont pas valables (si la valeur ou le paramètre ne sont pas des nombres entiers ou si le paramètre est plus petit que 1). Sinon, le résultat est toujours un nombre entier.
Par exemple :
{{ value|get_digit:"2" }}
SI value contient 123456789, le résultat sera 8.
iriencode¶
Convertit un IRI (Internationalized Resource Identifier) en une chaîne pouvant être incluse dans une URL. C’est nécessaire quand vous essayez d’insérer des chaînes contenant des caractères non ASCII dans des URL.
Vous pouvez sans problème utiliser ce filtre sur une chaîne ayant déjà passé par le filtre urlencode.
Par exemple :
{{ value|iriencode }}
Si value contient "?test=I ♥ Django", le résultat sera "?test=I%20%E2%99%A5%20Django".
join¶
Concatène les éléments d’une liste avec une chaîne de liaison, comme Python le fait avec str.join(list).
Par exemple :
{{ value|join:" // " }}
Si value contient la liste ['a', 'b', 'c'], le résultat sera "a // b // c".
json_script¶
Transforme un objet Python en JSON de manière sûre, enveloppé dans une balise <script>, pour utilisation à partir de JavaScript.
Paramètre : l’attribut HTML « id » facultatif de la balise <script>.
Par exemple :
{{ value|json_script:"hello-data" }}
Si value contient le dictionnaire {'hello': 'world'}, le résultat sera :
<script id="hello-data" type="application/json">{"hello": "world"}</script>
On peut accéder aux données résultantes en JavaScript comme ceci :
const value = JSON.parse(document.getElementById('hello-data').textContent);
Les attaques XSS sont évitées en échappant les caractères « < », « > » et « & ». Par exemple, si value contient {'hello': 'world</script>&'}, le résultat sera :
<script id="hello-data" type="application/json">{"hello": "world\\u003C/script\\u003E\\u0026amp;"}</script>
Ceci est compatible avec une politique Content Security stricte qui interdit l’exécution de script dans les pages. Cela maintient également une séparation propre entre des données passives et du code exécutable.
last¶
Renvoie le dernier élément de la liste.
Par exemple :
{{ value|last }}
Si value contient la liste ['a', 'b', 'c', 'd'], le résultat sera 'd'.
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'] ou "abcd", le résultat sera 4.
Le filtre renvoie 0 pour une variable non définie.
linebreaks¶
Remplace les sauts de ligne dans du texte brut par le code HTML approprié ; un saut de ligne simple devient un saut de ligne HTML (<br>) et un saut de ligne suivi d’une ligne vide devient un saut de paragraphe (</p>).
Par exemple :
{{ value|linebreaks }}
Si value contient "Joël\nest une limace", le résultat sera <p>Joël<br>est une limace</p>.
linebreaksbr¶
Convertit tous les sauts de ligne d’un contenu de texte brut en sauts de ligne HTML (<br>).
Par exemple :
{{ value|linebreaksbr }}
Si value contient "Joël\nest une limace", le résultat sera Joël<br>est une limace.
linenumbers¶
Affiche un texte en numérotant ses lignes.
Par exemple :
{{ value|linenumbers }}
Si value contient :
one
two
three
le résultat sera :
1. one
2. two
3. three
ljust¶
Aligne à gauche la valeur dans un champ de largeur donnée.
Paramètre : taille de champ
Par exemple :
"{{ value|ljust:"10" }}"
Si value contient "Django", le résultat sera "Django ".
lower¶
Convertit une chaîne tout en minuscules.
Par exemple :
{{ value|lower }}
Si value contient J'aime FOLLEMENT cet album!, le résultat sera j'aime follement cet album!.
make_list¶
Renvoie la valeur transformée en liste. Pour une chaîne, ce sera une liste de caractères. Pour un nombre entier, le paramètre est d’abord forcé en chaîne avant d’en faire une liste.
Par exemple :
{{ value|make_list }}
Si value contient la chaîne "Joël", le résultat sera la liste ['J', 'o', 'ë', 'l']. Si value contient 123, le résultat sera la liste ['1', '2', '3'].
phone2numeric¶
Convertit un numéro de téléphone (pouvant contenir des lettres) en son équivalent numérique.
La valeur de départ ne doit pas forcément être un numéro de téléphone valable. Toute chaîne de caractères sera transformée sans renâcler.
Par exemple :
{{ value|phone2numeric }}
Si value vaut 800-COLLECT, le résultat sera 800-2655328.
pluralize¶
Renvoie un suffixe de pluriel si la valeur est différente de 1, '1' ou d’un objet de longueur 1. Par défaut, le suffixe est 's'.
Exemple :
You have {{ num_messages }} message{{ num_messages|pluralize }}.
Si num_messages contient 1, le résultat sera You have 1 message. Si num_messages contient 2, le résultat sera You have 2 messages.
Pour les mots exigeant un suffixe autre que 's', vous pouvez indiquer un suffixe alternatif en paramètre du filtre.
Exemple :
You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}.
Pour les mots dont le pluriel n’est pas un simple suffixe, vous pouvez indiquer à la fois un suffixe singulier et un suffixe pluriel, séparés par une virgule.
Exemple :
You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.
Note
Utilisez blocktranslate pour mettre au pluriel des chaînes à traduire.
pprint¶
Un adaptateur autour de pprint.pprint(), à réserver vraiment pour le débogage.
random¶
Renvoie un élément aléatoire dans la liste indiquée.
Par exemple :
{{ value|random }}
Si value contient la liste ['a', 'b', 'c', 'd'], le résultat pourrait être "b".
rjust¶
Aligne à droite la valeur dans un champ de largeur donnée.
Paramètre : taille de champ
Par exemple :
"{{ value|rjust:"10" }}"
Si value contient "Django", le résultat sera " Django".
safe¶
Marque une chaîne comme n’ayant plus besoin d’être échappée avant d’être affichée dans du code HTML. Lorsque l’échappement automatique est désactivé, ce filtre n’a aucun effet.
Note
Si vous enchaînez des filtres, un filtre appliqué après safe peut de nouveau rendre le contenu non fiable. Par exemple, le code suivant affiche la variable telle quelle, non échappée :
{{ var|safe|escape }}
safeseq¶
Applique le filtre safe à chaque élément d’une liste. Utile conjointement avec d’autres filtres qui agissent sur les listes, comme join. Par exemple :
{{ some_list|safeseq|join:", " }}
Vous n’auriez pas pu utiliser directement le filtre safe dans ce cas, car cela aurait d’abord converti la variable en chaîne au lieu d’agir sur les éléments individuels de la liste.
slice¶
Renvoie un segment de la liste.
Utilise la même syntaxe que la segmentation des listes Python. Voir la documentation de Python pour une introduction.
Exemple :
{{ some_list|slice:":2" }}
Si some_list contient ['a', 'b', 'c'], le résultat sera ['a', 'b'].
slugify¶
Convertit en ASCII. Convertit les espaces en tirets. Enlève les caractères qui ne sont ni alphanumériques, ni soulignements, ni tirets. Convertit en minuscules. Les espaces en début et fin de chaîne sont aussi enlevés.
Par exemple :
{{ value|slugify }}
Si value contient "Joël est une limace", le résultat sera joel-est-une-limace.
stringformat¶
Met en forme la variable en fonction du paramètre, une spécification de chaîne de format. Celle-ci utilise la syntaxe printf-style String Formatting, à l’exclusion du caractère « % » initial.
Par exemple :
{{ value|stringformat:"E" }}
SI value contient 10, le résultat sera 1.000000E+01.
striptags¶
Fait tout son possible pour supprimer toutes les balises [X]HTML.
Par exemple :
{{ value|striptags }}
Si value contient "<b>Joël</b> <button>est</button> une <span>limace</span>", le résultat sera "Joël est une limace".
Aucune garantie de sécurité
Notez que striptags ne donne aucune garantie que le contenu résultant ne contienne plus de balisage HTML, plus particulièrement lorsque le contenu en entrée n’est pas du code HTML valide. N’appliquez donc JAMAIS le filtre safe sur du contenu provenant de striptags. Si vous recherchez une solution plus solide, recherchez un outil tiers de nettoyage de HTML.
time¶
Met en forme une heure selon le format indiqué.
Le format indiqué peut être le format prédéfini TIME_FORMAT ou un format personnalisé, comme pour le filtre date. Notez que le format prédéfini est dépendant de la langue active.
Par exemple :
{{ value|time:"H:i" }}
Si value est équivalent à datetime.datetime.now(), le résultat sera "01:23".
Notez que vous pouvez échapper par barre oblique inverse une chaîne de format si vous souhaitez utiliser la valeur « brute ». Dans cet exemple, « h » et « m » sont tous deux échappés par barre oblique inverse, sinon ils seraient chacun interprétés comme une chaîne de format pour afficher respectivement l’heure et le mois :
{{ value|time:"H\h i\m" }}
Le résultat affiché est « 01h 23m »..
Un autre exemple :
En supposant que LANGUAGE_CODE vaille par exemple "de", alors pour :
{{ value|time:"TIME_FORMAT" }}
le résultat sera "01:23" (le spécificateur de format "TIME_FORMAT" de la locale de fournie par Django contient "H:i").
Le filtre time n’accepte dans la chaîne de format que les paramètres concernant l’heure du jour, et non la date. Si vous avez besoin de mettre en forme une date, utilisez plutôt le filtre date (éventuellement avec time si vous avez besoin de produire une valeur datetime complète).
Il existe une exception à la règle ci-dessus : lorsqu’il reçoit une valeur datetime contenant une information de fuseau horaire (une instance datetime consciente), le filtre time accepte les indicateurs de format relatifs aux fuseaux horaires 'e', 'O' , 'T' et 'Z'.
Lorsqu’aucune chaîne de format n’est indiquée, c’est le format TIME_FORMAT qui est utilisé :
{{ value|time }}
est identique à :
{{ value|time:"TIME_FORMAT" }}
timesince¶
Met en forme une date de manière relative à cette date (par ex. « 4 jours, 6 heures »).
Accepte un paramètre facultatif sous forme de variable contenant la date à utiliser comme point de comparaison (sans paramètre, le point de comparaison est maintenant). Par exemple, si blog_date est une instance de date représentant minuit le 1 juin 2006 et que comment_date est une instance de date représentant le 1 juin 2006 à 08:00, le code suivant renverra « 8 heures »:
{{ blog_date|timesince:comment_date }}
La comparaison entre des dates/heures naïves et conscientes (en rapport au fuseau horaire) renvoie une chaîne vide.
Les minutes sont la plus petite unité utilisée, et « 0 minute » est renvoyé pour toute date dans le futur en fonction du point de comparaison.
timeuntil¶
Semblable à timesince, sauf qu’il mesure le temps depuis maintenant jusqu’à la date ou date/heure indiquée. Par exemple, si nous sommes le 1er juin 2006 et que conference_date est une instance de date contenant le 29 juin 2006, {{ conference_date|timeuntil }} renverra « 4 semaines ».
Accepte un paramètre facultatif sous forme de variable contenant la date à utiliser comme point de comparaison (au lieu de maintenant). Si from_date contient le 22 juin 2006, le code suivant renverra « 1 semaine » :
{{ conference_date|timeuntil:from_date }}
La comparaison entre des dates/heures naïves et conscientes (en rapport au fuseau horaire) renvoie une chaîne vide.
Les minutes sont la plus petite unité utilisée, et « 0 minute » est renvoyé pour toute date dans le passé en fonction du point de comparaison.
title¶
Convertit une chaîne en casse de titre de type anglophone en mettant en majuscule la première lettre de chaque mot et en minuscules les autres lettres. Cette balise ne fait aucun effort pour conserver en minuscules les mots « utilitaires ».
Par exemple :
{{ value|title }}
Si value contient "mon PREMIER article", le résultat sera "Mon Premier Article".
truncatechars¶
Tronque une chaîne si elle est plus longue que le nombre de caractères indiqué. Les chaînes tronquées se terminent par un caractère points de suspension (« … »).
Paramètre : le nombre maximum de caractères du résultat
Par exemple :
{{ value|truncatechars:7 }}
Si value contient "Joël est une limace", le résultat sera "Joël e…".
truncatechars_html¶
Semblable à truncatechars, mais en tenant compte des balises HTML. Toute balise ouverte dans la chaîne et non fermée avant le point de troncature est immédiatement fermée après la troncature.
Par exemple :
{{ value|truncatechars_html:7 }}
Si value contient "<p>Joël est une limace</p>", le résultat sera "<p>Joël e…</p>".
Les sauts de ligne dans le contenu HTML sont préservés.
Taille de la chaîne d’entrée
Le traitement de chaînes HTML très grandes, potentiellement malformées, peut exiger de grandes ressources et influencer la performance du service. truncatechars_html limite le traitement de son entrée aux 5 premiers millions de caractères.
Dans les versions précédentes, des chaînes de plus de 5 millions de caractères étaient traitées.
truncatewords¶
Tronque une chaîne après un certain nombre de mots.
Paramètre : le nombre maximum de mots du résultat
Par exemple :
{{ value|truncatewords:2 }}
Si value contient "Joël est une limace", le résultat sera "Joël est …".
Les sauts de ligne à l’intérieur de la valeur seront enlevés.
truncatewords_html¶
Semblable à truncatewords, mais en tenant compte des balises HTML. Toute balise ouverte dans la chaîne et non fermée avant le point de troncature est immédiatement fermée après la troncature.
Ce filtre est moins efficace que truncatewords, il ne devrait donc être employé que lorsque l’on agit sur du texte contenant du HTML.
Par exemple :
{{ value|truncatewords_html:2 }}
Si value contient "<p>Joël est une limace</p>", le résultat sera "<p>Joël est …</p>".
Les sauts de ligne dans le contenu HTML sont préservés.
Taille de la chaîne d’entrée
Le traitement de chaînes HTML très grandes, potentiellement malformées, peut exiger de grandes ressources et influencer la performance du service. truncatewords_html limite le traitement de son entrée aux 5 premiers millions de caractères.
Dans les versions précédentes, des chaînes de plus de 5 millions de caractères étaient traitées.
unordered_list¶
Accepte des listes imbriquées et les traite récursivement pour obtenir une liste HTML non ordonnée, sans les balises <ul> ouvrantes et fermantes.
Il est nécessaire que la liste soit dans le bon format. Par exemple, si var contient ['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']], le résultat de {{ var|unordered_list }} sera :
<li>States
<ul>
<li>Kansas
<ul>
<li>Lawrence</li>
<li>Topeka</li>
</ul>
</li>
<li>Illinois</li>
</ul>
</li>
upper¶
Convertit une chaîne tout en majuscules.
Par exemple :
{{ value|upper }}
Si value vaut "Joël est une limace", le résultat sera "JOËL EST UNE LIMACE".
urlencode¶
Échappe une valeur pour être incluse dans une URL.
Par exemple :
{{ value|urlencode }}
Si value vaut "https://www.example.org/foo?a=b&c=d", le résultat sera "https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd".
Il est possible de fournir un paramètre facultatif contenant les caractères qui ne doivent pas être échappés.
Sans ce paramètre, le caractère « / » est considéré comme sûr. Il est possible de fournir une chaîne vide pour indiquer que tous les caractères doivent être échappés. Par exemple :
{{ value|urlencode:"" }}
Si value vaut "https://www.example.org/", le résultat sera "https%3A%2F%2Fwww.example.org%2F".
urlize¶
Convertit les URL et les adresses électroniques dans le texte en hyperliens.
Cette balise de gabarit fonctionne avec des liens préfixés par http://, https:// ou www.. Par exemple, https://djangocon.eu sera converti mais djangocon.eu ne le sera pas.
Il convertit également les liens « noms de domaine » s’ils se terminent par l’un des domaines de premier niveau de base (.com, .edu, .gov, .int, .mil, .net et .org). Par exemple, djangoproject.com sera converti.
Les liens peuvent se terminer par de la ponctuation (points, virgules, parenthèse fermante) et peuvent commencer par de la ponctuation (parenthèse ouvrante) ; urlize n’en sera pas perturbé pour autant.
Les liens générés par urlize reçoivent l’attribut rel="nofollow".
Par exemple :
{{ value|urlize }}
Si value vaut "Visitez www.djangoproject.com", le résultat sera "Visitez <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproject.com</a>".
En plus des liens de type web, urlize convertit aussi les adresses électroniques en liens mailto:. Si value contient "Envoyez les questions à foo@example.com", le résultat sera "Envoyez les questions à <a href="mailto:foo@example.com">foo@example.com</a>".
Le filtre urlize accepte également un paramètre facultatif autoescape. Si celui-ci vaut True, le texte du lien et les URL seront échappés par le filtre escape de Django. La valeur par défaut de autoescape est True.
Note
Si urlize est appliqué à du texte qui contient déjà des balises HTML ou à des adresses électroniques contenant des guillemets simples ('), les choses ne se passeront pas comme prévu. N’appliquez ce filtre qu’à du texte pur.
Avertissement
L’utilisation de urlize ou urlizetrunc peut impliquer une charge de calcul significative, pouvant même être importante lorsque ces filtres sont appliqués à des contenus en provenance des utilisateurs, comme par exemple des contenus stockés dans des champs TextField. Le filtre truncatechars peut être utilisé pour limiter la longueur de telles valeurs :
{{ value|truncatechars:500|urlize }}
urlizetrunc¶
Convertit les URL et les adresses électroniques dans le texte en hyperliens tout comme urlize, mais tronque le texte des URL plus long que la limite du nombre de caractères indiquée.
Paramètre : le nombre maximum de caractères que le texte du lien contiendra après avoir été tronqué si nécessaire, y compris l’ellipse ajoutée par la troncature, le cas échéant.
Par exemple :
{{ value|urlizetrunc:15 }}
Si value vaut "Visitez www.djangoproject.com", le résultat sera 'Visitez <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproj…</a>'.
Comme pour urlize, ce filtre ne doit être appliqué qu’à du texte pur.
wordcount¶
Renvoie le nombre de mots.
Par exemple :
{{ value|wordcount }}
Si value vaut "Joël est une limace", le résultat sera 4.
wordwrap¶
Ajoute des sauts de ligne d’après une longueur de ligne maximale.
Paramètre : le nombre de caractères après lequel un saut de ligne est rajouté dans le texte.
Par exemple :
{{ value|wordwrap:5 }}
Si value vaut Joel is a slug, le résultat sera :
Joel
is a
slug
yesno¶
Fait correspondre les valeurs vrai (True), faux (False) et facultativement None respectivement aux chaînes de caractères « yes », « no », « maybe », ou à une liste personnalisée de chaînes séparées par des virgules, et renvoie la chaîne correspondant à la valeur transmise :
Par exemple :
{{ value|yesno:"yeah,no,maybe" }}
Valeur |
Paramètre |
Affiche |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Balises et filtres d’internationalisation¶
Django fournit des balises et des filtres de gabarit pour contrôler chaque aspect de l’internationalization dans les gabarits. Ils permettent un contrôle plus fin sur les traductions, la mise en forme et les conversions de fuseaux horaires.
i18n¶
Cette bibliothèque permet d’indiquer du texte à traduire dans les gabarits. Pour l’activer, définissez USE_I18N à True puis chargez-la avec {% load i18n %}.
l10n¶
Cette bibliothèque donne le contrôle sur la régionalisation des valeurs dans les gabarits. Vous devez seulement charger la bibliothèque en écrivant {% load l10n %}.
tz¶
Cette bibliothèque permet de contrôler les conversions de fuseaux horaires dans les gabarits. Comme l10n, il suffit de charger la bibliothèque avec {% load tz %}, mais il est préférable de définir aussi USE_TZ à True pour que la conversion en temps locale se fasse par défaut.
Voir Affichage de fuseaux horaires conscients dans les gabarits.
Autres bibliothèques de balises et de filtres¶
Django contient quelques autres bibliothèques de balises de gabarit que vous devez activer explicitement dans votre réglage INSTALLED_APPS et qu’il fut charger dans les gabarits avec la balise {% load %}.
django.contrib.humanize¶
Un ensemble de filtres de gabarit utiles pour ajouter une touche « humaine » aux données. Voir django.contrib.humanize.
static¶
static¶
Pour créer des liens vers les fichiers statiques enregistrés dans STATIC_ROOT, Django fournit une balise de gabarit static. Si l’application django.contrib.staticfiles est installée, la balise servira les fichiers en utilisant la méthode url() du stockage pointé par staticfiles dans STORAGES. Par exemple :
{% load static %}
<img src="{% static 'images/hi.jpg' %}" alt="Hi!">
Elle est aussi capable d’exploiter des variables de contexte standards ; par exemple en supposant qu’une variable user_stylesheet est transmise au gabarit :
{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" media="screen">
Si vous souhaitez récupérer une URL statique sans l’afficher, vous pouvez effectuer un appel un peu différent :
{% load static %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}" alt="Hi!">
Utilisation de gabarits Jinja2
Voir Jinja2 pour des informations sur l’utilisation de la balise static avec Jinja2.
get_static_prefix¶
La préférence devrait être donnée à la balise de gabarit static, mais si vous avez besoin d’un contrôle plus fin sur l’endroit et la manière dont STATIC_URL est injecté dans le gabarit, vous pouvez utiliser la balise de gabarit get_static_prefix:
{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" alt="Hi!">
Il existe aussi une seconde forme utilisable pour empêcher du traitement inutile si vous avez besoin de la même valeur plusieurs fois :
{% load static %}
{% get_static_prefix as STATIC_PREFIX %}
<img src="{{ STATIC_PREFIX }}images/hi.jpg" alt="Hi!">
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" alt="Hello!">
get_media_prefix¶
Semblable à get_static_prefix, get_media_prefix crée une variable de gabarit contenant le préfixe de média MEDIA_URL, par exemple :
{% load static %}
<body data-media-url="{% get_media_prefix %}">
En stockant la valeur dans un attribut de données, nous nous assurons qu’elle soit proprement échappée si nous souhaitons l’utiliser dans un contexte JavaScript.
