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 un gabarit :
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.
{% 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 une valeur vide en une chaîne non vide.
{% firstof form_var_nom1|upper form_var_nom2|upper %}
Dans cet exemple, si form_var_nom1
est vide (None
), le filtre upper
renverra la chaîne "NONE"
au lieu de 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
avantupper
:
Cela permet de remplacer les valeursNone
par une chaîne vide avant de les convertir en majuscules.
{% firstof form_var_nom1|default:""|upper form_var_nom2|default:""|upper %}
-
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.
{% firstof form_var_nom1 form_var_nom2 as nom %}{{ nom|upper }}
Filtres sur les blocs de champs
Obtenir la liste des valeurs 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 les valeurs du champ nom dans un bloc de champs nommé monbloc :
form_var_monbloc|getlist:"nom"
Faire la somme des valeurs d’un champ
Le filtre |sum
permet d’additionner les valeurs d’un champ dans un bloc de champs ou dans une liste de nombres.
Exemple avec un bloc de champs :
Pour calculer la somme des valeurs du champ montant 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 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, le séparateur est l’espace.
Exemple : "un deux trois"|split
→ ["un", "deux", "trois"]
.
Vous pouvez définir un autre séparateur, comme la virgule, par exemple : xxx|split:","
|has_role vérifie 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) :
{% with nom_fichier="dutexte"|add:form_var_votrechamp|add:"-"|add:form_var_autrechamp|add:".$ext" %}
{{form_var_fichierarenommer|rename_file:nom_fichier }}
{% endwith %}
|convert_image_format convertit une image dans un autre format (JPEG, PDF ou PNG)
Exemple :
{{ 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 :
{% 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 la partie numérique d’un numéro de rue.
Exemple : "42bis"|housenumber_number
→ 42
|housenumber_btq extrait la partie non-numérique d’un numéro de rue.
Exemple : "42bis"|housenumber_btq
→ "bis"
.
|strip_emoji supprime les émojis d’un texte.
|repeat:n répète une valeur un certain nombre de fois.
Exemple : "hello"|repeat:3
→ "hellohellohello"
.