Pour des variables individuelles

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

Ceci sera échappé : {{ data }}
Ceci ne sera pas échappé : {{ data|safe }}

Pensez à safe comme un raccourci pour safe from further escaping (libéré d'un échappement ultérieur) ou can be safely interpreted as HTML (peut être interprété comme de l'HTML en toute sécurité). Dans cet exemple, si data contient '<b>', le résultat sera:

Ceci sera échappé : <b>
Ceci ne sera pas échappé : <b>

Pour des blocs de templates

Pour contrôler l'échappement automatique des templates, il faut inclure le template (ou juste une section particulière de celui-ci) dans le tag autoescape, comme ceci:

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

Le tag autoescape a pour argument on ou off. Parfois vous pouvez vouloir forcer l'échappement automatique quand il serait par ailleurs désactivé. Voici un exemple de template:

L'échappement automatique est activé par défaut. Hello, {{ name }}

{% autoescape off %}
    Ceci ne sera pas échappé automatiquement : {{ data }}

    Ni ceci : {{ other_data }}
    {% autoescape on %}
        L'échappement automatique s'applique à nouveau : {{ name }}
    {% endautoescape %}

Le tag d'échappement automatique transfère son effet aux templates qui dérivent du template courant et aux templates inclus par le tag include, comme pour tous les tags de block. Par exemple:

# base.html

{% autoescape off %}
<h1>{% block title %}{% endblock %}</h1>
{% block content %}
{% endblock %}
{% endautoescape %}


# child.html

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

Comme l'échappement automatique est désactivé dans le template de base, il le sera également dans le template enfant, ce qui donnera l'HTML suivant après rendu lorsque la variable greeting contient la chaîne <b>Hello!<b>

<h1>This & that</h1>
<b>Hello !</b>

autoescape

Nouveau dans la version de développement de Django

Contrôle le comportement courant de l'échappement automatique. Prend on ou off en argument, ce qui détermine si l'échappement automatique est actif à l'intérieur du bloc.

Quand l'échappement automatique est actif, tous les contenus de variables se voient appliquer l'échappement de l'HTML avant l'affichage du résultat dans le rendu final (mais après que tous les filtres aient été appliqués). C'est équivalent à appliquer le filtre escape manuellement à toutes les variables.

Les seules exceptions sont les variables qui sont déjà marquées comme "safe" et donc libres d'échappement, soit par le code qui a fourni et instancié la variable, soit parce que les filtres safe ou escape lui sont appliqués.

block

Définit un bloc qui peut être surchargé par les templates enfants. Voir Héritage des templates pour plus d'informations.

comment

Tout ce qui se trouve entre {% comment %} et {% endcomment %} est ignoré.

cycle

Modifié dans la version de développement de Django Parcourt en boucle les chaînes de caractères ou les variables fournies à chaque fois que ce tag est rencontré.

Dans une boucle, passe à la valeur suivante parmi les chaînes et variables fournies à chaque itération:

{% for o in some_list %}
    <tr class="{% cycle 'row1' 'row2' rowvar %}">
        ...
    </tr>
{% endfor %}

En dehors d'une boucle, donne à la liste un nom unique la première fois que vous y faites référence, puis utilise chaque valeur de celle-ci successivement en bouclant en fin de liste:

<tr class="{% cycle 'row1' 'row2' rowvar as rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>

Vous pouvez utiliser un nombre quelconque de valeurs séparées par des espaces. Les valeurs entre quotes simples (') ou doubles (") sont traitées comme des chaînes de caractères, les valeurs sans quotes sont supposées être des variables de contexte.

Vous pouvez aussi séparer les valeurs par des virgules:

{% cycle row1,row2,row3 %}

Dans cette syntaxe, chaque valeur sera interprêtée comme un littéral en chaîne de caractères. La syntaxe avec les virgules assure la compatibilité avec les anciennes versions et ne doit pas être utilisée dans de nouveaux projets.

debug

Produit un ensemble complet d'informations de déboguage, y compris le contexte courant et les modules importés.

extends

Indique que ce template « étend » un template parent (héritage).

Ce tag peut être utilisé de deux manières :

• {% extends "base.html" %} (entre quotes) utilise la valeur fournie "base.html" comme nom du template parent duquel dériver.
• {% extends variable %} utilise la valeur de variable. Si la variable renvoie une chaîne, Django utilisera cette chaîne comme nom du template parent. Si la variable renvoie un objet Template, Django utilisera cet objet comme template parent.

Voir Héritage des templates pour plus d'informations.

filter

Filtre le contenu des variables au travers des filtres de variables fournis.

Les filtres peuvent s'enchaîner et avoir des paramètres -- exactement comme dans la syntaxe des variables.

Exemple:

{% filter force_escape|lower %}
    This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}

