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.

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
|safe	permet, dans un endroit qui autorise de l'HTML, de dire qu'une valeur doit être traitée comme de l'HTML.
|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)
|boolean	pour obtenir un booléen (principalement utile lors d'appels webservices)
|float	pour obtenir un nombre à virgule flottante (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)

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

|float convertit un nombre (entier ou décimal, éventuellement sous forme de chaîne de caractères) en nombre à virgule flottante, parfois nécessaire pour des appels webservices.

|boolean convertit une valeur en booléen (les valeurs considérées comme « faux » sont None, 0, False, la chaîne vide, et les chaînes "false" et "False").