Balises et filtres de gabarit intégrésLien vers cette rubrique#

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

{% autoescape on %}
    {{ body }}
{% endautoescape %}

blockLien vers cette rubrique#

Définit un bloc pouvant être surchargé par les gabarits enfants. Voir Héritage des gabarits pour plus d’informations.

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

<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_tokenLien vers cette rubrique#

Cette balise est utilisée pour la protection CSRF, comme décrit dans la documentation Cross Site Request Forgeries.

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

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

Il 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 tout un lot d’informations de débogage, y compris le contexte actuel et les modules importés.

extendsLien vers cette rubrique#

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.

En principe, le nom du gabarit est relatif au répertoire racine du chargeur de gabarits. Un paramètre textuel peut aussi être un chemin relatif commençant par ./ ou ../. Par exemple, en admettant la structure de répertoires suivante :

dir1/
    template.html
    base2.html
    my/
        base3.html
base1.html

Dans template.html, les chemins suivants seraient valides :

{% extends "./base2.html" %}
{% extends "../base1.html" %}
{% extends "./my/base3.html" %}

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

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

firstofLien vers cette rubrique#

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

Vous 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>
{% 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 :

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

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

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

{% if athlete_list and coach_list or cheerleader_list %}

if (athlete_list and coach_list) or cheerleader_list

{% if somevar == "x" %}
  This appears if variable somevar equals the string "x"
{% endif %}

{% if somevar != "x" %}
  This appears if variable somevar does not equal the string "x",
  or if somevar is not found in the context
{% endif %}

{% if somevar < 100 %}
  This appears if variable somevar is less than 100.
{% endif %}

{% if somevar > 0 %}
  This appears if variable somevar is greater than 0.
{% endif %}

{% if somevar <= 100 %}
  This appears if variable somevar is less than 100 or equal to 100.
{% endif %}

{% if somevar >= 1 %}
  This appears if variable somevar is greater than 1 or equal to 1.
{% endif %}

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

{% if somevar is True %}
  This appears if and only if somevar is True.
{% endif %}

{% if somevar is None %}
  This appears if somevar is None, or if somevar is not found in the context.
{% endif %}

{% if somevar is not True %}
  This appears if somevar is not True, or if somevar is not found in the
  context.
{% endif %}

{% if somevar is not None %}
  This appears if and only if somevar is not None.
{% endif %}

{% if messages|length >= 100 %}
   You have lots of messages today!
{% endif %}

{% if a == b or c == d and e %}

(a == b) or ((c == d) and e)

{% if a > b > c %}  (WRONG)

{% if a > b and b > c %}

ifequal et ifnotequalLien vers cette rubrique#

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

ifchangedLien vers cette rubrique#

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 :

   Django template

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

   Django template

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

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

Le nom du gabarit peut être soit une variable, soit une chaîne fixe entre guillemets, simples ou doubles.

Cet exemple inclut le contenu du gabarit "foo/bar.html":

{% include "foo/bar.html" %}

En principe, le nom du gabarit est relatif au répertoire racine du chargeur de gabarits. Un paramètre textuel peut aussi être un chemin relatif commençant par ./ ou ../, comme expliqué dans la documentation de la balise extends.

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

{% include template_name %}

La variable peut aussi être tout objet possédant une méthode render() acceptant un contexte. Cela permet de référencer un objet Template compilé dans votre contexte.

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 :

  Django template

  {% include "name_snippet.html" %}
  

• Le gabarit name_snippet.html:

  Django template

  {{ 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. Lorsque le mode débogage est désactivé, {% include %} journalise un avertissement dans le journaliseur django.template avec l’exception qui survient lors du processus de rendu du gabarit imbriqué et renvoie une chaîne vide.

loadLien vers cette rubrique#

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.

loremLien vers cette rubrique#

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 :

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.

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 :

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

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

regroupLien vers cette rubrique#

Regroupe une liste d’objets semblables par un attribut commun.

La meilleure façon d’illustrer cette balise complexe est de donner un exemple : disons que cities contient une liste de villes représentées par des dictionnaires contenant les clés "name", "population" et "country":

cities = [
    {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
    {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
    {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
    {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
    {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]

…et vous aimeriez afficher une liste hiérarchique triée par pays, comme ceci :

• India

  • Mumbai: 19,000,000

  • Calcutta: 15,000,000

• USA

  • New York: 20,000,000

  • Chicago: 7,000,000

• Japan

  • Tokyo: 33,000,000

Vous pouvez utiliser la balise {% regroup %} pour grouper la liste des villes par pays. L’extrait de code de gabarit suivant effectue cela :

{% regroup cities by country as country_list %}

<ul>
{% for country in country_list %}
    <li>{{ country.grouper }}
    <ul>
        {% for city in country.list %}
          <li>{{ city.name }}: {{ city.population }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Parcourons cet exemple. {% regroup %} accepte trois paramètres : la liste que vous souhaitez regrouper, l’attribut sur lequel grouper et le nom de la liste résultante. Dans ce cas, nous regroupons la liste cities par l’attribut country et nommons le résultat country_list.

{% regroup %} produit une liste (dans ce cas, country_list) d”objets groupes. Les objets groupes sont des instances de namedtuple() contenant deux champs :

• grouper, l’élément qui a servi au groupement (par ex. la chaîne « India » ou « Japan »).

• list, une liste de tous les éléments du groupe (par ex. une liste de toutes les villes 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 %}

<ul>
{% for country, local_cities in country_list %}
    <li>{{ country }}
    <ul>
        {% for city in local_cities %}
          <li>{{ city.name }}: {{ city.population }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Notez que {% regroup %} ne trie pas ce qu’il reçoit ! Notre exemple compte sur le fait que la liste cities est préalablement triée par country. Si la liste cities n’était pas triée par pays, le regroupement aurait naïvement affiché plus d’un groupe par pays. Par exemple, si la liste cities contenait ceci (notez que les pays ne sont pas regroupés) :

cities = [
    {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
    {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
    {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
    {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
    {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]

Avec ce contenu dans cities, l’exemple de code de gabarit pour {% regroup %} ci-dessus produirait le résultat suivant :

• India

  • Mumbai: 19,000,000

• USA

  • New York: 20,000,000

• India

  • Calcutta: 15,000,000

• USA

  • Chicago: 7,000,000

• Japan

  • Tokyo: 33,000,000

La solution la plus simple à ce problème est de s’assurer au niveau de la vue que les données sont triées d’après le critère que vous voulez utiliser pour l’affichage.

Un autre solution est de trier les données dans le gabarit avec le filtre dictsort, pour autant que les données soient constituées d’une liste de dictionnaires :

{% regroup cities|dictsort:"country" by country as country_list %}

{% regroup cities by country.description as country_list %}

{% regroup cities by get_country_display as country_list %}

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 :

{% for coach in coach_list %}
    <h1>{{ coach.name }}</h1>
    {% for athlete in coach.athlete_set.all %}
        <p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>
    {% endfor %}
    {% resetcycle %}
{% endfor %}

Cet exemple produit le code HTML suivant :

<h1>José Mourinho</h1>
<p class="odd">Thibaut Courtois</p>
<p class="even">John Terry</p>
<p class="odd">Eden Hazard</p>

<h1>Carlo Ancelotti</h1>
<p class="odd">Manuel Neuer</p>
<p class="even">Thomas Müller</p>

Remarquez comme le premier bloc se termine avec class="odd" et le nouveau qui commence avec class="odd". Sans la balise {% resetcycle %}, le second bloc aurait commencé avec class="even".

Il est aussi possible de réinitialiser les balises cycle nommées :

{% for item in list %}
    <p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}">
        {{ item.data }}
    </p>
    {% ifchanged item.category %}
        <h1>{{ item.category }}</h1>
        {% if not forloop.first %}{% resetcycle tick %}{% endif %}
    {% endifchanged %}
{% endfor %}

Dans cet exemple, nous avons à la fois les lignes alternées pair/impair et une ligne « principale » toutes les cinq lignes. Seul le cycle des cinq lignes est réinitialisé lorsqu’une catégorie change.

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

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

templatetagLien vers cette rubrique#

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 :

Exemple d’utilisation :

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

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 :

{% url 'some-url-name' v1 v2 %}

Le premier paramètre est un nom de motif d’URL. Cela peut être une chaîne littérale entre guillemets ou une variable de contexte. Des paramètres supplémentaires sont facultatifs et sont fournis sous forme de valeurs séparées par des espaces qui seront utilisées comme paramètres de l’URL. L’exemple ci-dessus montre comment passer des paramètres positionnels. Il est aussi possible d’utiliser la syntaxe par mot-clé

{% url 'some-url-name' arg1=v1 arg2=v2 %}

Ne mélangez pas la syntaxe positionnelle avec la syntaxe par mot-clé dans le même appel. Tous les paramètres requis par la configuration d’URL doivent être présents.

Par exemple, supposons que vous avez une vue, app_views.client, dont la configuration d’URL accepte un identifiant de client (ici, client() est une méthode dans le fichier de vues app_views.py). La ligne de configuration d’URL pourrait ressembler à ceci :

path('client/<int:id>/', app_views.client, name='app-views-client')

Si la configuration d’URL de cette application est incluse dans la configuration d’URL du projet par un chemin tel que celui-ci :

path('clients/', include('project_name.app_name.urls'))

…vous pouvez alors dans le gabarit créer un lien vers cette vue comme ceci :

{% url 'app-views-client' client.id %}

La balise de gabarit affichera le texte /clients/client/123/.

Notez que si l’URL que vous résolvez n’existe pas, vous obtiendrez une exception NoReverseMatch, ce qui provoquera l’affichage d’une page d’erreur sur votre site.

Si vous aimeriez récupérer une URL sans l’afficher, vous pouvez effectuer un appel un peu différent :

{% url 'some-url-name' arg arg2 as the_url %}

<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>

La portée de la variable créée par la syntaxe as var est le {% block %} dans lequel la balise {% url %} apparaît.

Cette syntaxe {% url ... as var %} ne produira pas d’erreur si la vue est manquante. En pratique, vous allez utiliser cela pour des liens vers des vues qui sont facultatives :

{% url 'some-url-name' as the_url %}
{% if the_url %}
  <a href="{{ the_url }}">Link to optional stuff</a>
{% endif %}

Si vous souhaitez récupérer une URL avec espace de noms, indiquez le nom entièrement qualifié :

{% url 'myapp:view-name' %}

La stratégie habituelle de résolution d’URL avec espace de noms sera respectée, y compris l’usage d’indicateurs fournis par le contexte comme l’application actuelle.

verbatimLien vers cette rubrique#

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

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

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

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

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

addLien vers cette rubrique#

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

addslashesLien vers cette rubrique#

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

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.

Par exemple :

{{ value|capfirst }}

Si value contient "django", le résultat sera "Django".

centerLien vers cette rubrique#

Centre la valeur dans un champ de largeur donnée.

Par exemple :

"{{ value|center:"15" }}"

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

Par exemple :

{{ value|cut:" " }}

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

Utilise un format semblable à la fonction date() de PHP (https://php.net/date) avec certaines différences.

Chaînes de format disponibles :

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, c’est le format DATE_FORMAT qui est utilisé. Avec des réglages semblables à l’exemple précédent :

{{ value|date }}

produit 9 de Enero de 2008 (la chaîne de format DATE_FORMAT de la locale es étant r'j \d\e F \d\e Y').

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

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

{{ value|default:"nothing" }}

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

{{ value|default_if_none:"nothing" }}

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

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)

dictsort peut aussi trier une liste de listes (ou tout autre objet implémentant __getitem__()) par des éléments à un indice donné. Par exemple :

{{ value|dictsort:0 }}

Si value contient :

[
    ('a', '42'),
    ('c', 'string'),
    ('b', 'foo'),
]

le résultat sera :

[
    ('a', '42'),
    ('b', 'foo'),
    ('c', 'string'),
]

Vous devez passer l’indice comme nombre entier et pas comme chaîne. Le code suivant produit un résultat vide :

{{ values|dictsort:"0" }}

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

divisiblebyLien vers cette rubrique#

Renvoie True si la valeur est divisible par le paramètre.

Par exemple :

{{ value|divisibleby:"3" }}

Si value contient 21, le résultat sera

escapeLien vers cette rubrique#

Échappe du code HTML. Plus particulièrement, il effectue les remplacements suivants :

• < est converti en <

• > est converti en >

• ' (apostrophe) est converti en '

• " (guillemet) est converti en "

• & est converti en &

L’application de escape à une variable qui doit normalement subir l’échappement automatique de son résultat ne fera qu’effectuer un contrôle d’échappement supplémentaire. On peut donc utiliser cette fonction sans souci même dans un contexte d’échappement automatique. Si vous souhaitez forcer l’échappement réel dans tous les cas, utilisez le filtre force_escape.

Par exemple, vous pouvez appliquer escape à certains champs lorsque autoescape n’est pas actif :

{% autoescape off %}
    {{ title|escape }}
{% endautoescape %}

escapejsLien vers cette rubrique#

Escapes characters for use in JavaScript strings. This does not make the string safe for use in HTML or JavaScript template literals, but does protect you from syntax errors when using templates to generate 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".

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 :

{{ value|filesizeformat }}

SI value contient 123456789, le résultat sera 117.7 Mio.

firstLien vers cette rubrique#

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

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 :

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 :

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.

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 :

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 %}
    {{ body|linebreaks|force_escape }}
{% endautoescape %}

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

Par exemple :

{{ value|get_digit:"2" }}

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

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

{{ value|join:" // " }}

Si value contient la liste ['a', 'b', 'c'], le résultat sera "a // b // c".

lastLien vers cette rubrique#

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

lengthLien vers cette rubrique#

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

Par exemple :

{{ value|length }}

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

Le filtre renvoie 0 pour une variable non définie.

length_isLien vers cette rubrique#

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.

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 :

{{ value|linebreaks }}

Si value contient "Joël\nest une limace", le résultat sera <p>Joel<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 :

{{ value|linebreaksbr }}

Si value contient "Joël\nest une limace", le résultat sera Joel<br />est une limace.

linenumbersLien vers cette rubrique#

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

ljustLien vers cette rubrique#

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

lowerLien vers cette rubrique#

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

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

phone2numericLien vers cette rubrique#

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.

pluralizeLien vers cette rubrique#

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

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

Par exemple :

{{ value|random }}

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

Paramètre : taille de champ

Par exemple :

"{{ value|rjust:"10" }}"

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

safeseqLien 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:", " }}

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.

sliceLien vers cette rubrique#

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

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.

Par exemple :

{{ value|slugify }}

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

Par exemple :

{{ value|stringformat:"E" }}

SI value contient 10, le résultat sera 1.000000E+01.

striptagsLien vers cette rubrique#

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

timeLien vers cette rubrique#

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" (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 (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, c’est le format TIME_FORMAT qui est utilisé :

{{ value|time }}

est identique à :

{{ value|time:"TIME_FORMAT" }}

timesinceLien vers cette rubrique#

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.

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

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.

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

Par exemple :

{{ value|title }}

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

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

truncatewordsLien vers cette rubrique#

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

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

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>

upperLien vers cette rubrique#

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

urlencodeLien vers cette rubrique#

Échappe une valeur pour être incluse dans une URL.

Par exemple :

{{ value|urlencode }}

Si value vaut "https://www.example.org/foo?a=b&c=d", le résultat sera "https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd".

Il est possible de fournir un paramètre facultatif contenant les caractères qui ne doivent pas être échappés.

Sans ce paramètre, le caractère « / » est considéré comme sûr. Il est possible de fournir une chaîne vide pour indiquer que tous les caractères doivent être échappés. Par exemple :

{{ value|urlencode:"" }}

Si value vaut "https://www.example.org/", le résultat sera "https%3A%2F%2Fwww.example.org%2F".

urlizeLien vers cette rubrique#

Convertit les URL et les adresses électroniques dans le texte en hyperliens.

Cette balise de gabarit fonctionne avec des liens préfixés par http://, https:// ou www.. Par exemple, https://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 :

{{ value|urlize }}

Si value vaut "Visitez www.djangoproject.com", le résultat sera "Visitez <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproject.com</a>".

En plus des liens de type Web, urlize convertit aussi les adresses électroniques en liens mailto:. Si value contient "Envoyez les questions à foo@example.com", le résultat sera "Envoyez les questions à <a href="mailto:foo@example.com">foo@example.com</a>".

Le filtre urlize accepte également un paramètre facultatif autoescape. Si celui-ci vaut True, le texte du lien et les URL seront échappés par le filtre escape de Django. La valeur par défaut de autoescape est True.

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.

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.

wordcountLien vers cette rubrique#

Renvoie le nombre de mots.

Par exemple :

{{ value|wordcount }}

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

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

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

{{ value|yesno:"yeah,no,maybe" }}

i18nLien vers cette rubrique#

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.

l10nLien vers cette rubrique#

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.

tzLien vers cette rubrique#

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.

django.contrib.humanizeLien vers cette rubrique#

Un ensemble de filtres de gabarit utiles pour ajouter une touche « humaine » aux données. Voir django.contrib.humanize.

staticLien vers cette rubrique#

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

{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />

{% load static %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}"></img>

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

{% 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!" />

{% load static %}
<body data-media-url="{% get_media_prefix %}">