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.

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 :

{% autoescape on %}
    {{ body }}
{% 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, il suffit de donner 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 %}

Par rétrocompatibilité, la balise {% cycle %} prend encore en charge l’ancienne syntaxe de moindre qualité des précédentes version de Django. Vous ne devriez plus l’utiliser dans de nouveaux projets, mais pour les personnes qui l’utilisent encore, voici à quoi elle ressemble :

{% cycle row1,row2,row3 %}

Avec cette syntaxe, chaque valeur est interprétée comme chaîne littérale et il n’est pas possible d’indiquer des valeurs de variables, ni virgules littérales, ni espaces. Ne vous avons-nous pas prévenu de ne pas utiliser cette syntaxe dans de nouveaux projets ?

debug

Affiche tout un lot d’informations de débogage, y compris le contexte actuel et les modules importés.

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

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 False. N’affiche rien si toutes les valeurs transmises valent False.

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

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
forloop.counter	L’itération actuelle de la boucle (index à partir de 1)
forloop.counter0	L’itération actuelle de la boucle (index à partir de 0)
forloop.revcounter	Le nombre d’itérations à partir de la fin de la boucle (index à partir de 1)
forloop.revcounter0	Le nombre d’itérations à partir de la fin de la boucle (index à partir de 0)
forloop.first	True si la boucle est dans sa première itération
forloop.last	True si la boucle est dans sa dernière itération
forloop.parentloop	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 ==, !=, <, >, <=, >= et in (dans), 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.

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

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 :

• or
• 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 %}

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

ifequal et ifnotequal

{% ifequal a b %} ... {% endifequal %} est une ancienne façon d’écrire {% if a == b %} ... {% endif %}. De même, {% ifnotequal a b %} ... {% endifnotequal %} est maintenant remplacé par {% if a != b %} ... {% endif %}. Les balises ifequal et ifnotequal seront rendues obsolètes dans une future version.

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.

1. 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 %}
   

2. 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" %}

Cet exemple inclut le contenu du gabarit dont le nom est contenu dans la variable template_name:

{% include template_name %}

Changed in Django 1.7:

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.

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 :

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

Si le gabarit inclus provoque une exception lors de son affichage (y compris par son absence ou par des erreurs de syntaxe), le comportement varie en fonction de l’option debug du moteur de gabarit (quand elle n’est pas explicitement définie, la valeur par défaut de cette option correspond à DEBUG). Lorsque le mode de débogage est actif, une exception comme TemplateDoesNotExist ou TemplateSyntaxError est générée ; sinon, {% include %} ignore toute exception qui survient lors du processus de rendu du gabarit imbriqué et renvoie une chaîne vide.

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

New in Django 1.8:

La balise se trouvait précédemment dans django.contrib.webdesign.

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
count	Un nombre (ou une variable) contenant le nombre de paragraphes ou de mots à produire (1 par défaut).
method	Indiquez w pour des mots, p pour des paragraphes HTML ou b pour des blocs de paragraphe de texte brut (b est la valeur par défaut).
random	Le mot random, quand il est indiqué, n’utilise pas le paragraphe connu (« Lorem ipsum dolor sit amet... ») lors de la production de texte.

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 blocktrans par exemple :

{% now "Y" as current_year %}
{% blocktrans %}Copyright {{ current_year }}{% endblocktrans %}

New in Django 1.8.

