Modifiée par : Anaïs Ecuvillon

Utiliser les filtres Django pour manipuler les données

Introduction aux filtres Django

Les filtres permettent de transformer ou de manipuler les données dans Publik. Ils sont utilisés directement dans les gabarits Django via le symbole |, appelé pipe (prononcé païpe).

Syntaxe générale :
form_var_chose|nom_du_filtre

Exemple simple

Si vous souhaitez convertir une valeur en minuscules :
{{ form_var_titre|lower }}

Combinaison de filtres

Les filtres peuvent être chaînés :
{{ form_var_title|first|lower }}
Cela extrait le premier caractère de form_var_title et le convertit en minuscule.

Filtres avec paramètres

Certains filtres acceptent des paramètres :
form_var_chose|nom_du_filtre:parametre

Le paramètre peut être un nombre (sans guillemets) :
form_var_chose|add:2

Le paramètre peut être une chaîne de caractères (encadrée par des guillemets) :
form_var_chose|startswith:"toto"

En savoir plus

Cette page ne détaille que les filtres classiquement utilisés avec Publik. La façon la plus complète de comprendre l'utilisation des filtres et de regarder la documentation Django en la matière.

Il existe une page spécifique de la documentation Publik pour les filtres de requête.

Types de données

Dans les gabarits ou les conditions Django, il est souvent nécessaire de convertir une donnée d’un type à un autre, par exemple vers une date ou un nombre. Ces conversions permettent de réaliser des calculs, des comparaisons, ou de gérer plus facilement le format d’affichage. Pour cela, on utilise des filtres. Voici les principaux types de données gérés par Publik :

  • chaîne de caractères: type par défaut pour toutes les données de Publik ;
  • date: utilisé pour les champs de type « date » ;
  • decimal: nombre à virgule, utile pour les comparaisons et les calculs de tarifs ;
  • datetime: combinaison de la date et de l’heure, utilisée notamment pour la gestion des rendez-vous ;
  • time: heure seule.

Conversion de types

La syntaxe pour convertir une variable est la suivante :
form_var_chose|<type>

<type> pouvant être : date, decimal, datetime ou time.

Lorsque la conversion échoue, Django retourne une chaîne de caractères vide. Publik respecte ce principe.

Exemples pratiques

  • form_var_date|date --> transforme la valeur en date

  • form_var_date|datetime --> transforme la valeur en date + heure

  • form_var_tarif|decimal --> transforme la valeur en nombre

Précision sur les nombres, le filtre |decimal:2 donne un nombre à 2 chiffres après la virgule mais ne transforme pas form_var_tarif en nombre.

Manipuler et formater les dates

Modifier le format d'affichage

Le filtre |date permet de personnaliser l’affichage des dates :
{{ today|date:"Y-m-d" }} --> affiche la date au format ISO, par exemple 2025-01-07
{{ today|date:"d/m/Y" }} --> affiche la date au format plus habituel 07/01/2025

Calculs d'âge

Les filtres suivants calculent l'âge d'une date par rapport à aujourd'hui :

  • En jours : form_var_date|age_in_days --> le résultat est un nombre, qui est négatif quand l'évènement est dans le futur

  • En jours ouvrés : form_var_date|age_in_working_days

  • En jours ouvrés, samedi inclus : form_var_date|age_in_working_days_with_saturday

  • En mois : form_var_date|age_in_months

  • En années : form_var_date|age_in_years

  • En heures : form_var_date|age_in_hours --> fonctionne également avec une variable au format datetime. Cela permet par exemple de déclencher l'envoi d'un courriel exactement 48 heures avant un rendez-vous.

Les filtres age_in_* ci-dessus permettent de calculer l'âge en fonction de la date du jour. Il est également possible de calculer le nombre d’heures, de jours, de mois ou d’années entre deux dates. Pour réaliser ces calculs, utilisez la syntaxe suivante :
form_var_date1|age_in_years:form_var_date2 --> ici calcule le nombre d'années, years pouvant être remplacé selon l'unité voulue

