Documentation en ligne

Utiliser les filtres

Quand on dispose d'une donnée dans Publik, comme form_var_chose, on peut la transformer, au travers de «filtres».
 
La notation générale est :
form_var_chose|nom_du_filtre
Le symbole |, barre verticale, est souvent nommé «pipe», prononcé à l'anglaise, «païpe».

 

Par exemple, si on veut passer une valeur en minuscule, on va utiliser le filtre « lower ». Dans un gabarit, on aura donc :

 

{{ form_var_titre|lower }}
On peut combiner les filtres les uns à la suite des autres :
{{ 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
Note : parametre peut être un nombre (alors sans guillemets, exemple : form_var_chose|add:2) ou une chaîne de caractères, alors encadrée par des guillemets (exemple : form_var_chose|startswith:"toto").
 

 

Filtres standards

La façon la plus complète de comprendre l'utilisation des filtres et de regarder la documentation Django en la matière.

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 comparaison, 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 :

  •   string : chaine 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
La syntaxe pour une conversion de form_var_chose est :
form_var_chose|<type>
<type> étant string, date, decimal, datetime ou time.
 
Quand la conversion échoue, le résultat est une chaine de caractères vide (c'est un principe générique dans Django que Publik respecte).
 
Exemples les plus utiles :
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_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
Exemple d'usage dans une condition Django :
form_var_datenaissance|age_in_years >= 18 --> vraie si la personne est majeure
Exemple d'usage 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 %}
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

Ajout de jours/heures

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

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és en 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|adjust_to_working_day --> prend le prochain jour ouvré
form_var_date|adjust_to_working_day_with_saturday --> prend le prochain jour ouvré en incluant le samedi

Comparer deux dates

Pour comparer des dates contenues dans deux variables form_var_date1 et form_var_date2, on va utiliser la notation suivante :
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
Attention si ça ne fonctionne pas c’est peut-être que vous utilisez une variable qui n’est pas une date, utilisez le filtre |date pour la convertir. Il est conseillé d'être «explicite» et donc d'utiliser une syntaxe telle que :
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
  • |removesuffix permet de supprimer un suffixe
  • |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. Fonctionne

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
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 deux nombres

Pour comparer deux variables form_var_nombre1 et form_var_nombre2, on va utiliser la notation suivante :
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» et donc d'utiliser une syntaxe telle que :

form_var_nombre1|decimal > form_var_nombre2|decimal

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

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

Filtres de requêtes

Ce nouveau filtre permet de faire des recherches (requêtes) sur les demandes et fiches, par exemple pour détecter des doublons simples.

form_objects|filter_by:"nom"|filter_value:"entrouvert"

permet de chercher, dans le même formulaire que celui où est posé le filtre, si la valeur "entrouvert" est déjà présente dans un champ dont l'identifiant est "nom".

forms|objects:"le-slug-du-formulaire-recherche"|filter_by:"nom"|filter_value:"entrouvert"

permet de chercher, dans un formulaire dont le slug est "le-slug-du-formulaire-recherche", si la valeur "entrouvert" est déjà présente dans un champ dont l'identifiant est "nom".

Appliqués aux fiches, ces filtres peuvent permettre de faire remonter la valeur d'un champ particulier pour une fiche donnée :

cards|objects:"slug-modele-fiche"|filter_by:"nom"|filter_value:"entrouvert"|first|get:"telephone"

permet de récupérer le contenu du champ dont l'identifiant est "telephone", dans un modèle de fiche dont le slug est "slug-fiche", pour la première fiche contenant la valeur "entrouvert" dans le champ dont l'identifiant est "nom".

Il est également possible d'utiliser le filtre |count :

{{form_objects|filter_by:"nom"|filter_value:"entrouvert"|count}} --> retourne un entier

Une condition s'écrirait ainsi :

{% if form_objects|filter_by:"nom"|filter_value:"entrouvert"|count == 0 %}Aucune demande{% endif %}

Autres filtres de requête :

  • |same_user permet de limiter les résultats aux demandes posées par le même utilisateur que la demande de départ.
  • |filter_by_user:form_user permet de filtrer les résultats aux fiches et demandes liées à un usager précis.
  • |filter_by_status:"Libellé du statut" permet de filtrer les résultats sur le statut donné.
  • |exclude_self permet d'exclure la demande de départ des résultats.

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

Dernière mise à jour le 8 février 2021 10:36 — Éditer