Aller au contenu

Filtres et facettes des vues

Dans ce chapitre nous allons découvrir comment utiliser des filtres sur des subsets, des vues ou des facettes:

Définitions

Les subsets sont des sous-ensembles d'objet. Par exemple, un subset peut être toutes les entrées (objet) dont le type est une demande d'admission. Ils permettent ainsi de regrouper et de synthétiser des données. Des filtres supplémentaires peuvent être appliqués sur ces sets afin de faire des recherches plus précises. Par exemple, une fois récupéré la liste des entrées de type demande d'admission, j'aimerais savoir lesquels ont été crée ce jour. Le rajout de filtres sur des subsets s'appellent des facettes. La création de subsets (et de facettes) doivent suivre une syntaxe particulière définies ci-après. Elles suivent une logique de construction de requête similaire à la syntaxe SQL. Des recherches de types valeur égale à, valeur supérieure à, inférieure à, comprise entre, etc sont possibles.

Les types de filtres

Les différents types de filtres disponibles dans l'application sont :

  • And : Cette valeur ET cette valeur
  • Or : Cette valeur OU cette valeur
  • Equals : Cette valeur ÉGALE cette valeur
  • Date : Cette valeur correspond à cette date
  • Me : Cette valeur est moi
  • Like : Cette valeur RESSEMBLE à cette valeur
  • Lesser : Cette valeur est INFÉRIEURE à cette valeur
  • LesserOrEquals : Cette valeur est INFÉRIEURE OU ÉGALE à cette valeur
  • Greater : Cette valeur est SUPÉRIEURE à cette valeur
  • GreaterOrEquals : Cette valeur est SUPÉRIEURE OU ÉGALE à cette valeur
  • IsNull : Cette valeur est NULLE
  • Between : Cette valeure est COMPRISE ENTRE cette valeur et cette valeur
  • Different : Cette valeur est DIFFÉRENTE DE cette valeur
  • In : Cette valeur existe dans ce tableau
  • Contains : Cette valeur est contenue dans ce tableau

Pour chaque filtre, nous avons une notion de gauche (left) ou droite (right), correspondant à la partie de la requête sur lesquels s'applique la comparaison de valeurs. Par exemple sur la requete Les entrées dont la date de création est supérieurs à la date du jour, on cherche les entrées où date_creation greater today, le filtre est ici greater (supérieure à ou >) la partie gauche de la requête est date_creation et la partie droite today.
La notion de gauche et droite permet également de créer des sous requetes dans la requete.
Par exemple, si je cherche à rechercher toutes les entrées de type demande d'adhésion dont la date de création est supérieure à aujourd'hui ou après avril 2021, la requete ressemblera à
(entry = demande_adhesion ET (date_creation > today OR date_creation > 2021/04/30))
où dans ce cas entry = demande_adhesion sera à gauche, le filtre sera AND et la partie droite sera (date_creation > today OR date_creation > 2021/04/30).
Cette partie droite sera elle même divisé en deux requêtes, une pour date_creation > today et une autre pour date_creation > 2021/04/30

Mise en forme des filtres

Les filtres sont des subsets et en tant que tel implémentent entre autres les traits Documentable et Identifier. Ce qui signifie que chaque filtre peut être nommé et identifié par un identifier. Les filtres en eux-mêmes sont compris dans une propriété filter et sont contenus dans un objet set plus large 

"owner": ownerId                     // Identifiant du propriétaire du subset
"displayName": name                  // Nom d'affichage du filtre
"identifier": filterName             // Identifiant unique du filtre
"sequence" : 1                       // Position du filtre retourné pour l'affichage des filtres
"listDefinition" : listDefinitionId  // Identifiant de la liste défintion du filtre, c'est à dire les colonnes à afficher
"definition" : {                     // Définition du filtre à appliquer
    "filter" : {                     // Filtre en lui même
        "$func" : "functionName"     // Nom de la fonction à appliquer (non sensible à la casse)
        "$vars" : {                  // Paramètres de variable à prendre en compte
            "field": "path.to.field" // Champ sur lequel la requête s'applique
            "value": "valeur"        // Valeur que doit prendre le champ
        }
    }
}