Exemples pratiques

Dans une condition Django:
form_var_datenaissance|age_in_years >= 18 --> vraie si la personne est majeure

Dans ungabarit:
Vous avez aujourd'hui {{ form_var_datenaissance|age_in_years }} ans. {% if form_var_datenaissance|age_in_years >= 18 %}Vous êtes majeur·e.{% endif %}

Ajout de jours ou d'heures à une date

Vous pouvez ajouter ou retirer des jours, des heures, ou des minutes à une date donnée grâce à des filtres spécifiques :

  • form_var_date|add_days:3 --> ajoute 3 jours à form_var_date

  • form_var_date|add_hours:-6 --> retranche 6 heures à form_var_date

  • form_var_date|add_minutes:15 --> ajoute 15 minutes à form_var_date

Un nombre négatif permet de retirer des jours, des heures ou des minutes.

Ajout de jours ouvrés

Pour ajouter des jours ouvrés, utilisez les filtres suivants :

  • form_var_date|add_working_days:5 --> ajoute 5 jours ouvrés à form_var_date

  • form_var_date|add_working_days_with_saturday:5 --> ajoute 5 jours ouvrés en incluant le samedi à form_var_date

Ajustement des jours ouvrés

D'autres filtres permettent de travailler avec les jours ouvrés :

  • form_var_date|is_working_day --> indique si la date est un jour ouvré

  • form_var_date|is_working_day_with_saturday --> indique si la date est un jour ouvré, samedi inclus

  • form_var_date|adjust_to_working_day --> affiche le prochain jour ouvré

  • form_var_date|adjust_to_working_day_with_saturday --> affiche le prochain jour ouvré en incluant le samedi

Comparer deux dates

Utilisez les opérateurs standards pour comparer deux dates :

  • form_var_date1 != form_var_date2 --> Les deux dates sont différentes

  • form_var_date1 > form_var_date2 --> date1 est strictement après date2

  • form_var_date1 <= form_var_date2 --> date1 est avant ou égal à date2

Attention: Si cela ne fonctionne pas, vérifiez que vos variables sont bien des dates et utilisez si nécessaire le filtre |date pour les convertir.

Filtres

pour les opérations mathématiques

Les filtres suivants permettent d'effectuer des calculs simples. Ils retournent un nombre (ou zéro si le calcul ne peut pas être effectué) :

Calculs de base :

xxx|add:2 --> ajoute 2 à xxx
xxx|subtract:2 --> soustrait 2 de xxx
xxx|multiply:2 --> multiplie xxx par 2
xxx|divide:2 --> divise xxx par 2
xxx|modulo:yyy --> renvoie le reste de la division de xxx par yyy

Comparaison :

xxx|decimal > 2 --> vérifie si xxx est supérieur à 2

Utilisation avec des variables :

Les filtres acceptent également des variables comme arguments :

"2"|add:xxx --> ajoute la valeur de xxx à 2
xxx|subtract:yyy --> soustrait la valeur de yyy à la valeur de xxx

Division par zéro :

xxx|divide:0 --> en cas de division par zéro, le filtre retourne une chaîne vide

Ordre d'exécution des filtres :

Les filtres sont appliqués de gauche à droite, sans parenthèses pour structurer les priorités. Par exemple :

form_var_prix1|add:form_var_prix2|multiply:1.2|decimal:2 --> additionne deux prix, puis calcule la TVA, et enfin formate le résultat avec deux décimales.

Pour gérer des calculs complexes (l'usage de parenthèse n'étant pas autorisé), il faut passer par des résultats intermédiaires :

{% with var1=prix1|multiply:1.2 var2=prix2|multiply:1.055 %}
{{ var1|add:var2|decimal:2 }}
{% endwith %}
--> additionne deux prix, calculés avec des TVA différentes.

Arrondir un nombre :

xxx|ceil --> arrondit au nombre entier supérieur
xxx|floor --> arrondit au nombre entier inférieur

Valeur absolue :