firstof

Renvoie la première des variables qui ne vaut pas False. Ne renvoie rien du tout si toutes les variables qui lui sont passées valent False.

Exemple:

{% firstof var1 var2 var3 %}

Cette formulation est équivalente à:

{% if var1 %}
    {{ var1 }}
{% else %}{% if var2 %}
    {{ var2 }}
{% else %}{% if var3 %}
    {{ var3 }}
{% endif %}{% endif %}{% endif %}

Vous pouvez également utiliser une chaîne littérale comme valeur de refuge dans le cas où toutes les variables passées sont False:

{% firstof var1 var2 var3 "valeur refuge" %}

for

Parcourt tous les items d'une liste. Par exemple, pour afficher une liste d'athlètes contenus dans athlete_list:

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

Vous pouvez boucler sur les éléments d'une liste en ordre inverse en utilisant {% for obj in list reversed %}.

Nouveau dans la version de développement de Django Si vous devez boucler sur une liste de listes, vous pouvez récupérer les valeurs de chaque sous-liste dans un ensemble de variables nommées. Par exemple, si votre contexte contient une liste de coordonnées (x,y) appelées points, vous pourriez utiliser ceci pour afficher la liste des points:

{% for x, y in points %}
    There is a point at {{ x }},{{ y }}
{% endfor %}

Cela peut être également utile pour accéder aux éléments d'un dictionnaire. Par exemple, si votre contexte contient un dictionnaire data, ce qui suit affichera les clés et les valeurs du dictionnaire:

{% for key, value in data.items %}
    {{ key }}: {{ value }}
{% endfor %}

La boucle for positionne un certain nombre de variables accessibles depuis celle-ci :

Variable	Description
forloop.counter	Le numéro de l'itération courante (en partant de 1)
forloop.counter0	Le numéro de l'itération courante (en partant de 0)
forloop.revcounter	Le nombre d'itérations depuis la fin de la boucle (en partant de 1)
forloop.revcounter0	Le nombre d'itérations depuis la fin de la boucle (en partant de 0)
forloop.first	True si c'est le premier passage dans la boucle
forloop.last	True si c'est le dernier passage dans la boucle
forloop.parentloop	Pour les boucles imbriquées, désigne celle qui est "au-dessus" de la boucle courante

if