Si le champ fait partie d'un schéma d'attribut la syntaxe vers le champ en question est de la forme 

"field" : "fieldType.attributes:SchemaName.path.to.value"

FieldType est le type de donnée (entry, binary, user, etc)
Noter la présence des deux points avant le nom du schéma. Un exemple de schéma est donné dans l'exemple du filtre différent
Nous allons maintenant voir des exemples de paramétrage attendus par l'application pour chacun de ces filtres.

Exemples de Filtres

Equals

Cette requête vérifie que les valeurs sont égales entre elles. Ici que le la valeur du cycle de vie soit égale à brouillon 

"filter": {
    "$func": "equals",
    "$vars": {
        "field": "lifecycle.currentStatus",
        "value": "workingCopy_draft"
    }
}

And

On utilise cette requête quand on a deux conditions left et right à vérifier (c'est une sorte de combinaison de vérifications)
Ici, on vérifie que la valeur des identifiants de type d'entrée soient égale à BulletinAdhesion et que leur statut de cycle de vie soit en brouillon ("workingCopy_draft") 

"filter": {
    "$func": "AND",
    "$vars": {
        "left": {
            "$func": "equals",
            "$vars": {
                "field": "entryType.identifier",
                "value": "BulletinAdhesion"
           }
        },
        "right": {
            "$func": "equals",
            "$vars": {
                "field": "lifecycle.currentStatus",
                "value": "workingCopy_draft"
            }
        }
    }
}

Or

Cette requête vérifie que l'une des deux conditions left ou right est réalisée.
Ici que l'objet soit au statut brouillon OU au statut publié. 

"filter": {
    "$func": "or",
    "$vars": {
        "left": {
            "$func": "equals",
            "$vars": {
                "field": "lifecycle.currentStatus",
                "value": "workingCopy_draft"
            }
        },
        "right": {
            "$func": "equals",
            "$vars": {
                "field": "lifecycle.currentStatus",
                "value": "current_published"
            }
        }
    }
}

Date

Les requêtes sur les dates suivent un comportement un peu différent des autres types de requêtes. De nombreux mots-clés sont disponibles en plus des requêtes basique (inférieur, supérieur, égale, etc). Ces fonctions supplémentaires font appel en interne aux différentes possibilités offertes pas DateTimeInterface de php ainsi que les fonctions supplémentaires proposés par la librairie Carbon. Cela permet de réaliser des requêtes plus complexes, du style, toutes les entrées publiés ce mois ou bien cette semaine, etc.

Vous trouverez plus de details dans la section Exemples de l'utilisation de la libraire carbon pour la gestion des dates en bas de page.
L'exemple de requête suivant retourne toutes les entrées crées dans les dix derniers jours. 

"filter": {
    "$func": "lesser",
    "$vars": {
        "field": "entry.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "sub": "10 days"
            }
        }
    }
}

L'exemple de requête suivant retourne toutes les entrées crées dans les dix prochains jours. 

"filter": {
    "$func": "lesser",
    "$vars": {
        "field": "entry.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "add": "10 days"
            }
        }
    }
}

Me

Cette requête vérifie si c'est l'utilisateur actuellement connecté est le créateur d'une entrée. 

"filter": {
    "$func": "equals",
    "$vars": {
        "field": "entry.createdBy",
        "value": {
            "$func": "me"
        }
    }
}

Le filtre "Me" peut être utilisé comme mot-clé avec la syntaxe @me ou @me.<field>. Les fields possible sont :

  • @me : utilise l'id de l'utilisateur
  • @me.id : l'id de l'utilisateur
  • @me.identifier : l'identifier métier de l'utilisateur
  • @me.displayName : le nom de l'utilisateur
  • @me.email : l'email de l'utilisateur
  • @me.groups : la liste d'id des groupes de l'utilisateur
  • @me.groups.identifier : la liste d'identifier des groupes de l'utilisateur
  • @me.attributes.<path.vers.attribute> : utilise un champ dans les attributes de l'utilisateur.