xxx|abs --> renvoie toujours une valeur positive

Comparer des nombres

Utilisez les opérateurs standards pour comparer deux nombres :

  • form_var_nombre1!= form_var_nombre2 --> Les deux nombres sont différents

  • form_var_nombre1 > form_var_nombre2 --> nombre1 est strictement supérieur à nombre2

  • form_var_nombre1<= form_var_nombre2 --> nombre1 est inférieur ou égal à nombre2

Attention: Si cela ne fonctionne pas, vérifiez que vos variables sont bien des nombres et utilisez si nécessaire le filtre |decimal.

Transformer un nombre en jours, heures et minutes

Le filtre |duration permet de convertir une durée exprimée en minutes en un format lisible, soit en heures et minutes, soit en jours, heures et minutes. Voici comment l'utiliser :

{{ form_var_mon_nombre|duration }} --> si form_var_mon_nombre contient 125, cela renverra :2h05.
{{ form_var_mon_nombre|duration:"long" }} --> Si form_var_mon_nombre contient 125, cela renverra : 2 heures et 5 minutes.

Filtres sur les chaînes de caractère
Filtre Description
|startswith:"toto" renvoie True (vrai) si la chaîne de caractère commence par "toto", False sinon
|endswith:"toto" renvoie True (vrai) si la chaîne de caractère se termine par "toto", False sinon
|lower permet d'obtenir une variable en minuscules
|upper permet d'obtenir une variable en majuscules
|capfirst permet d'obtenir une chaîne avec une majuscule sur la première lettre
|title permet d'obtenir une variable comprenant une majuscule aux premières lettres de chaque mot
|slugify permet d'obtenir une chaîne en minuscules non accentuées, espaces convertis en tirets
|unaccent permet d'obtenir une chaîne de caractères non accentués
|default:"" permet d'obtenir un texte (chaîne vide, en l'occurence) si la variable n'est pas spécifiée (serait "None" sinon)
|removeprefix permet de supprimer un préfixe. {{ "Ma valeur"|removeprefix:"Ma "}} va donner valeur
|removesuffix permet de supprimer un suffixe. {{ "Ma valeur"|removesuffix:" valeur"}} va donner Ma
|strip permet de retirer les espaces en début et fin de chaîne
|linebreaks permet de forcer les retours à la ligne dans un texte contenant plusieurs paragraphes, il produit de l’HTML qui doit donc être marqué par |safe pour être interprété comme tel
|is_empty vérifie si la variable existe, ou si la valeur existe et est non vide
|as_numeral convertit un nombre en toutes lettres ("42", devient "quarante-deux")
|as_numeral_currency convertit un nombre en toutes lettres avec les centimes ("42,50", devient "quarante-deux et cinquante centimes")
|sha256 pour obtenir un hachage selon la fonction SHA256.
|integer pour obtenir un entier (principalement utile lors d'appels webservices)
|phonenumber_fr convertit un numéro de téléphone français en 5 groupes de 2 chiffres séparés entre eux par un espace ("0123456789", devient "01 23 45 67 89"). Le filtre prend en option le séparateur des paires de chiffres : |phonenumber_fr:"" donnera "0123456789"
|is_french_mobile_phone_number vérifie si la variable pointe un numéro de téléphone mobile (06 ou 07)

Lors de l'utilisation de firstof, il est important de noter que les filtres s'appliquent directement aux valeurs, y compris si celles-ci sont None. Cela peut transformer

Attention, dans le cas où l'on utilise firstof, le filtre s'applique sur une valeur None, transformant une valeur vide en une chaîne non vide. valeur non vide. Par exemple :

{% firstof form_var_nom1|upper form_var_nom2|upper %}

Dans cet exemple, va renvoyer "NONE" si form_var_nom1 est vide (None), le filtre upper renverra la chaîne "NONE" vide, au lieu de

  1. passer à form_var_nom2.

    Pour éviter ce comportement et garantir un résultat attendu, il est recommandé d'utiliser une des approches suivantes :

    Appliquer un filtre default avant upper:
    Cela permet de remplacer les valeurs     None par une chaîne vide avant de les convertir en majuscules. renvoyer form_var_nom2.

    Dans ce cas, la bonne pratique consiste à faire :


    {% firstof form_var_nom1|default:""|upper form_var_nom2|default:""|upper %}

  2. Combiner firstof avec une variable temporaire :
    Ici, la transformation en majuscules est effectuée après la sélection de la première valeur non vide.

    ou encore :


    {% firstof form_var_nom1 form_var_nom2 as nom %}{{ nom|upper }}

Filtres permettant des opérations mathématiques
Les filtres permettant des opérations mathématiques retournent un nombre (zéro s'ils n'arrivent pas à faire le calcul) :
xxx|decimal > 2 --> effectue la comparaison
xxx|add:2       --> ajoute 2 à xxx xxx|subtract:2  --> retranche 2 à xxx xxx|multiply:2  --> multiplie xxx par 2 xxx|divide:2    --> divise xxx par 2
xxx|modulo:yyy  --> extrait le reste de la division de xxx par yyy
L'argument peut aussi être une variable :
"2"|add:xxx     --> ajoute xxx à 2 xxx|add:yyy     --> ajoute yyy à xxx
En cas de division par zéro, on obtient une chaîne vide.
xxx|divide:0    --> (vide)
Attention, les opérations chaînées s'exécutent de gauche à droite :
form_var_prix1|add:form_var_prix2|multiply:1.2|decimal:2 --> additionne deux prix et applique dessus le calcul de la TVA
Il n'y a pas de parenthèses. Pour les simuler, il faut passer par des résultats intermédiaires :
{% with var1=prix1|multiply:1.2 var2=prix2|multiply:1.055 %} {{ var1|add:var2|decimal:2 }} {% endwith %} --> ajoute deux prix TTC issus de deux TVA différentes
D'autres opérateurs permettent d'arrondir les nombres,
xxx|ceil        --> nombre entier directement supérieur ou égal à xxx xxx|floor       --> nombre entier directement inférieur ou égal à xxx
ou encore d'en extaire la valeur absolue.
xxx|abs           --> valeur absolue (toujours positive) de xxx

Comparer des nombres

Utilisez les opérateurs standards pour comparer deux nombres :

form_var_nombre1 != form_var_nombre2 # Les deux nombres sont différents
form_var_nombre1 > form_var_nombre2 # nombre1 est strictement supérieur à nombre2 form_var_nombre1 <= form_var_nombre2 # nombre1 est inférieur ou égal à nombre2

Attention: Si cela ne fonctionne pas, vérifiez que vos variables sont bien des nombres et utilisez si nécessaire le filtre |decimal.

Transformer un nombre en jours/heures

Il est possible d'afficher une durée exprimée en minutes sous forme de texte, en jours, heures et minutes, avec le filtre |duration :

{{ form_var_mon_nombre|duration }} => renvoie quelque chose comme 2h05
{{ form_var_mon_nombre|duration:"long" }} => renvoie quelque chose comme 2 heures et 5 minutes
Filtres sur les blocs de champs

Obtenir Renvoyer la liste des valeurs d’un d'un champ

Le filtre |getlist

extrait toutes les valeurs d’un champ spécifique au sein d’un bloc de champs.Exemple : Pour afficher

permet d'afficher les valeurs d'un champ précis d'un bloc de champ. L'exemple suivant renvoie les valeurs du champ nom intégré dans un bloc de champs nommé monbloc:
form_var_monbloc|getlist:"nom"

Faire la somme des valeurs

d’un champLe d'un champ dans un bloc de champs ou une listele filtre |sum permet d’additionner les valeurs d’un champ dans d'additionner les valeurs d'un champ intégré à un bloc de

champs ou dans une liste de nombres.Exemple avec un bloc de champs :
Pour calculer

champs. L'exemple suivant renvoie la somme des valeurs du champ montant intégré dans un bloc de champs nommé monbloc:
form_var_monbloc|getlist:"montant"|sum

Exemple avec une liste obtenue via un filtre de requête :
Pour additionner les valeurs du champ montant d’un le filtre |sum fonctionne aussi pour faire la somme des éléments d'une liste de nombres. Par exemple pour un filtre de requête récupérant la liste des montants dans le champ "montant" d'un modèle de fiche nommé subventions:
cards|objects:"subventions"|getlist:"montant"|sum

Autres filtres spécifiques

|split transforme la valeur d'une variable en liste en utilisant un séparateur.Par défaut, construit une liste depuis la variable, en considérant que le séparateur est l’espace.
Exemple : "un deux trois"|split → l'espace. Par exemple « un deux trois » va donner la liste ["un", "deux", "trois"].


Vous pouvez définir un autre séparateur, comme la virgule, par exemple : xxx|split:","|has_role vérifie

On peut spécifier un autre séparateur que l'espace, par exemple la virgule : xxx|split:",";|has_role:"..." permet de voir si un utilisateur

possède un rôle spécifique.
Exemple : session_user|has_role:"Agent"

|rename_file renomme un fichier.
Le paramètre .$ext récupère l’extension du fichier d’origine.

Exemple simple :
{{ form_var_fichierarenommer|rename_file:"RIB.$ext }}

Exemple avancé (nom dynamique basé sur plusieurs champs) :

dispose d'un rôle particulier, par ex : session_user|has_role:"Agent".|rename_file pour modifier le nom d’un fichier.  (le paramètre ".$ext" permet de récupérer l'extension du fichier source. On peut reformater le nom d'un fichier pour qu'il respecte des règles de nommage. Des exemples ci-dessous : {{form_var_fichierarenommer|rename_file:"RIB.$ext" }}
{% with nom_fichier="dutexte"|add:form_var_votrechamp|add:"-"|add:form_var_autrechamp|add:".$ext" %}
{{form_var_fichierarenommer|rename_file:nom_fichier }}
{% %}{{form_var_fichierarenommer|rename_file:nom_fichier }}{% endwith %}

|convert_image_format convertit une image dans un autre format (JPEG, PDF ou PNG)
Exemple : pour convertir un fichier d’image d’un format à un autre; les formats pris en charge sont JPEG, PDF et PNG.
{{ form_var_image|convert_image_format:"jpeg" }}
{{ form_url|qrcode|convert_image_format:"pdf" }}

|as_template

interprète une variable comme un gabarit.|check_no_duplicates vérifie l’absence de doublons dans une liste.
Exemple 

pour demander l’interprétation d’une variable sous forme de gabarit.|check_no_duplicates pour vérifier qu'il n'y a pas de doublon dans une liste, exemple  :
{% if forms|objects:"slug_formulaire"|filter_by:"un_champ"|filter_value:unevaleur|getlist:"un_champ"|check_no_duplicates %} code>
pas de doublon (on vérifie si des doublons existe)
{% else %}
{{forms|objects:"slug_formulaire"|filter_by:"un_champ"|filter_value:unevaleur|getlist:"un_champ"|join:","}} (pour renvoyer la liste des doublons)
{% endif %}

|housenumber_number extrait permet d’isoler la partie numérique d’un numéro de

rue.
Exemple : "42bis"|housenumber_number → 42|housenumber_btq extrait

rue, permet par exemple d’obtenir "42" à partir du texte "42bis".|housenumber_btq permet à l’inverse d’isoler la partie non-numérique d’un numéro de

rue.
Exemple : "42bis"|housenumber_btq → "bis".|strip_emoji supprime

rue, par exemple donc d’obtenir "bis" à partir du texte "42bis".|strip_emoji permet de retirer les émojis d’un texte.

|repeat:n répète une permet de répéter la valeur un certain nombre de fois.
Exemple : "hello"|repeat:3 → "hellohellohello".

fois, exemple "hello"|repeat:3 donnera "hellohellohello".