Utiliser les filtres Django pour manipuler les données
Filtres standards
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.
form_var_chose|nom_du_filtre
{{ form_var_titre|lower }}
{{ form_var_title|first|lower }}
Cela va prendre le premier caractère et le passer en minuscule.
Certains filtres acceptent des paramètres, qu'on précise ainsi :
form_var_chose|nom_du_filtre:parametre
Types de données
Dans les gabarits ou les conditions Django, on peut avoir besoin de convertir un type de donnée vers un autre, le plus souvent vers une date ou un nombre. Cela permet d'y faire des calculs, des comparaisons, ou d'en gérer plus facilement le format d'affichage. On va utiliser les filtres pour cela. Publik gère quelques type de données :
- chaîne de caractère, c'est le type par défaut pour toutes les données de Publik
- date : date, c'est le type pour les champs « date »
- decimal : nombre (à virgule), à utiliser pour les comparaisons de nombre et les calculs de tarifs
- datetime : date et heure, à utiliser pour la gestion des rendez-vous
- time : heure seule
form_var_chose|<type>
form_var_date|date --> transforme la valeur en date form_var_date|datetime --> même chose, mais en transformant en date + heure form_var_tarif|decimal --> transforme en nombre.
Attention,
form_var_tarif|decimal:2
donne un nombre à 2 chiffres après la virgule mais ne transforme pas form_var_tarif en nombre.
Filtres sur les dates
Format d'affichage
On peut faire varier la façon dont une date va s'afficher grâce à des paramètres du filtre |date. Par exemple avec la variable today (qui contient la date du jour), on aura :
{{ today|date:"Y-m-d" }} --> affiche la date au format ISO, par exemple 2019-02-25 {{ today|date:"d/m/Y" }} --> affiche la date au format plus habituel 25/02/2019
On pourra souhaiter ne récupérer que :
-
L'année : today|date:"Y"
-
Le mois : today|date:"m"
-
Le jour : today|date:"d"
Calcul d'âge
Il est souvent intéressant, pour une date d'évaluer sa distance (son âge) par rapport à la date du jour. On va pour cela utiliser les filtres suivants :
- form_var_date|age_in_days : donne l'âge d'un évènement qui se produit à la date form_var_date, en jours. Le résultat est un nombre, qui est négatif quand l'évènement est dans le futur.
- form_var_date|age_in_working_days et form_var_date|age_in_working_days_with_saturday sont également possibles pour tenir compte des jours ouvrés (en incluant le samedi en tant que jour ouvré, si souhaité)
- form_var_date|age_in_years : même chose avec le nombre d'années
- form_var_date|age_in_months : même chose avec le nombre de mois
- form_var_date|age_in_hours : même chose avec le nombre d'heure, et fonctionne aussi quand xxx est une datetime. Permet par exemple de faire un mail exactement 48 heures avant un rendez-vous
form_var_datenaissance|age_in_years >= 18 --> vraie si la personne est majeure
Vous avez aujourd'hui {{ form_var_datenaissance|age_in_years }} ans. {% if form_var_datenaissance|age_in_years >= 18 %}Vous êtes majeur·e.{% endif %}
Les filtres age_in_* calculent l'âge en fonction de la date du jour. Mais il est souvent intéressant de pouvoir faire un calcul du nombre de heures/jours/mois/années entre deux dates. Pour faire ce calcul on va utiliser le format :
form_var_date2|age_in_<unité>:form_var_date1
form_var_date|age_in_years == 1
; cela signifie également qu’une comparaison form_var_date|age_in_years > 1
sera vraie uniquement après son deuxième anniversaire.Ajout de jours / heures / minutes
Il est possible d'ajouter des jours ou des heures à une date donnée grâce à deux filtres dédiés :
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 d'enlever des jours ou des heures.
Il est possible d'ajouter des jours ouvrés avec |add_working_days :
form_var_date|add_working_days:5 --> ajoute 5 jours ouvrés
form_var_date|add_working_days_with_saturday:5 --> ajoute 5 jours ouvrésen comptant le samedi
D'autres filtres permettent d'ajuster les jours ouvrés :
form_var_date|is_working_day --> permet de dire si le jour est un jour ouvré
form_var_date|is_working_day_with_saturday --> permet de dire si le jour est un jour ouvré en incluant le samedi comme jour ouvréform_var_date|a
djust_to_working_day --> prend le prochain jour ouvréform_var_date|a
djust_to_working_day_with_saturday --> prend le prochain jour ouvré en incluant le samedi
Comparer deux dates
form_var_date1 == form_var_date2
La condition sera vraie si les deux dates sont identiques. Les autres opérateurs de comparaisons sont également utilisables avec les dates :
form_var_date1 != form_var_date2 --> les dates sont différentes form_var_date1 > form_var_date2 --> date1 est strictement après date2 form_var_date1 < form_var_date2 --> date1 est strictement avant date2 form_var_date1 >= form_var_date2 --> date1 est après date2, ou égal à date2 form_var_date1 <= form_var_date2 --> date1 est avant date2, ou égal à date2
form_var_date1|date > form_var_date2|date
Filtres sur les chaînes de caractère
- |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")
- |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).
Attention, dans le cas où l'on utilise firstof
, le filtre s'applique sur une valeur None, transformant une valeur vide en valeur non vide. Par exemple :
{% firstof form_var_nom1|upper form_var_nom2|upper %}
va renvoyer "NONE" si form_var_nom1
est vide, au lieu de renvoyer form_var_nom2.
Dans ce cas, la bonne pratique consiste à faire :
{% firstof form_var_nom1|default:""|upper form_var_nom2|default:""|upper %}
ou encore :
{% firstof form_var_nom1 form_var_nom2 as nom %}{{ nom|upper }}
Comparer deux nombres
form_var_nombre1 == form_var_nombre2.
La condition sera vraie si les deux nombres sont identiques. Les autres opérateurs de comparaison sont également utilisables :
form_var_nombre1 != form_var_nombre2 --> les nombres sont différents form_var_nombre1 > form_var_nombre2 --> nombre1 est strictement supérieur à nombre2 form_var_nombre1 < form_var_nombre2 --> nombre1 est strictement inférieur à nombre2 form_var_nombre1 >= form_var_nombre2 --> nombre1 est supérieur ou égal à nombre2 form_var_nombre1 <= form_var_nombre2 --> nombre1 est inférieur ou égal à nombre2
Attention si ça ne fonctionne pas c’est peut-être que vous utilisez une variable qui n’est pas une nombre, utilisez le filtre |decimal pour la convertir. Il est conseillé d'être «explicite», y compris pour les champs de type Nombre et d'utiliser une syntaxe telle que :
form_var_nombre1|decimal > form_var_nombre2|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
Renvoyer la liste des valeurs d'un champ
Le filtre |getlist 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 champ dans un bloc de champs ou une liste
le filtre |sum permet d'additionner les valeurs d'un champ intégré à un bloc de 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
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 construit une liste depuis la variable, en considérant que le séparateur est l'espace. Par exemple « un deux trois » va donner la liste
["un", "deux", "trois"]
. 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 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 }}{% endwith %}
- |convert_image_format 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 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 %} 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 permet d’isoler la partie numérique d’un numéro de 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, par exemple donc d’obtenir "bis" à partir du texte "42bis".
- |strip_emoji permet de retirer les émojis d’un texte.
- |repeat:n permet de répéter la valeur un certain nombre de fois, exemple
"hello"|repeat:3
donnera "hellohellohello".