Exemple :

"filter": {
  "$func": "or",
  "$vars": {
    "left": {
      "$func": "equals",
      "$vars": {
        "field": "entry.attributes:BulletinAdhesion.demandeur.code_utilisateur",
        "value": "@me.attributes.ModelUser.code"
      }
    },
    "right": {
      "$func": "equals",
      "$vars": {
        "field": "entry.attributes:BulletinAdhesion.demandeur.identifiant_utilisateur",
        "value": "@me.identifier"
      }
    }
  }
}

Like

Like permet d'effectuer une recherche partielle sur une propriété. Ici on recherche un attribut nature du contrat dans un schéma qui comporte la valeur "dra" 

"filter": {
    "$func": "like",
    "$vars": {
        "field": "entry.attributes:BulletinAdhesion.garantie.natureDuContrat",
        "value": "dra"
    }
}

Lesser

Cette requête liste les objets dont la valeur est strictement inférieure à la valeur passée en paramètre. Ici, si la date de création est inférieure à la date du jour. 

"filter": {
    "$func": "lesser",
    "$vars": {
        "field": "entry.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "today": "today"
            }
        }
    }
}
  • Lesserorequal : Cette requête vérifie si la valeur est inférieure ou égale à la valeur passée en paramétre. Par exemple ici, que la date de création de l'objet est inférieure à la date du jour. 
"filter": {
    "$func": "lesserorequal",
    "$vars": {
        "field": "entry.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "today": "today"
            }
        }
    }
}

Greater

Cette requête liste les objets dont la valeur est strictement supérieure à la valeur passée en paramètre. Ici, si la date de création est supérieure à la date du jour 

"filter": {
    "$func": "greater",
    "$vars": {
        "field": "entry.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "today": "today"
            }
        }
    }
}

Greaterorequal

Cette requête liste tous les objets dont la valeur est supérieure ou égaleà la valeur passée en paramètre. Ici si la date de création est supérieure ou égale à la date du jour. 

"filter": {
    "$func": "greaterorequal",
    "$vars": {
        "field": "entry.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "today": "today"
            }
        }
    }
}

Isnull

Cette requête liste les objets dont la valeur recherchée est nulle.

"filter": {
    "$func": "isNull",
    "$vars": {
        "field": "contentType"
    }
}

Between

Cette requête liste les objets dont la valeur est comprise entre deux valeures distinctes. Elle est essentiellement utilisée pour des plages de dates. 

"filter": {
    "$func": "between",
    "$vars": {
        "field": "entry.createdAt",
        "value": "1972-02-02..1972-02-04"
    }
}

Different

Cette requête liste les objets dont la valeur est différente de celle donnée en paramètre

"filter": {
    "$func": "different",
    "$vars": {
        "field": "entry.attributes:CONTRATMGC.taches.code",
        "value": "T_ADH"
    }
}

discriminator

Cette requête liste tous les objets par type. la liste des types disponibles est la suite: [entry, binaryContent et user] 

"filter": {
    "$func": "discriminator",
    "$vars": {
        "field": "entry.attributes:CONTRATMGC.taches.code",
        "value": "entry"
    }
}

In

Cette requête liste les objets dont la valeur recherchée fait partie d'une propriété tableau 'array' d'un modèle d'attributs. Par exemple, un choix dans une liste déroulante

"filter": {
    "$func": "IN",
    "$vars": {
        "field": "entry.attributes:BulletinAdhesion.garantie.options",
        "value": "Optique Plus"
    }
}

Contains

Cette requête liste les objets dont la valeur recherchée fait partie d'une propriété tableau 'array' contenant la liste des identifiants du groupe de l'utilisateur connecté