La possibilité d’utiliser la syntaxe as a été ajoutée.

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 « places » 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 item in country.list %}
          <li>{{ item.name }}: {{ item.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. Chaque objet groupe possède deux attributs :

• 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').

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

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

ssi

Obsolète depuis la version 1.8: Cette balise est obsolète et sera supprimée dans Django 1.10. Utilisez la balise include à la place.

Affiche le contenu du fichier indiqué dans la page.

Comme une balise include simple, {% ssi %} inclut le contenu d’un autre fichier, qui doit être indiqué avec son chemin absolu, dans la page actuelle :

{% ssi '/home/html/ljworld.com/includes/right_generic.html' %}

Le premier paramètre de ssi peut être une chaîne entre guillemets ou toute autre variable de contexte.

Si le paramètre facultatif parsed est fourni, le contenu du fichier inclus est évalué comme du code de gabarit, à l’intérieur du contexte en cours :

{% ssi '/home/html/ljworld.com/includes/right_generic.html' parsed %}

Notez que si vous utilisez {% ssi %}, vous devez aussi définir 'allowed_include_roots' dans le réglage OPTIONS du moteur de gabarit par mesure de sécurité.

Note

Avec la balise ssi et le paramètre parsed, il n’existe pas d’état partagé entre les fichiers – chaque inclusion est un processus d’affichage complètement indépendant. Cela signifie qu’il n’est par exemple pas possible de définir des blocs ou de modifier le contexte de la page actuelle en utilisant le fichier inclus.

Voir aussi {% include %}.

templatetag

Affiche l’une des séquences de caractères utilisées dans la syntaxe des balises de gabarit.

Comme le système des gabarits n’a pas de concept d’« échappement », si vous souhaitez afficher des parties de syntaxe utilisées dans les balises de gabarit, vous devez utiliser la balise {% templatetag %}.

Le paramètre indique quelle séquence de gabarit vous voulez afficher :

Paramètre	Affiche
openblock	{%
closeblock	%}
openvariable	{{
closevariable	}}
openbrace	{
closebrace	}
opencomment	{#
closecomment	#}

Exemple d’utilisation :

{% templatetag openblock %} url 'entry_list' {% templatetag closeblock %}

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

('^client/([0-9]+)/$', 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 :

('^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.

Obsolète depuis la version 1.8: Vous pouvez aussi transmettre un chemin Python pointé vers une fonction de vue, mais cette syntaxe est obsolète et sera supprimée dans Django 1.10 :

{% url 'path.to.some_view' v1 v2 %}

Avertissement

N’oubliez pas d’entourer le nom d’url() 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 blocktrans, comme ceci :

{% widthratio this_value max_value max_width as width %}
{% blocktrans %}The width is: {{ width }}{% endblocktrans %}

Changed in Django 1.7:

La possibilité d’utiliser « as » avec cette balise, comme le montre l’exemple ci-dessus, a été ajoutée.

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 (http://php.net/date) 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
a	'a.m.' ou 'p.m.' (notez que c’est légèrement différent de l’affichage PHP, par la présence de points correspondant au style Associated Press).	'a.m.'
A	'AM' ou 'PM'.	'AM'
b	Mois, abréviation de 3 caractères en minuscules.	'jan'
B	Non implémenté.
c	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 datetime.tzinfo).	2008-01-02T10:30:00.000123+02:00 ou 2008-01-02T10:30:00.000123 si la date/heure est naïve
d	Jour du mois, 2 chiffres complétés si nécessaire par un zéro.	'01' à '31'
D	Jour de la semaine, abréviation de 3 caractères.	'ven'
e	Nom de fuseau horaire. Différents formats peuvent apparaître, ou même une chaîne vide, en fonction de la date/heure.	'', 'GMT', '-500', 'US/Eastern', etc.
E	Mois, représentation alternative spécifique à la langue active, habituellement utilisée pour les dates au format étendu.	'listopada' (pour le polonais, contrairement à 'Listopad')
f	Heure, en format heures et minutes sur 12 heures, sans affichage des minutes si elles valent 0. Extension propriétaire.	'1', '1:30'
F	Mois au format texte long.	'janvier'
g	Heure, format sur 12 heures sans zéros initiaux.	'1' à '12'
G	Heure, format sur 24 heures sans zéros initiaux.	'0' à '23'
h	Heure, format sur 12 heures.	'01' à '12'
H	Heure, format sur 24 heures.	'00' à '23'
i	Minutes.	'00' à '59'
I	Heure d’été, indication si elle est active ou non.	'1' ou '0'
j	Jour du mois sans zéros initiaux.	'1' à '31'
l	Jour de la semaine, texte complet.	'vendredi'
L	Valeur booléenne indiquant s’il s’agit d’une année bissextile.	True ou False
m	Mois, 2 chiffres, avec zéro initial si nécessaire.	'01' à '12'
M	Mois, abréviation de 3 caractères.	'jan'
n	Mois (chiffres) sans zéro initial.	'1' à '12'
N	Abréviation du mois dans le style Associated Press. Extension propriétaire.	'jan.', 'fév.', 'mars', 'mai'
o	Année selon numération des semaines ISO-8601 (W)	'1999'
O	Différence en heures avec le temps de Greenwich.	'+0200'
P	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.	'1 a.m.', '1:30 p.m.', 'minuit', 'midi', '12:30 p.m.'
r	Date mise en forme selon RFC 2822.	'ven, 22 Nov 2013 18:41:16 +0100'
s	Secondes, 2 chiffres avec zéro initial.	'00' à '59'
S	Suffixe ordinal anglais pour le jour du mois, sur 2 caractères.	'st', 'nd', 'rd' ou 'th'
t	Nombre de jours du mois indiqué.	28 à 31
T	Fuseau horaire de la machine.	'EST', 'MDT'
u	Microsecondes.	000000 à 999999
U	Secondes depuis le temps Unix initial (1er janvier 1970 00:00:00 UTC).
w	Jour de la semaine, chiffre sans zéro initial.	'0' (dimanche) à '6' (samedi)
W	Numéro de semaine dans l’année selon ISO-8601, les semaines commençant le lundi.	1, 53
y	Année sur 2 chiffres.	'99'
Y	Année sur 4 chiffres.	'1999'
z	Jour de l’année.	0 à 365
Z	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.	-43200 à 43200

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.

Dans le cas où USE_L10N vaut True et que LANGUAGE_CODE est, 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 :

{{ value|date }}

…c’est la chaîne de format définie dans le réglage DATE_FORMAT qui est utilisé, sans appliquer aucune régionalisation.

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 le texte "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}},
]

alors le résultat sera :

* Alice (Lewis)
* 1984 (George)
* Timequake (Kurt)

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 &lt;

• > est converti en &gt;

• ' (apostrophe) est converti en &#39;

• " (guillemet) est converti en &quot;

• & est converti en &amp;

L’échappement n’est appliqué qu’au moment de l’affichage de la chaîne, l’emplacement de escape dans une chaîne de filtres n’est donc pas important : il sera toujours appliqué comme s’il était le dernier filtre. Si vous souhaitez que l’échappement se produise immédiatement, utilisez le filtre force_escape.

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

escapejs

Échappe des caractères dans du contenu JavaScript. Cela ne rend pas le texte fiable pour être utilisé dans du HTML, mais cela protège des erreurs de syntaxe lors de l’utilisation de gabarits pour générer du JavaScript/JSON.

Par exemple :

{{ value|escapejs }}

Si value contient "testing\r\njavascript \'string" <b>escaping</b>", le résultat sera "testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E".

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 :

valeur	Gabarit	Affichage
34.23234	{{ valeur|floatformat }}	34,2
34.00000	{{ valeur|floatformat }}	34
34.26000	{{ valeur|floatformat }}	34,3

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 :

valeur	Gabarit	Affichage
34.23234	{{ valeur|floatformat:3 }}	34,232
34.00000	{{ valeur|floatformat:3 }}	34,000
34.26000	{{ valeur|floatformat:3 }}	34,260

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.

valeur	Gabarit	Affichage
34.23234	{{ valeur|floatformat:"0" }}	34
34.00000	{{ valeur|floatformat:"0" }}	34
39.56000	{{ valeur|floatformat:"0" }}	40

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 :

valeur	Gabarit	Affichage
34.23234	{{ valeur|floatformat:"-3" }}	34,232
34.00000	{{ valeur|floatformat:"-3" }}	34
34.26000	{{ valeur|floatformat:"-3" }}	34,260

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=1&moi=2", le résultat sera "?test=1&amp;moi=2".

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

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.

Changed in Django 1.8:

Le filtre renvoie 0 pour une variable non définie. Précédemment, il renvoyait une chaîne vide.

length_is

Renvoie True si la longueur de la valeur correspond au paramètre, sinon False.

Par exemple :

{{ value|length_is:"4" }}

Si value contient ['a', 'b', 'c', 'd'] ou "abcd", le résultat sera True.

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>Joel<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 Joel<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 unicode 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. 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 blocktrans 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".

removetags

Obsolète depuis la version 1.8: removetags ne peut pas garantir que le résultat soit un contenu HTML sûr ; la balise a été rendue obsolète pour des raisons de sécurité. Envisagez plutôt l’emploi de bleach.

Supprime de la valeur affichée une liste de balises [X]HTML séparées par des espaces.

Par exemple :

{{ value|removetags:"b span" }}

Si value contient "<b>Joël</b> <button>est</button> une <span>limace</span>", le résultat non échappé sera "Joël <button>est</button> une limace".

Notez que ce filtre est sensible à la casse.

Si value contient "<B>Joël</B> <button>est</button> une <span>limace</span>", le résultat non échappé sera "<B>Joël</B> <button>est</button> une limace".

Aucune garantie de sécurité

Notez que removetags ne donne aucune garantie que le contenu résultant ne contienne plus de balisage HTML. Plus particulièrement, il ne fonctionne pas de manière récursive, ce qui fait qu’une valeur d’entrée comme "<sc<script>ript>alert('XSS')</sc</script>ript>" ne sera pas sûre même si vous appliquez |removetags:"script". N’appliquez donc JAMAIS le filtre safe sur du contenu provenant des utilisateurs et ayant passé par removetags. Si vous recherchez une solution plus solide, vous pouvez utiliser la bibliothèque Python bleach, notamment sa méthode clean.

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 de listes Python. Voir http://www.diveintopython3.net/native-datatypes.html#slicinglists pour une introduction (en anglais).

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 de mise en forme de Python, à l’exclusion du caractère « % » initial.

Voir https://docs.python.org/library/stdtypes.html#string-formatting-operations pour la documentation sur les chaînes de format de Python.

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, vous pouvez utiliser la bibliothèque Python bleach, notamment sa méthode clean.

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

Un autre exemple :

En supposant que USE_L10N vaille True et que LANGUAGE_CODE vaille par exemple "de", alors pour :

{{ value|time:"TIME_FORMAT" }}

le résultat sera "01:23:00" (le spécificateur de format "TIME_FORMAT" de la locale de fournie par Django contient "H:i:s").

Le filtre time n’accepte dans la chaîne de format que les paramètres concernant l’heure du jour, et non la date (pour des raisons évidentes). 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 :

{{ value|time }}

…c’est la chaîne de format définie dans le réglage TIME_FORMAT qui sera utilisée, sans appliquer de régionalisation.

Changed in Django 1.7:

La capacité de recevoir et d’agir sur des valeurs contenant des informations de fuseau horaire a été ajoutée dans Django 1.7.

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 pas une suite traduisible de points de suspension (« ... »).

Paramètre : le nombre maximum de caractères du résultat

Par exemple :

{{ value|truncatechars:9 }}

Si value contient "Joël est une limace", le résultat sera "Joël e...".

truncatechars_html

New in Django 1.7.

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:9 }}

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.

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.

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>

Obsolète depuis la version 1.8: Un format d’entrée plus ancien, plus restrictif et verbeux est également pris en charge : ['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]. La prise en charge de cette syntaxe sera supprimée dans Django 1.10.

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 "http://www.example.org/foo?a=b&c=d", le résultat sera "http%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 "http://www.example.org/", le résultat sera "http%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, http://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.

Changed in Django 1.8:

La prise en charge de liens ne contenant qu’un domaine et contenant des caractères après le domaine de premier niveau (par exemple djangoproject.com/ et djangoproject.com/download/) a été ajoutée.

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 à [e-mail]", le résultat sera "Envoyez les questions à <a href="mailto:[e-mail]">[e-mail]</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, les choses ne se passeront pas comme prévu. N’appliquez ce filtre qu’à du texte pur.

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.djangopr...</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
True		yes
True	"yeah,no,maybe"	yeah
False	"yeah,no,maybe"	no
None	"yeah,no,maybe"	maybe
None	"yeah,no"	no (convertit None en False si aucune correspondance n’est indiquée pour None)

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

Voir Internationalisation : dans le code des gabarits.

l10n

Cette bibliothèque permet de contrôler la régionalisation des valeurs dans les gabarits. Il suffit de charger la bibliothèque en utilisant {% load l10n %}, mais il est souvent préférable de définir aussi USE_L10N à True pour que la régionalisation soit active par défaut.

Voir Contrôle de la régionalisation dans les gabarits.

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. Vous pouvez l’utiliser dans tous les cas, indépendamment de l’utilisation de RequestContext.

{% 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 %}" type="text/css" 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 }}"></img>

Note

L’application contribuée staticfiles fournit également une balise de gabarit static qui utilise le réglage STATICFILES_STORAGE de staticfiles' pour construire l’URL du chemin donné (plutôt que de simplement combiner STATIC_URL et le chemin donné avec urllib.parse.urljoin()). Préférez cette balise si vous êtes confronté à une situation plus spéciale comme l’utilisation d’un service en nuage pour servir les fichiers statiques:

{% load static from staticfiles %}
<img src="{% static "images/hi.jpg" %}" alt="Hi!" />

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.