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é.
\nautoescapeLien vers cette rubrique#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.
Lorsque l’échappement automatique est actif, tous les contenus de variables sont soumis à l’échappement HTML avant d’être affichés (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 » (plus besoin d’être échappées), soit par le code qui a défini la variable en question ou parce qu’elle a déjà passé par un filtre safe ou escape.
Exemple d’utilisation :
\n{% autoescape on %}\n {{ body }}\n{% endautoescape %}\nblockLien vers cette rubrique#Définit un bloc pouvant être surchargé par les gabarits enfants. Voir Héritage des gabarits pour plus d’informations.
\ncommentLien vers cette rubrique#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 :
\n<p>Rendered text with {{ pub_date|date:"c" }}</p>\n{% comment "Optional note" %}\n <p>Commented out text with {{ create_date|date:"c" }}</p>\n{% endcomment %}\nLes balises comment ne peuvent pas être imbriquées.
csrf_tokenLien vers cette rubrique#Cette balise est utilisée pour la protection CSRF, comme décrit dans la documentation Cross Site Request Forgeries.
\ncycleLien vers cette rubrique#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.
\nCette balise est particulièrement utile dans une boucle :
\n{% for o in some_list %}\n <tr class="{% cycle 'row1' 'row2' %}">\n ...\n </tr>\n{% endfor %}\nLa 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 %}\n <tr class="{% cycle rowvalue1 rowvalue2 %}">\n ...\n </tr>\n{% endfor %}\nLes variables incluses dans le cycle seront échappées. Vous pouvez désactiver l’échappement automatique avec :
\n{% for o in some_list %}\n <tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}">\n ...\n </tr>\n{% endfor %}\nVous pouvez mélanger des variables et des chaînes :
\n{% for o in some_list %}\n <tr class="{% cycle 'row1' rowvalue2 'row3' %}">\n ...\n </tr>\n{% endfor %}\nDans 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 %}\nÀ 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>\n <td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td>\n <td class="{{ rowcolors }}">...</td>\n</tr>\n<tr>\n <td class="{% cycle rowcolors %}">...</td>\n <td class="{{ rowcolors }}">...</td>\n</tr>\naffichera :
\n<tr>\n <td class="row1">...</td>\n <td class="row1">...</td>\n</tr>\n<tr>\n <td class="row2">...</td>\n <td class="row2">...</td>\n</tr>\nVous 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 %}\n {% cycle 'row1' 'row2' as rowcolors silent %}\n <tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr>\n{% endfor %}\nCeci 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 %}\n{% cycle rowcolors %}\nIl est possible d’utiliser la balise resetcycle pour réinitialiser une balise {% cycle %} à sa première valeur lors de sa prochaine apparition.
debugLien vers cette rubrique#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.
extendsLien vers cette rubrique#Indique que ce gabarit étend un gabarit parent.
\nCette balise peut être utilisée de deux façons :
\n{% extends "base.html" %} (avec guillemets) utilise la valeur littérale "base.html" comme nom du gabarit parent à étendre.
{% extends variable %} utilise la valeur de variable. Si la variable contient une chaîne de caractères, Django utilise celle-ci comme nom du gabarit parent. Si la variable contient un objet Template, Django utilise cet objet comme gabarit parent.
Voir Héritage de gabarits pour plus d’informations.
\nEn 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/\n template.html\n base2.html\n my/\n base3.html\nbase1.html\nDans template.html, les chemins suivants seraient valides :
{% extends "./base2.html" %}\n{% extends "../base1.html" %}\n{% extends "./my/base3.html" %}\nfilterLien vers cette rubrique#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.
\nNotez que le bloc inclus tout le texte entre les balises filter et endfilter.
Exemple d’utilisation :
\n{% filter force_escape|lower %}\n This text will be HTML-escaped, and will appear in all lowercase.\n{% endfilter %}\nfirstofLien vers cette rubrique#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 ».
\nExemple d’utilisation :
\n{% firstof var1 var2 var3 %}\nC’est l’équivalent de :
\n{% if var1 %}\n {{ var1 }}\n{% elif var2 %}\n {{ var2 }}\n{% elif var3 %}\n {{ var3 }}\n{% endif %}\nVous 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" %}\nCette balise échappe automatiquement les valeurs des variables. Vous pouvez désactiver l’échappement automatique avec :
\n{% autoescape off %}\n {% firstof var1 var2 var3 "<strong>fallback value</strong>" %}\n{% endautoescape %}\nOu si seulement certaines variables doivent être échappées, vous pouvez employer :
\n{% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %}\nVous pouvez utiliser la syntaxe {% firstof var1 var2 var3 as value %} pour stocker le résultat dans une variable.
forLien vers cette rubrique#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>\n{% for athlete in athlete_list %}\n <li>{{ athlete.name }}</li>\n{% endfor %}\n</ul>\nVous pouvez effectuer une boucle inversée sur une liste en utilisant {% for obj in list reversed %}`.
\nSi 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 %}\n There is a point at {{ x }},{{ y }}\n{% endfor %}\nCela 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 %}\n {{ key }}: {{ value }}\n{% endfor %}\nN’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 | \nDescription | \n
|---|---|
| \nL’itération actuelle de la boucle (index à partir de 1) | \n
| \nL’itération actuelle de la boucle (index à partir de 0) | \n
| \nLe nombre d’itérations à partir de la fin de la boucle (index à partir de 1) | \n
| \nLe nombre d’itérations à partir de la fin de la boucle (index à partir de 0) | \n
| \n
| \n
| \n
| \n
| \nPour les boucles imbriquées, il s’agit de la boucle de niveau supérieur | \n
for … emptyLien vers cette rubrique#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>\n{% for athlete in athlete_list %}\n <li>{{ athlete.name }}</li>\n{% empty %}\n <li>Sorry, no athletes in this list.</li>\n{% endfor %}\n</ul>\nLe code ci-dessus est équivalent, mais plus court, plus propre et peut-être plus rapide que ceci :
\n<ul>\n {% if athlete_list %}\n {% for athlete in athlete_list %}\n <li>{{ athlete.name }}</li>\n {% endfor %}\n {% else %}\n <li>Sorry, no athletes in this list.</li>\n {% endif %}\n</ul>\nifLien vers cette rubrique#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 %}\n Number of athletes: {{ athlete_list|length }}\n{% elif athlete_in_locker_room_list %}\n Athletes should be out of the locker room soon!\n{% else %}\n No athletes.\n{% endif %}\nDans 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.
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 %}\n Both athletes and coaches are available.\n{% endif %}\n\n{% if not athlete_list %}\n There are no athletes.\n{% endif %}\n\n{% if athlete_list or coach_list %}\n There are some athletes or some coaches.\n{% endif %}\n\n{% if not athlete_list or coach_list %}\n There are no athletes or there are some coaches.\n{% endif %}\n\n{% if athlete_list and not coach_list %}\n There are some athletes and absolutely no coaches.\n{% endif %}\nL’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 %}\nsera interprété comme :
\nif (athlete_list and coach_list) or cheerleader_list\nL’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 :
==Lien vers cette rubrique#Égalité. Exemple :
\n{% if somevar == "x" %}\n This appears if variable somevar equals the string "x"\n{% endif %}\n!=Lien vers cette rubrique#Inégalité. Exemple :
\n{% if somevar != "x" %}\n This appears if variable somevar does not equal the string "x",\n or if somevar is not found in the context\n{% endif %}\n<Lien vers cette rubrique#Inférieur à. Exemple :
\n{% if somevar < 100 %}\n This appears if variable somevar is less than 100.\n{% endif %}\n>Lien vers cette rubrique#Supérieur à. Exemple :
\n{% if somevar > 0 %}\n This appears if variable somevar is greater than 0.\n{% endif %}\n<=Lien vers cette rubrique#Inférieur ou égal à. Exemple :
\n{% if somevar <= 100 %}\n This appears if variable somevar is less than 100 or equal to 100.\n{% endif %}\n>=Lien vers cette rubrique#Supérieur ou égal à. Exemple :
\n{% if somevar >= 1 %}\n This appears if variable somevar is greater than 1 or equal to 1.\n{% endif %}\ninLien vers cette rubrique#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" %}\n This appears since "bc" is a substring of "abcdef"\n{% endif %}\n\n{% if "hello" in greetings %}\n If greetings is a list or set, one element of which is the string\n "hello", this will appear.\n{% endif %}\n\n{% if user in users %}\n If users is a QuerySet, this will appear if user is an\n instance that belongs to the QuerySet.\n{% endif %}\nnot inLien vers cette rubrique#Non contenu dans. C’est la négation de l’opérateur in.
isLien vers cette rubrique#Identité d’objet. Teste si deux valeurs sont le même objet. Exemple :
\n{% if somevar is True %}\n This appears if and only if somevar is True.\n{% endif %}\n\n{% if somevar is None %}\n This appears if somevar is None, or if somevar is not found in the context.\n{% endif %}\nis notLien vers cette rubrique#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 %}\n This appears if somevar is not True, or if somevar is not found in the\n context.\n{% endif %}\n\n{% if somevar is not None %}\n This appears if and only if somevar is not None.\n{% endif %}\nVous pouvez aussi utiliser des filtres dans l’expression if. Par exemple :
{% if messages|length >= 100 %}\n You have lots of messages today!\n{% endif %}\nTous 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 :
\nor
and
not
in
==, !=, <, >, <=, >=
(Ceci suit exactement le comportement Python). Ainsi, par exemple, la balise if complexe suivante :
{% if a == b or c == d and e %}\n…sera interprétée comme :
\n(a == b) or ((c == d) and e)\nSi 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 :
\n{% if a > b > c %} (WRONG)\nvous devez écrire :
\n{% if a > b and b > c %}\nifchangedLien vers cette rubrique#Vérifie si une valeur a changé depuis l’itération précédente d’une boucle.
\nLa 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 :
\n<h1>Archive for {{ year }}</h1>\n\n{% for date in days %}\n {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}\n <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>\n{% endfor %}\nSi 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é :
\n{% for date in days %}\n {% ifchanged date.date %} {{ date.date }} {% endifchanged %}\n {% ifchanged date.hour date.date %}\n {{ date.hour }}\n {% endifchanged %}\n{% endfor %}\nLa balise ifchanged accepte aussi une clause facultative {% else %} qui affiche son contenu si la valeur n’a pas changé :
{% for match in matches %}\n <div style="background-color:\n {% ifchanged match.ballot_id %}\n {% cycle "red" "blue" %}\n {% else %}\n gray\n {% endifchanged %}\n ">{{ match }}</div>\n{% endfor %}\nincludeLien vers cette rubrique#Charge un gabarit et l’affiche avec le contexte en cours. C’est une manière d’inclure d’autres gabarits dans un gabarit.
\nLe nom du gabarit peut être soit une variable, soit une chaîne fixe entre guillemets, simples ou doubles.
\nCet exemple inclut le contenu du gabarit "foo/bar.html":
{% include "foo/bar.html" %}\nEn 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 %}\nLa 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 person contient "John" et la variable greeting contient "Hello".
Gabarit :
\n{% include "name_snippet.html" %}\nLe gabarit name_snippet.html:
{{ greeting }}, {{ person|default:"friend" }}!\nVous pouvez transmettre du contexte supplémentaire au gabarit en utilisant des paramètres nommés :
\n{% include "name_snippet.html" with person="Jane" greeting="Hello" %}\nSi 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 %}\nloadLien vers cette rubrique#Charge un lot de balises de gabarit personnalisées.
\nPar 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 %}\nVous 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 %}\nVoir Bibliothèques de balises et de filtres personnalisés pour plus d’informations.
\nloremLien vers cette rubrique#Affiche du texte latin aléatoire « lorem ipsum ». C’est pratique pour produire des données d’exemple dans les gabarits.
\nUtilisation :
\n{% lorem [count] [method] [random] %}\nLa balise {% lorem %} peut être utilisée avec zéro, un, deux ou trois paramètres. Ces paramètres sont :
Paramètre | \nDescription | \n
|---|---|
| \nUn nombre (ou une variable) contenant le nombre de paragraphes ou de mots à produire (1 par défaut). | \n
| \nIndiquez | \n
| \nLe mot | \n
Exemples :
\n{% 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.
nowLien vers cette rubrique#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 :
\nIt is {% now "jS F Y H:i" %}\nNotez 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 :
\nIt is the {% now "jS \\o\\f F" %}\nLe résultat affiché est « It is the 4th of September ».
\n\nVous 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 %}\n{% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %}\nregroupLien vers cette rubrique#Regroupe une liste d’objets semblables par un attribut commun.
\nLa 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 = [\n {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},\n {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},\n {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},\n {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},\n {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},\n]\n…et vous aimeriez afficher une liste hiérarchique triée par pays, comme ceci :
\nIndia
\nMumbai: 19,000,000
Calcutta: 15,000,000
USA
\nNew York: 20,000,000
Chicago: 7,000,000
Japan
\nTokyo: 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 %}\n\n<ul>\n{% for country in country_list %}\n <li>{{ country.grouper }}\n <ul>\n {% for city in country.list %}\n <li>{{ city.name }}: {{ city.population }}</li>\n {% endfor %}\n </ul>\n </li>\n{% endfor %}\n</ul>\nParcourons 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 ayant country='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 %}\n\n<ul>\n{% for country, local_cities in country_list %}\n <li>{{ country }}\n <ul>\n {% for city in local_cities %}\n <li>{{ city.name }}: {{ city.population }}</li>\n {% endfor %}\n </ul>\n </li>\n{% endfor %}\n</ul>\nNotez 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 = [\n {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},\n {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},\n {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},\n {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},\n {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},\n]\nAvec ce contenu dans cities, l’exemple de code de gabarit pour {% regroup %} ci-dessus produirait le résultat suivant :
India
\nMumbai: 19,000,000
USA
\nNew York: 20,000,000
India
\nCalcutta: 15,000,000
USA
\nChicago: 7,000,000
Japan
\nTokyo: 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.
\nUn 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 %}\nToute 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 %}\nOu 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 %}\n{{ country.grouper }} contient maintenant la partie valeur des choix choices plutôt que leur clé.
resetcycleLien vers cette rubrique#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 :
\n{% for coach in coach_list %}\n <h1>{{ coach.name }}</h1>\n {% for athlete in coach.athlete_set.all %}\n <p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>\n {% endfor %}\n {% resetcycle %}\n{% endfor %}\nCet exemple produit le code HTML suivant :
\n<h1>José Mourinho</h1>\n<p class="odd">Thibaut Courtois</p>\n<p class="even">John Terry</p>\n<p class="odd">Eden Hazard</p>\n\n<h1>Carlo Ancelotti</h1>\n<p class="odd">Manuel Neuer</p>\n<p class="even">Thomas Müller</p>\nRemarquez 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 %}\n <p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}">\n {{ item.data }}\n </p>\n {% ifchanged item.category %}\n <h1>{{ item.category }}</h1>\n {% if not forloop.first %}{% resetcycle tick %}{% endif %}\n {% endifchanged %}\n{% endfor %}\nDans 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.
\nspacelessLien vers cette rubrique#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.
\nExemple d’utilisation :
\n{% spaceless %}\n <p>\n <a href="foo/">Foo</a>\n </p>\n{% endspaceless %}\nCet exemple produit le code HTML suivant :
\n<p><a href="foo/">Foo</a></p>\nSeuls 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 %}\n <strong>\n Hello\n </strong>\n{% endspaceless %}\ntemplatetagLien vers cette rubrique#Affiche l’une des séquences de caractères utilisées dans la syntaxe des balises de gabarit.
\nLe 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 :
\nParamètre | \nAffiche | \n
|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
Exemple d’utilisation :
\nThe {% templatetag openblock %} characters open a block.\nVoir aussi la balise verbatim pour une autre façon d’inclure ces caractères.
urlLien vers cette rubrique#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 :
\n{% url 'some-url-name' v1 v2 %}\nLe 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é
\n{% url 'some-url-name' arg1=v1 arg2=v2 %}\nNe 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.
\nPar 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')\nSi la configuration d’URL de cette application est incluse dans la configuration d’URL du projet par un chemin tel que celui-ci :
\npath('clients/', include('project_name.app_name.urls'))\n…vous pouvez alors dans le gabarit créer un lien vers cette vue comme ceci :
\n{% url 'app-views-client' client.id %}\nLa 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 :
\n{% url 'some-url-name' arg arg2 as the_url %}\n\n<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>\nLa 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 %}\n{% if the_url %}\n <a href="{{ the_url }}">Link to optional stuff</a>\n{% endif %}\nSi vous souhaitez récupérer une URL avec espace de noms, indiquez le nom entièrement qualifié :
\n{% url 'myapp:view-name' %}\nLa 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.
\n\nverbatimLien vers cette rubrique#Empêche le moteur de gabarits d’effectuer le rendu du contenu de cette balise de bloc.
\nC’est souvent employé pour permettre une couche de gabarit JavaScript qui entre en conflit avec la syntaxe Django. Par exemple :
\n{% verbatim %}\n {{if dying}}Still alive.{{/if}}\n{% endverbatim %}\nVous pouvez aussi désigner une balise de fermeture spécifique, permettant l’utilisation de {% endverbatim %} comme faisant partie du contenu non rendu :
{% verbatim myblock %}\n Avoid template rendering via the {% verbatim %}{% endverbatim %} block.\n{% endverbatim myblock %}\nwidthratioLien vers cette rubrique#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.
\nPar exemple :
\n<img src="bar.png" alt="Bar"\n height="10" width="{% widthratio this_value max_value max_width %}">\nSi 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 %}\n{% blocktranslate %}The width is: {{ width }}{% endblocktranslate %}\nwithLien vers cette rubrique#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).
\nPar exemple :
\n{% with total=business.employees.count %}\n {{ total }} employee{{ total|pluralize }}\n{% endwith %}\nLa 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 :
\n{% with alpha=1 beta=2 %}\n ...\n{% endwith %}\naddLien vers cette rubrique#Ajoute le paramètre à la valeur.
\nPar exemple :
\n{{ value|add:"2" }}\nSi 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.
\nPar exemple, si nous avons :
\n{{ first|add:second }}\net que first vaut [1, 2, 3] et second vaut [4, 5, 6], le résultat sera [1, 2, 3, 4, 5, 6].
addslashesLien vers cette rubrique#Ajoute des barres obliques inverses avant les guillemets. Utile pour échapper des chaînes en CSV, par exemple.
\nPar exemple :
\n{{ value|addslashes }}\nSi value contient "J'utilise Django", le résultat sera "J\\'utilise Django".
capfirstLien vers cette rubrique#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.
\nPar exemple :
\n{{ value|capfirst }}\nSi value contient "django", le résultat sera "Django".
centerLien vers cette rubrique#Centre la valeur dans un champ de largeur donnée.
\nPar exemple :
\n"{{ value|center:"15" }}"\nSi value contient "Django", le résultat sera " Django ".
cutLien vers cette rubrique#Enlève toutes les valeurs en paramètre de la chaîne à filtrer.
\nPar exemple :
\n{{ value|cut:" " }}\nSi value contient "Chaîne avec des espaces", le résultat sera "Chaîneavecdesespaces".
dateLien vers cette rubrique#Met en forme une date selon le format indiqué.
\nUtilise un format semblable à la fonction date() de PHP avec certaines différences.
\n\nChaînes de format disponibles :
\nCaractère de format | \nDescription | \nExemple d’affichage | \n
|---|---|---|
Jour | \n\n | \n |
| \nJour du mois, 2 chiffres complétés si nécessaire par un zéro. | \n
| \n
| \nJour du mois sans zéros initiaux. | \n
| \n
| \nJour de la semaine, abréviation de 3 caractères. | \n
| \n
| \nJour de la semaine, texte complet. | \n
| \n
| \nSuffixe ordinal anglais pour le jour du mois, sur 2 caractères. | \n
| \n
| \nJour de la semaine, chiffre sans zéro initial. | \n
| \n
| \nJour de l’année. | \n
| \n
Semaine | \n\n | \n |
| \nNuméro de semaine dans l’année selon ISO-8601, les semaines commençant le lundi. | \n
| \n
Mois | \n\n | \n |
| \nMois, 2 chiffres, avec zéro initial si nécessaire. | \n
| \n
| \nMois (chiffres) sans zéro initial. | \n
| \n
| \nMois, abréviation de 3 caractères. | \n
| \n
| \nMois, abréviation de 3 caractères en minuscules. | \n
| \n
| \nMois, représentation alternative spécifique à la langue active, habituellement utilisée pour les dates au format étendu. | \n
| \n
| \nMois au format texte long. | \n
| \n
| \nAbréviation du mois dans le style Associated Press. Extension propriétaire. | \n
| \n
| \nNombre de jours du mois indiqué. | \n
| \n
Année | \n\n | \n |
| \nAnnée, 2 chiffres avec zéros initiaux. | \n
| \n
| \nAnnée, 4 chiffres avec zéros initiaux. | \n
| \n
| \nValeur booléenne indiquant s’il s’agit d’une année bissextile. | \n
| \n
| \nAnnée selon numération des semaines ISO-8601 (W) utilisant la semaine intercalaire. Voir Y pour le format d’année plus habituel. | \n
| \n
Heure | \n\n | \n |
| \nHeure, format sur 12 heures sans zéros initiaux. | \n
| \n
| \nHeure, format sur 24 heures sans zéros initiaux. | \n
| \n
| \nHeure, format sur 12 heures. | \n
| \n
| \nHeure, format sur 24 heures. | \n
| \n
| \nMinutes. | \n
| \n
| \nSecondes, 2 chiffres avec zéro initial. | \n
| \n
| \nMicrosecondes. | \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \nHeure, en format heures et minutes sur 12 heures, sans affichage des minutes si elles valent 0. Extension propriétaire. | \n
| \n
| \nHeure, 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. | \n
| \n
Fuseau horaire | \n\n | \n |
| \nNom de fuseau horaire. Différents formats peuvent apparaître, ou même une chaîne vide, en fonction de la date/heure. | \n
| \n
| \nHeure d’été, indication si elle est active ou non. | \n
| \n
| \nDifférence en heures avec le temps de Greenwich. | \n
| \n
| \nFuseau horaire de la machine. | \n
| \n
| \nDé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. | \n
| \n
Date/heure | \n\n | \n |
| \nFormat 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 | \n
| \n
| \nDate mise en forme selon RFC 5322. | \n
| \n
| \nSecondes depuis le temps Unix initial (1er janvier 1970 00:00:00 UTC). | \n\n |
Par exemple :
\n{{ value|date:"D d M Y" }}\nSi 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.
Dans le cas où USE_L10N vaut True et que LANGUAGE_CODE est, par exemple, "es", alors pour :
{{ value|date:"SHORT_DATE_FORMAT" }}\nle 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 }}\nproduit 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" }}\ndefaultLien vers cette rubrique#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 :
\n{{ value|default:"nothing" }}\nSi value contient "" (la chaîne vide), le résultat sera nothing.
default_if_noneLien vers cette rubrique#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 :
\n{{ value|default_if_none:"nothing" }}\nSi value vaut None, le résultat sera nothing.
dictsortLien vers cette rubrique#Accepte une liste de dictionnaires et renvoie cette liste triée par la clé donnée en paramètre.
\nPar exemple :
\n{{ value|dictsort:"name" }}\nSi value contient :
[\n {'name': 'zed', 'age': 19},\n {'name': 'amy', 'age': 22},\n {'name': 'joe', 'age': 31},\n]\nle résultat sera :
\n[\n {'name': 'amy', 'age': 22},\n {'name': 'joe', 'age': 31},\n {'name': 'zed', 'age': 19},\n]\nVous pouvez également faire des choses plus compliquées comme :
\n{% for book in books|dictsort:"author.age" %}\n * {{ book.title }} ({{ book.author.name }})\n{% endfor %}\nSi books est :
[\n {'title': '1984', 'author': {'name': 'George', 'age': 45}},\n {'title': 'Timequake', 'author': {'name': 'Kurt', 'age': 75}},\n {'title': 'Alice', 'author': {'name': 'Lewis', 'age': 33}},\n]\nalors le résultat sera :
\n* Alice (Lewis)\n* 1984 (George)\n* Timequake (Kurt)\ndictsort 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 }}\nSi value contient :
[\n ('a', '42'),\n ('c', 'string'),\n ('b', 'foo'),\n]\nle résultat sera :
\n[\n ('a', '42'),\n ('b', 'foo'),\n ('c', 'string'),\n]\nVous devez passer l’indice comme nombre entier et pas comme chaîne. Le code suivant produit un résultat vide :
\n{{ values|dictsort:"0" }}\nLe tri par éléments à un indice donné n’est pas pris en charge pour les dictionnaires.
\n\ndictsortreversedLien vers cette rubrique#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.
\ndivisiblebyLien vers cette rubrique#Renvoie True si la valeur est divisible par le paramètre.
Par exemple :
\n{{ value|divisibleby:"3" }}\nSi value contient 21, le résultat sera
escapeLien vers cette rubrique#Échappe du code HTML. Plus particulièrement, il effectue les remplacements suivants :
\n< 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 %}\n {{ title|escape }}\n{% endautoescape %}\nescapejsLien vers cette rubrique#Échappe des caractères dans du contenu JavaScript. Cela ne rend pas le texte fiable pour être utilisé dans du HTML ou des gabarits de littéraux JavaScript, mais cela protège des erreurs de syntaxe lors de l’utilisation de gabarits pour générer du JavaScript/JSON.
\nPar exemple :
\n{{ value|escapejs }}\nSi value contient "testing\\r\\njavascript 'string\\" <b>escaping</b>", le résultat sera "testing\\\\u000D\\\\u000Ajavascript \\\\u0027string\\\\u0022 \\\\u003Cb\\\\u003Eescaping\\\\u003C/b\\\\u003E".
filesizeformatLien vers cette rubrique#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 :
\n{{ value|filesizeformat }}\nSI value contient 123456789, le résultat sera 117.7 Mio.
firstLien vers cette rubrique#Renvoie le premier élément de la liste.
\nPar exemple :
\n{{ value|first }}\nSi value contient la liste ['a', 'b', 'c'], le résultat sera 'a'.
floatformatLien vers cette rubrique#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 :
\n
| \nGabarit | \nAffichage | \n
|---|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
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 :
| \nGabarit | \nAffichage | \n
|---|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
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.
\n
| \nGabarit | \nAffichage | \n
|---|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
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 :
| \nGabarit | \nAffichage | \n
|---|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
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) :
| \nGabarit | \nAffichage | \n
|---|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
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) :
| \nGabarit | \nAffichage | \n
|---|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
L’utilisation de floatformat sans paramètre est équivalent à l’utilisation de floatformat avec le paramètre -1.
force_escapeLien vers cette rubrique#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 %}\n {{ body|linebreaks|force_escape }}\n{% endautoescape %}\nget_digitLien vers cette rubrique#É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.
\nPar exemple :
\n{{ value|get_digit:"2" }}\nSI value contient 123456789, le résultat sera 8.
iriencodeLien vers cette rubrique#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.
\nVous pouvez sans problème utiliser ce filtre sur une chaîne ayant déjà passé par le filtre urlencode.
Par exemple :
\n{{ value|iriencode }}\nSi value contient "?test=1&moi=2", le résultat sera "?test=1&moi=2".
joinLien vers cette rubrique#Concatène les éléments d’une liste avec une chaîne de liaison, comme Python le fait avec str.join(list).
Par exemple :
\n{{ value|join:" // " }}\nSi value contient la liste ['a', 'b', 'c'], le résultat sera "a // b // c".
json_scriptLien vers cette rubrique#Transforme un objet Python en JSON de manière sûre, enveloppé dans une balise <script>, pour utilisation à partir de JavaScript.
Paramètre : « id » HTML de la balise <script>.
Par exemple :
\n{{ value|json_script:"hello-data" }}\nSi value contient le dictionnaire {'hello': 'world'}, le résultat sera :
<script id="hello-data" type="application/json">{"hello": "world"}</script>\nOn peut accéder aux données résultantes en JavaScript comme ceci :
\nconst value = JSON.parse(document.getElementById('hello-data').textContent);\nLes 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>\nCeci 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.
\nlastLien vers cette rubrique#Renvoie le dernier élément de la liste.
\nPar exemple :
\n{{ value|last }}\nSi value contient la liste ['a', 'b', 'c', 'd'], le résultat sera 'd'.
lengthLien vers cette rubrique#Renvoie la longueur de la valeur. Cela fonctionne aussi bien pour du texte que des listes.
\nPar exemple :
\n{{ value|length }}\nSi value vaut ['a', 'b', 'c', 'd'] ou "abcd", le résultat sera 4.
Le filtre renvoie 0 pour une variable non définie.
length_isLien vers cette rubrique#Renvoie True si la longueur de la valeur correspond au paramètre, sinon False.
Par exemple :
\n{{ value|length_is:"4" }}\nSi value contient ['a', 'b', 'c', 'd'] ou "abcd", le résultat sera True.
linebreaksLien vers cette rubrique#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 :
\n{{ value|linebreaks }}\nSi value contient "Joël\\nest une limace", le résultat sera <p>Joël<br>est une limace</p>.
linebreaksbrLien vers cette rubrique#Convertit tous les sauts de ligne d’un contenu de texte brut en sauts de ligne HTML (<br>).
Par exemple :
\n{{ value|linebreaksbr }}\nSi value contient "Joël\\nest une limace", le résultat sera Joël<br>est une limace.
linenumbersLien vers cette rubrique#Affiche un texte en numérotant ses lignes.
\nPar exemple :
\n{{ value|linenumbers }}\nSi value contient :
one\ntwo\nthree\nle résultat sera :
\n1. one\n2. two\n3. three\nljustLien vers cette rubrique#Aligne à gauche la valeur dans un champ de largeur donnée.
\nParamètre : taille de champ
\nPar exemple :
\n"{{ value|ljust:"10" }}"\nSi value contient "Django", le résultat sera "Django ".
lowerLien vers cette rubrique#Convertit une chaîne tout en minuscules.
\nPar exemple :
\n{{ value|lower }}\nSi value contient J'aime FOLLEMENT cet album!, le résultat sera j'aime follement cet album!.
make_listLien vers cette rubrique#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.
\nPar exemple :
\n{{ value|make_list }}\nSi 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'].
phone2numericLien vers cette rubrique#Convertit un numéro de téléphone (pouvant contenir des lettres) en son équivalent numérique.
\nLa 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.
\nPar exemple :
\n{{ value|phone2numeric }}\nSi value vaut 800-COLLECT, le résultat sera 800-2655328.
pluralizeLien vers cette rubrique#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 :
\nYou have {{ num_messages }} message{{ num_messages|pluralize }}.\nSi 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 :
\nYou have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}.\nPour 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.
\nExemple :
\nYou have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.\npprintLien vers cette rubrique#Un adaptateur autour de pprint.pprint(), à réserver vraiment pour le débogage.
randomLien vers cette rubrique#Renvoie un élément aléatoire dans la liste indiquée.
\nPar exemple :
\n{{ value|random }}\nSi value contient la liste ['a', 'b', 'c', 'd'], le résultat pourrait être "b".
rjustLien vers cette rubrique#Aligne à droite la valeur dans un champ de largeur donnée.
\nParamètre : taille de champ
\nPar exemple :
\n"{{ value|rjust:"10" }}"\nSi value contient "Django", le résultat sera " Django".
safeLien vers cette rubrique#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.
\n\nsafeseqLien vers cette rubrique#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:", " }}\nVous 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.
sliceLien vers cette rubrique#Renvoie un segment de la liste.
\nUtilise la même syntaxe que la segmentation de listes Python. Voir https://diveinto.org/python3/native-datatypes.html#slicinglists pour une introduction (en anglais).
\nExemple :
\n{{ some_list|slice:":2" }}\nSi some_list contient ['a', 'b', 'c'], le résultat sera ['a', 'b'].
slugifyLien vers cette rubrique#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.
\nPar exemple :
\n{{ value|slugify }}\nSi value contient "Joël est une limace", le résultat sera joel-est-une-limace.
stringformatLien vers cette rubrique#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.
\nPar exemple :
\n{{ value|stringformat:"E" }}\nSI value contient 10, le résultat sera 1.000000E+01.
timeLien vers cette rubrique#Met en forme une heure selon le format indiqué.
\nLe 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 :
\n{{ value|time:"H:i" }}\nSi 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 :
\n{{ value|time:"H\\h i\\m" }}\nLe résultat affiché est « 01h 23m »..
\nUn autre exemple :
\nEn supposant que USE_L10N vaille True et que LANGUAGE_CODE vaille par exemple "de", alors pour :
{{ value|time:"TIME_FORMAT" }}\nle 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 }}\nest identique à :
\n{{ value|time:"TIME_FORMAT" }}\ntimesinceLien vers cette rubrique#Met en forme une date de manière relative à cette date (par ex. « 4 jours, 6 heures »).
\nAccepte 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 }}\nLa comparaison entre des dates/heures naïves et conscientes (en rapport au fuseau horaire) renvoie une chaîne vide.
\nLes 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.
\ntimeuntilLien vers cette rubrique#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 }}\nLa comparaison entre des dates/heures naïves et conscientes (en rapport au fuseau horaire) renvoie une chaîne vide.
\nLes 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.
\ntitleLien vers cette rubrique#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 ».
\nPar exemple :
\n{{ value|title }}\nSi value contient "mon PREMIER article", le résultat sera "Mon Premier Article".
truncatecharsLien vers cette rubrique#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 (« … »).
\nParamètre : le nombre maximum de caractères du résultat
\nPar exemple :
\n{{ value|truncatechars:7 }}\nSi value contient "Joël est une limace", le résultat sera "Joël e…".
truncatechars_htmlLien vers cette rubrique#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 :
\n{{ value|truncatechars_html:7 }}\nSi 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.
\ntruncatewordsLien vers cette rubrique#Tronque une chaîne après un certain nombre de mots.
\nParamètre : le nombre maximum de mots du résultat
\nPar exemple :
\n{{ value|truncatewords:2 }}\nSi 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.
\ntruncatewords_htmlLien vers cette rubrique#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 :
\n{{ value|truncatewords_html:2 }}\nSi 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.
\nunordered_listLien vers cette rubrique#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.
\nIl 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\n<ul>\n <li>Kansas\n <ul>\n <li>Lawrence</li>\n <li>Topeka</li>\n </ul>\n </li>\n <li>Illinois</li>\n</ul>\n</li>\nupperLien vers cette rubrique#Convertit une chaîne tout en majuscules.
\nPar exemple :
\n{{ value|upper }}\nSi value vaut "Joël est une limace", le résultat sera "JOËL EST UNE LIMACE".
urlencodeLien vers cette rubrique#Échappe une valeur pour être incluse dans une URL.
\nPar exemple :
\n{{ value|urlencode }}\nSi 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.
\nSans 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 :
\n{{ value|urlencode:"" }}\nSi value vaut "https://www.example.org/", le résultat sera "https%3A%2F%2Fwww.example.org%2F".
urlizeLien vers cette rubrique#Convertit les URL et les adresses électroniques dans le texte en hyperliens.
\nCette balise de gabarit fonctionne avec des liens préfixés par http://, https:// ou www.. Par exemple, https://goo.gl/aia1t sera converti mais goo.gl/aia1t 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 :
\n{{ value|urlize }}\nSi 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.
urlizetruncLien vers cette rubrique#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.
\nParamè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.
\nPar exemple :
\n{{ value|urlizetrunc:15 }}\nSi 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.
\nwordcountLien vers cette rubrique#Renvoie le nombre de mots.
\nPar exemple :
\n{{ value|wordcount }}\nSi value vaut "Joël est une limace", le résultat sera 4.
wordwrapLien vers cette rubrique#Ajoute des sauts de ligne d’après une longueur de ligne maximale.
\nParamètre : le nombre de caractères après lequel un saut de ligne est rajouté dans le texte.
\nPar exemple :
\n{{ value|wordwrap:5 }}\nSi value vaut Joel is a slug, le résultat sera :
Joel\nis a\nslug\nyesnoLien vers cette rubrique#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 :
\n{{ value|yesno:"yeah,no,maybe" }}\nValeur | \nParamètre | \nAffiche | \n
|---|---|---|
| \n\n |
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n