"filter": {
    "$func": "contains",
    "$vars": {
        "field": "entry.attributes:BulletinAdhesion.demandeur.group.identifier",
        "value": "@me.groups.identifier"
    }
}

Les champs utilisables avec le mot clé @me.groups sont :

  • identifier : @me.groups.identifier
  • id : @me.groups.id

Exemples de filtres complexes

Dans cet exemple nous allons utiliser quatre fonctions différentes : Date, And, Equals et Greaterorequal.
On utilise le And quand notre filtre vérifie plus qu'une condition(left, right), ici nous allons vérifier que lifecycle.currentStatus === workingCopy_draft avec la fonction Equals et que entry.createdAt est supérieur ou égale à la date du jour avec la fonction Greaterorequal combiné avec la fonction Date nous retournant la date souhaitée, dans notre cas c'est la date du jour.
Exemple de vue "Demandes du jour à qualifier" : 

"filter": {
    "$func": "AND",
    "$vars": {
        "left": {
            "$func": "equals",
            "$vars": {
                "field": "lifecycle.currentStatus",
                "value": "workingCopy_draft",
            }
        },
        "right": {
            "$func": "greaterorequal",
            "$vars": {
                "field": "entry.createdAt",
                "value": {
                    "$func": "date",
                    "$vars": {
                        "today": "today"
                    }
                }
            }
        }
    }
}

Facettes

Les facettes sont des filtres sur des filtres. Elles permettent de filtrer sur des résultats déja filtré.
Cette fonctionnalité est particulièrement utile dans le cas d'une utilisation de l'api par une interface graphique. Par exemple, un lien qui amène vers la liste des documents publiés et que dans cette liste, je souhaite maintenant afficher uniquement les documents publiés ce mois.

Exemple de Facettes "Documents publiés ce mois" :

Pour cet exemple des facettes nous avons utilisé une fonction mère greaterorequal pour filtrer par la fonction supérieur ou égale et la fonction date afin de récupérer le premier jour du mois courant ce que nous a permis de récupérer les éléments avec content.createdAt supérieur ou égale le premier jour du mois courant 

"facets": [
    {
        "identifier": 'facetThisMonth',
        "displayName": "Documents publiés ce mois",
        "sequence": 1,
        "filter": {
            "$func": "greaterorequal",
            "$vars": {
                "field": "content.createdAt",
                "value": {
                    "$func": "date",
                    "$vars": {
                        "firstOfMonth": "firstOfMonth"
                    }
                }
            }
        }
    }
]

Exemples de l'utilisation de la librairie carbon pour la gestion des dates

Récupérer la date d'hier

"filter": {
    "$func": "greaterorequal",
    "$vars": {
        "field": "content.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "yesterday": "yesterday"
            }
        }
    }
}

Récupérer la date de demain

"filter": {
    "$func": "greaterorequal",
    "$vars": {
        "field": "content.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "tomorrow": "tomorrow"
            }
        }
    }
}

Récupérer la date d'aujourd'hui

"filter": {
    "$func": "greaterorequal",
    "$vars": {
        "field": "content.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "today": "today"
            }
        }
    }
}

Récupérer le premier jour du mois courant

"filter": {
    "$func": "greaterorequal",
    "$vars": {
        "field": "content.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "firstOfMonth": "firstOfMonth"
            }
        }
    }
}

Récupérer une date ultérieure avec la fonction sub qui peut prendre jusqu'à 3 paramètres 'jour', 'heure' et 'minute'

"filter": {
    "$func": "lesser",
    "$vars": {
        "field": "entry.createdAt",
        "value": {
            "$func": "date",
            "$vars": {
                "sub": "3 days 10 hours 23 minutes"
            }
        }
    }
}

Les exemples en dessus se sont les fonctions(ou les vars) que notre filtre date prend en compte. Pour plus de détails sur la librairie carbon je vous invite à consulter la documentation