Le tag {% if %} évalue une variable, et si cette variable vaut "true" (c'est-à-dire si elle existe, n'est pas vide et n'est pas la valeur booléenne "false"), le contenu du bloc est affiché:

{% if athlete_list %}
    Number of athletes: {{ athlete_list|length }}
{% else %}
    No athletes.
{% endif %}

Si athlete_list ci-dessus n'est pas vide, le nombre d'athlètes sera affiché par la variable {{ athlete_list|length }}.

Comme vous pouvez le voir, le tag if peut prendre une clause facultative {% else %} qui sera affichée si le test échoue.

Le tag if peut utiliser and, or ou not pour tester plusieurs variables ou pour tester la négation d'une variable:

{% if athlete_list and coach_list %}
    A la fois athlètes et coaches sont disponibles.
{% endif %}

{% if not athlete_list %}
    Il n'y a pas d'athlètes.
{% endif %}

{% if athlete_list or coach_list %}
    Il y a des athlètes ou des coaches (pas forcément les deux).
{% endif %}

{% if not athlete_list or coach_list %}
    Il n'y a pas d'athlètes, ou il y a des coaches (d'accord, la traduction
    littérale de la logique booléenne semble ridicule, ce n'est pas de notre
    faute).
{% endif %}

{% if athlete_list and not coach_list %}
    Il y a des athlètes, et pas du tout de coaches.
{% endif %}

Le tag if ne permet pas d'utiliser à la fois les clauses and et or dans le même tag, parce que l'ordre d'évaluation logique serait ambigu. Cet exemple est invalide:

{% if athlete_list and coach_list or cheerleader_list %}

Si vous devez combiner and et or pour un test logique avancé, utilisez simplement des tags if imbriqués. Par exemple:

{% if athlete_list %}
    {% if coach_list or cheerleader_list %}
        Nous avons des athlètes, et des coaches ou des cheerleaders (pom-pom
        girls) !
    {% endif %}
{% endif %}

Des utilisations répétées du même opérateur logique sont possibles, tant que vous utilisez toujours le même opérateur. Cet exemple est valide:

{% if athlete_list or coach_list or parent_list or teacher_list %}

ifchanged

Teste si une valeur a changé depuis la dernière itération d'une boucle.

Le tag de bloc ifchanged est utilisé dans une boucle. Il a deux usages possibles.

1. Teste son propre contenu (ce qui est contenu dans le bloc) et n'affiche celui-ci que si il a changé depuis la dernière itération. Cet exemple affiche une liste de jours, et n'affiche 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 une variable est passée en paramètre, teste si cette variable a changé. Par exemple, le code qui suit affiche la date à chaque fois qu'elle change, mais ne montre l'heure que si à la fois la date et l'heure ont changé:

   {% for date in days %}
       {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
       {% ifchanged date.hour date.date %}
           {{ date.hour }}
       {% endifchanged %}
   {% endfor %}
   

ifequal

Affiche le contenu du bloc si les deux paramètres fournis sont égaux.

Exemple:

{% ifequal user.id comment.user_id %}
    ...
{% endifequal %}

Comme pour le tag {% if %}, une clause {% else %} est possible.

Les paramètres peuvent être directement des chaînes de caractères (par opposition à des variables), donc ce qui suit est valide:

{% ifequal user.username "adrian" %}
    ...
{% endifequal %}

Il est seulement possible de comparer un paramètre à des variables de template ou des chaînes de caractères. On ne peut pas tester l'égalité avec des objets Python tels que True ou False. Si vous devez tester si quelquechose est vrai ou faux, utilisez le tag if à la place.

ifnotequal

Exactement comme ifequal, sauf que l'on teste que les deux paramètres ne sont pas égaux.

include

Charge un template et l'envoie dans le contexte courant. C'est un moyen d'"inclure" d'autres templates dans un template donné.

Le nom du template peut être passé directement comme une chaîne de caractères entre quotes simples ou doubles, ou dans une variable.

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

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

Celui-ci inclut le contenu du template dont le nom est contenu dans la variable template_name:

{% include template_name %}

Un template inclus est rendu dans le contexte du template appelant. Cet exemple produira le texte "Hello, John" :

• Contexte: la variable person vaut "john".

• Template:

  {% include "name_snippet.html" %}
  

• Le template name_snippet.html:

  Hello, {{ person }}
  

Voir aussi : {% ssi %}.

load

Charge un ensemble personnalisé de tags de template.

Voir Tags personnalisés et bibliothèques de filtres pour plus d'informations.

now

Affiche la date au format indiqué.

Utilise le même format que la fonction date() de PHP (http://php.net/date) avec des extensions personnalisées.

Description du format:

Caractère de format	Description	Exemple d'affichage
a	'a.m.' ou 'p.m.' (Un peu différent de l'affichage de PHP, à cause des points pour respecter le style de l'Associated Press.)	'a.m.'
A	'AM' ou 'PM'.	'AM'
b	Le nom du mois sur 3 lettres, en minuscules.	'jan'
B	Non implémenté.
d	Le jour du mois, 2 chiffres avec le zéro initial si nécessaire.	'01' to '31'
D	Le jour de la semaine sur 3 lettres.	'Fri'
f	L'heure, sur 12 heures avec les minutes, les minutes ne sont pas affichées si zéro. Extension particuliére à Django.	'1', '1:30'
F	Le mois en toutes lettres.	'January'
g	L'heure sur 12 heures sans zéro initial.	'1' à '12'
G	L'heure sur 24 heures sans zéro initial.	'0' à '23'
h	L'heure sur 12 heures.	'01' à '12'
H	L'heure sur 24 heures.	'00' à '23'
i	Les minutes.	'00' à '59'
I	Non implémenté.
j	Le jour du mois sans zéro initial.	'1' à '31'
l	Le jour de la semaine en toutes lettres.	'Friday'
L	Booléen indiquant si l'année est bissextile.	True ou False
m	Le mois.	'01' à '12'
M	Le nom du mois sur 3 lettres.	'Jan'
n	Le mois en chiffres sans zéro initial.	'1' à '12'
N	Le mois abrégé dans le style de l'Associated Press. Extension particulière de Django.	'Jan.', 'Feb.', 'March', 'May'
O	Ecart avec l'heure de Greenwich en heures.	'+0200'
P	L'heure sur 12 heures avec les minutes et 'a.m.'/'p.m.', les minutes ne sont pas affichées si zéro. Affiche les cas particuliers 'midnight' et 'noon' si nécessaire. Extension particulière de Django.	'1 a.m.', '1:30 p.m.', 'midnight', 'noon', '12:30 p.m.'
r	La date au format RFC 2822.	'Thu, 21 Dec 2000 16:01:07 +0200'
s	Les secondes sur 2 chiffres avec le zéro initial si nécessaire.	'00' à '59'
S	Le suffixe anglais pour le jour du mois sur deux lettres.	'st', 'nd', 'rd' ou 'th'
t	Le nombre de jours du mois.	28 à 31
T	La zone horaire de la machine.	'EST', 'MDT'
U	Non implementé.
w	Le jour de la semaine sur 1 chiffre.	'0' (dimanche) à '6' (samedi)
W	Le numéro de la semaine au standard ISO-8601, les semaines commencent le lundi.	1, 53
y	L'année sur 2 chiffres.	'99'
Y	L'année sur 4 chiffres.	'1999'
z	Le rang du jour dans l'année.	0 à 365
Z	Le décalage de la zone horaire en secondes. Le décalage pour les zones horaires à l'ouest de UTC sont toujours négatifs, ceux à l'est sont toujours positifs.	-43200 à 43200

Exemple:

Nous sommes le {% now "jS F Y H:i" %}

Vous pouvez échapper un caractère de formatage à l'aide d'une barre de fraction inverse (backslash) si vous voulez l'afficher tel que au lieu de l'interpréter. Dans cet exemple, le "f" est échappé, sinon il serait interprété comme une chaîne qui affiche l'heure. Le "o" n'a pas besoin d'être échappé parce qu'il n'est pas utilisé comme caractère de formatage:

It is the {% now "jS o\f F" %}

Cette chaîne afficherait "It is the 4th of September".

regroup

Regroupe une liste d'objets ayant un attribut commun.

Ce tag complexe est plus facile à expliquer à l'aide d'un exemple : supposez que people est une liste de Personnes qui ont des attributs nom, prenom et sexe, et que vous voulez un affichage de ce genre :

• Homme :

  • George Bush
  • Bill Clinton

• Femme :

  • Margaret Thatcher
  • Condoleezza Rice

• Inconnu :

  • Pat Smith

Cet extrait de template accomplira ce travail bizarre:

{% regroup people by sexe as grouped %}
<ul>
{% for group in grouped %}
    <li>{{ group.grouper }}
    <ul>
        {% for item in group.list %}
        <li>{{ item }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Comme vous le voyez, {% regroup %} crée une variable avec une liste d'objets et les attributs grouper et list. grouper est l'item sur lequel les objets ont été regroupés, list contient la liste d'objets qui ont ce grouper en commun. Dans ce cas, grouper vaudra successivement Homme, Femme et Inconnu, et list est la liste des personnes dont c'est le sexe.

Notez que {% regroup %} ne fonctionnera pas si la liste à grouper n'est pas triée sur la clé de regroupement. Cela signifie que si votre liste de personnes n'est pas triée par sexe, vous devrez vous assurer de la trier avant de l'utiliser, par exemple:

{% regroup people|dictsort:"gender" by gender as grouped %}

spaceless

Enlève l'espace, les tabulations et les sauts de lignes entre les tags HTML.

Exemple d'utilisation:

{% spaceless %}
    <p>
        <a href="foo/">Foo</a>
    </p>
{% endspaceless %}

Cet exemple renverra cet HTML:

<p><a href="foo/">Foo</a></p>

Seul l'espacement entre les tags est supprimé -- pas l'espace entre les tags et le texte. Dans cet exemple, l'espace autour de Hello ne sera pas supprimé:

{% spaceless %}
    <strong>
        Hello
    </strong>
{% endspaceless %}

ssi

Affiche le contenu d'un fichier donné dans la page.

Comme un simple tag "include", {% ssi %} inclura le contenu d'un autre fichier -- qui doit être spécifié avec son chemin absolu -- dans la page courante:

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

Si le paramètre facultatif "parsed" est donné, le contenu du fichier inclus sera évalué comme un autre template, dans le contexte courant:

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

Notez que si vous utilisez {% ssi %}, vous devrez définir ALLOWED_INCLUDE_ROOTS dans vos règlages Django, pour plus de sécurité.

Voir également: {% include %}.

templatetag

Affiche un des caractères utilisés pour définir les tags de template.

Comme le système de template n'a pas de notion d'"échappement", pour afficher un des caractères utilisés pour marquer les tags de template, vous devez utiliser le tag {% templatetag %}.

Le paramètre donné indique quel caractère de template afficher :

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

url

Attention, la syntaxe de ce tag peut être modifiée dans le futur car nous travaillons à le rendre plus robuste.

Renvoie une URL absolue (c'est-à-dire une URL sans le nom de domaine) correspondant à une vue donnée et d'éventuels paramètres. Cela permet de créer des liens sans avoir à les coder "en dur" dans vos templates, ce qui constiturait une violation du principe DRY (don't repeat yourself, ne vous répétez pas):

{% url path.to.some_view arg1,arg2,name1=value1 %}

Le premier paramètre est le chemin d'une fonction vue au format package.module.function. Les autres paramètres sont facultatifs et doivent être des valeurs séparées par des virgules qui seront autant de paramétres de position ou de paramètres nommés dans l'URL. Tous les paramètres requis par l'URLconf doivent être présents.

Par exemple, supposez que vous avez une vue, app_views.client, dont l'URLconf prend en paramètre l'ID d'un client (ici, client() est une méthode dans le fichiers de vues app_views.py). La ligne URLconf pourrait ressembler à ceci:

('^client/(\d+)/$', 'app_views.client')

Si l'URLconf de cette application est incluse dans celle du projet dans un chemin tel que celui-ci:

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

...alors, dans un template, vous pouvez créer un lien vers cette vue de cette façon:

{% url app_views.client client.id %}

Le tag de template affichera la chaîne /clients/client/123/.

Nouveau dans la version de développement : Si vous utilisez des modèles d'URL nommés, vous pouvez vous servir du nom du modèle dans le tag url au lieu d'utiliser le chemin de la vue.

widthratio

Pour créer des graphiques en barres et assimilés, ce tag calcule le ratio d'une valeur donnée à une valeur maximum, puis applique ce ratio à une constante.

Par exemple:

<img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" />

Ci-dessus, si this_value vaut 175 et max_value vaut 200, l'image aura 88 pixels de large (parce que 175/200 = 0,875 et 0,875 * 100 = 87,5 arrondi à 88).

with

Nouveau dans la version de développement de Django

Cache une variable complexe derrière un nom plus simple. C'est utile pour accéder à une méthode "coûteuse" (qui par exemple fait une requête sur la base de données) de nombreuses fois.

Par exemple:

{% with business.employees.count as total %}
    {{ total }} employee{{ total|pluralize }}
{% endwith %}

La variable ainsi renseignée (total dans l'exemple) n'est accessible qu'entre les tags {% with %} et {% endwith %}.

add

Ajoute le paramètre fourni à la valeur.

Exemple

{{ value|add:"2" }}

Si value vaut 4, le résultat sera 6.

addslashes

Ajoute des barres de fraction (slashes) avant les guillemets (quotes). Utile pour échapper les valeurs dans le format CSV, (Comma Separated Values) par exemple.

Nouveau dans la version de développement de Django : Pour échapper des données dans des chaînes Javascript, utilisez le filtre escapejs à la place.

capfirst

Met en majuscule la première lettre de la valeur.

center

Centre la valeur dans un champ d'une largeur donnée.

cut

Supprime toutes les valeurs du paramètre de la chaîne donnée.

Exemple

{{ value|cut:" "}}

Si value vaut "Chaîne avec espaces", le résultat sera "Chaîneavecespaces".

date

Met une date au format donné (le même que pour le tag now).

Exemple

{{ value|date:"D d M Y" }}

Si value est un objet datetime (par exemple le résultat de datetime.datetime.now(), le résultat sera la chaîne 'Wed 09 Jan 2008' (ou sa version localisée).

default

Si une valeur vaut False, utilise la valeur fournie par défaut, sinon utilise la valeur fournie.

Exemple

{{ value|default:"rien" }}

Si value vaut "" (une chaîne vide), le résultat sera "rien".

default_if_none

Si (et seulement si) une valeur est None, utilise la valeur fournie par défaut, sinon utilise la valeur.

Notez que si la valeur est une chaîne vide, la valeur par défaut ne sera pas utilisée. Utilisez le filtre default si vous voulez une valeur par défaut pour les chaînes vides.

Exemple

{{ value|default_if_none:"rien" }}

Si value vaut None, le résultat sera "rien".

dictsort

Prend une liste de dictionnaires et renvoie cette liste triée sur la propriété passée en paramètre.

Exemple

{{ value|dictsort:"name" }}

Si value vaut

[
    {'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},
]

dictsortreversed

Prend une liste de dictionnaires et renvoie cette liste triée à l'envers sur la propriété passée en paramètre. Fonctionne exactement de la même façon que le filtre ci-dessus, mais la valeur sera renvoyée dans l'ordre inverse.

divisibleby

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

Exemple

{{ value|divisibleby:"3" }}

Si value vaut 21, le résultat sera True.

escape

Ajoute des caractères d'échappement à une chaîne HTML. Plus précisément, fait les remplacements suivants:

* ``<`` est converti en ``"&lt;"``
* ``>`` est converti en ``"&gt;"``
* ``'`` (simple quote) est converti en ``'&#39;'``
* ``"`` (double quote) est converti en ``'&quot;'``
* ``"&"`` est converti en ``"&amp;"``

L'échappement n'est appliqué qu'au moment ou la chaîne est rendue, donc l'endroit où vous placez escape dans une séquence de filtres est sans importance : il sera toujours appliqué comme si il était le dernier filtre. Si vous voulez que l'échappement intervienne immédiatemment, utilisez le filtre force_escape.

Appliquer le filtre escape à une variable qui serait normalement échappée automatiquement ne résultera qu'en une seule passe d'échappement. Il est donc possible d'appliquer ce filtre même dans les environnements d'échappement automatique. Si vous voulez plusieurs passes d'échappement, utilisez le filtre force_escape.

Nouveau dans la version de développement de Django : En raison de l'échappement automatique, le comportement de ce filtre a légèrement changé. Les remplacements ne sont appliqués qu'une fois, après tous les autres filtres -- y compris les filtres avant et après celui-ci.

escapejs

Nouveau dans la version de développement de Django

Échappe les caractéres pour l'utilisation dans des chaines Javascript. Cela ne rend pas la chaîne propre à l'utilisation dans du HTML, mais vous protège des erreurs de syntaxe lorsque vous utilisez les templates pour générer du Javascript ou du JSON.

filesizeformat

Affiche la valeur dans un format "lisible par l'homme" (par exemple, '13 KB', '4.1 MB', '102 bytes', etc).

Exemple

{{ value|filesizeformat }}

Si value vaut 123456789, le résultat sera 117.7 MB.

first

Renvoie le premier élément d'une liste.

Exemple

{{ value|first }}

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

fix_ampersands

Remplace le & par l'entité &amp;.

Exemple

{{ value|fix_ampersands }}

Si value vaut Tom & Jerry, le résultat sera Tom &amp; jerry.

Nouveau dans la version de développement de Django : Ce filtre n'est normalement plus utile, parce que les & sont automatiquement échappés dans les templates. Voir escape pour plus d'information sur l'échappement.

floatformat

Utilisé sans paramètre, arrondit un nombre décimal à un chiffre après la virgule -- mais seulement s'il y a une décimale à afficher. Par exemple :

Utilisé avec un paramètre entier numérique, floatformat arrondira à ce nombre de chiffres après la virgule. Par exemple :

Si le paramètre passé à floatformat est négatif, il arrondira à ce nombre de chiffres après la virgule -- mais seulement s'il y a des décimales à afficher. Par exemple :

Utiliser floatformat sans paramètre revient donc à l'utiliser avec le paramètre -1.

force_escape

Nouveau dans la version de développement de Django

Applique l'échappement du HTML à une chaîne de caractères (voir le filtre escape pour plus de détails). Ce filtre est appliqué immédiatemment et renvoie une nouvelle chaîne, échappée. C'est utile dans les cas rares où vous souhaitez des échappements multiples ou voulez appliquer d'autres filtres au résultat échappé. Normalement, vous devriez utiliser le filtre escape.

get_digit

Pour un nombre donné, renvoie le chiffre demandé, où 1 est le chiffre le plus à droite, 2 le suivant, etc. Renvoie le nombre original si le paramètre est invalide (ce n'est pas un entier, ou il est inférieur à 1). Sinon, renvoie toujours un entier.

Exemple

{{ value|get_digit:"2" }}

Si value vaut 123456789, le résultat sera 8.

iriencode

Convertit un IRI (Internationalized Resource Identifier) en une chaîne valide pour inclusion dans une URL. C'est nécessaire si vous essayez d'utiliser des chaînes contenant des caractères non ASCII dans des URL.

Il est possible d'utiliser ce filtre sur une chaîne qui est déjà passée par le filtre urlencode.

join

Joint les éléments d'une liste avec une chaîne, comme la fonction Python str.join(list)

Exemple

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

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

last

Nouveau dans la version de développement de Django

Renvoie le dernier item d'une liste.

Exemple

{{ value|last }}

Si value est la liste ['a', 'b', 'c', 'd'], le résultat sera la chaîne "d".

length

Renvoie la longueur de la valeur. Fonctionne avec les chaînes et les listes.

Exemple

{{ value|length }}

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

length_is

Renvoie True si le paramètre est égal à la longueur de la valeur filtrée, False sinon.

Exemple

{{ value|length_is:"4" }}

Si value est la liste ['a', 'b', 'c', 'd'], le résultat sera True.

linebreaks

Remplace les sauts de ligne dans le texte par le tag HTML approprié : un saut de ligne simple est remplacé par un saut de ligne HTML (<br />) et un saut de ligne suivi d'une ligne blanche est remplacé par un saut de paragraphe(</p>).

Exemple

{{ value|linebreaks }}

Si value vaut Joe\nest mon prénom, le résultat sera <p>Joe<br>est mon prénom</p>.

linebreaksbr

Convertit les sauts de lignes dans un passage en texte simple en tags <br />.

linenumbers

Affiche un texte avec des numéros de lignes.

ljust

Cadre la valeur à gauche dans un champ de longueur donnée.

Paramètre : taille du champ.

lower

Convertit une chaîne en minuscules.

Exemple

{{ value|lower }}

Si value vaut MERCI DE NE PAS CRIER, le résultat sera merci de ne pas crier.

make_list

Renvoie la valeur convertie en liste. Pour un entier, c'est une liste de chiffres. Pour une chaîne, c'est une liste de caractères.

Exemple

{{ value|make_list }}

Si value est la chaîne "Joe", le résultat sera la liste [u'J', u'o', u'e']. Si value vaut 123, le résultat sera la liste [1, 2, 3].

phone2numeric

Convertit un numéro de téléphone (qui peut contenir des lettres) en son équivalent numérique. Par exemple, '800-COLLECT' sera converti en '800-2655328'.

La valeur en entrée n'a pas besoin d'être un numéro de téléphone valide. Le filtre convertira gaiement n'importe quelle chaîne.

pluralize

Renvoie un suffixe pour marquer le pluriel si la valeur n'est pas 1. Le suffixe par défaut est 's'.

Exemple:

Vous avez {{ num_messages }} message{{ num_messages|pluralize }}.

Pour les mots dont la marque de pluriel n'est pas 's', vous pouvez passer en paramètre un autre suffixe au filtre.

Exemple:

Il y a {{ num_coaches }} coach{{ num_coach|pluralize:"es" }}.

Pour les mots dont le pluriel est plus élaboré qu'un simple suffixe, vous pouvez spécifier un suffixe pour le singulier et un autre pour le pluriel, séparés par une virgule.

Exemple:

Vous avez {{ num_chevaux }} cheva{{ num_cherries|pluralize:"l,ux" }}.

pprint

Ce filtre encapsule pprint.pprint -- à n'utiliser que pour le déboguage.

random

Renvoie un élément aléatoire de la liste fournie.

Exemple

{{ value|random }}

Si value est la liste ['a', 'b', 'c', 'd'], le résultat pourrait être "b".

removetags

Supprime de l'affichage une liste de tags [X]HTML séparés par des espaces.

Exemple

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

Si value vaut "<b>Joel</b> <button>is</button> a <span>slug</span>", le résultat sera "Joel <button>is</button> a slug".

rjust

Cadre la valeur à droite dans un champ de longueur donnée.

Paramètre : taille du champ.

safe

Marque une chaîne comme ne requérant pas d'échappement HTML ultérieur avant l'affichage. Lorsque l'échappement automatique n'est pas actif, ce filtre est sans effet.

slice

Renvoie un extrait (slice) de la liste.

Utilise la même syntaxe que celle de Python. Voir http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice pour une introduction.

Exemple: {{ some_list|slice:":2" }}

slugify

Convertit en minuscules, enlève les caractères autres que les lettres et enlève les tirets de soulignement, et convertit les espaces en tirets. Supprime également les espaces en début et fin de chaîne.

Exemple

{{ value|slugify }}

Si value vaut "Joel is a slug", le résultat sera "joel-is-a-slug".

stringformat

Formate la variable en fonction du paramètre, qui doit être une chaîne de format. La chaîne utilise la syntaxe de formattage de chaînes de Python, à ceci près que le "%" initial est supprimé.

Voir http://docs.python.org/lib/typesseq-strings.html pour une documentation des chaînes de format Python.

Exemple

{{ value|stringformat:"s" }}

Si value vaut "Joel is a slug", le résultat sera "Joel is a slug".

striptags

Supprime tous les tags [X]HTML.

Exemple

{{ value|striptags }}

Si value vaut "<b>Joel</b> <button>is</button> a <span>slug</span>", le résultat sera "Joel is a slug".

time

Formate l'heure dans le format fourni en paramètre (le même que pour le tag now). Le filtre time n'acceptera que les caractères de format relatifs à l'heure, pas à la date (pour des raisons évidentes). Si vous devez formater une date, utilisez le filtre date.

Exemple

{{ value|time:"H:i" }}

Si value` est équivalent à datetime.datetime.now(), le résultat sera la chaîne "01:23".

timesince

Formate une date comme le temps écoulé depuis cette date (par exemple, "4 jours et 6 heures").

Peut avoir un paramètre facultatif qui est une variable contenant la date à utiliser comme base de comparaison (sans ce paramètre, la base est maintenant). Par exemple, si blog_date est une instance de date représentant le 1er juin 2006 à zéro heures, et comment_date est une instance de date pour le 1er juin 2006 à 8 heures, {{ comment_date|timesince:blog_date }} renverra "8 heures".

L'unité la plus précise utilisée est la minute, et "0 minutes" sera renvoyé pour toute date qui est dans le futur de la base de comparaison.

timeuntil

Similaire à timesince, sinon qu'il mesure le temps de maintenant jusqu'à la date fournie. Par exemple, si nous sommes le 1er juin 2006 et conference_date est une instance de date représentant le 29 juin 2006, {{ conference_date|timeuntil }} renverra "4 semaines".

Peut avoir un paramètre facultatif qui est une variable contenant la date à utiliser comme base de comparaison (à la place de maintenant). Si from_date est le 22 juin 2006, {{ conference_date|timeuntil:from_date }} renverra "1 semaine".

L'unité la plus précise utilisée est la minute, et "0 minutes" sera renvoyé pour toute date qui est dans le passé de la base de comparaison.

title

Convertit une chaîne au format de titre.

truncatewords

Tronque une chaîne au-delà d'un certain nombre de mots.

Paramètre : Nombre de mots au-delà duquel tronquer.

Exemple

{{ value|truncatewords:2 }}

Si value est "Joel is a slug", le résultat sera "Joel is ...".

truncatewords_html

Similaire à truncatewords, mais respecte les tags HTML. Tout tag qui est ouvert dans la chaîne et non fermé avant le point au delà duquel la chaîne est tronquée sera fermé immédiatement après celui-ci.

Moins efficace que truncatewords, donc à n'utiliser que sur du texte au format HTML.

unordered_list

Lit de façon récursive une liste imbriquée, et renvoie une liste HTML non numérotée -- SANS les tags <ul> d'ouverture et de fermeture.

Noueau dans la version de développement de Django : Le format accepté par unordered_list a été modifié pour être plus facile à comprendre.

La liste est supposée être au bon format. Par exemple, si var contient ['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']], {{ var|unordered_list }} renverra

<li>States
<ul>
        <li>Kansas
        <ul>
                <li>Lawrence</li>
                <li>Topeka</li>
        </ul>
        </li>
        <li>Illinois</li>
</ul>
</li>

Note : le format précédent, plus restrictif et plus verbeux est toujours supporté : ['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois',[]]]]

upper

Convertit une chaîne en majuscules.

Exemple

{{ value|upper }}

Si value est "Joel is a slug", le résultat sera "JOEL IS A SLUG".

urlencode

Ajoute des caractères d'échappement à une chaîne de façon à pouvoir l'utiliser dans une URL.

urlize

Convertit les URL dans un texte en liens cliquables.

Notez que si urlize est appliqué à un texte qui contient déjà des balises HTML, le résultat ne sera pas celui attendu. N'appliquez ce filtre qu'à du texte brut.

Exemple

{{ value|urlize }}

Si value est "Check out www.djangoproject.com", le résultat sera "Check out <a href="http://www.djangoproject.com">www.djangoproject.com</a>".

urlizetrunc

Convertit les URL en liens cliquables, en les tronquant au delà d'une certaine longueur.

Comme pour urlize, ce filtre ne doit être appliqué qu'à du texte brut (sans balises HTML).

Paramètre : la longueur au-delà de laquelle tronquer les URL.

Exemple

{{ value|urlizetrunc:15 }}

Si value est "Check out www.djangoproject.com", le résultat sera "Check out <a href="http://www.djangoproject.com">www.djangopr...</a>".

wordcount

Renvoie le nombre de mots.

wordwrap

Formate les lignes à une certaine longueur.

Paramètre : nombre de caractères par ligne.

Exemple

{{ value|wordwrap:5 }}

Si value est Joel is a slug, le résultat sera

Joel
is a
slug

yesno

Utilise une chaîne fournissant des textes de remplacement pour True, False et None (ce dernier est facultatif) pour renvoyer un de ces textes en fonction de la valeur :