Aller au contenu

Syntaxe des filtres

Cette page décrit la syntaxe des filtres au format JSON. Ces filtres permettent d'exprimer des conditions pour interroger et sélectionner des entités de manière personnalisée. Cette syntaxe est notamment utilisée dans la configuration des modules SubSet et Facet de l'application.

Format des filtres

Chaque filtre est un objet JSON. La manière dont cet objet est structuré indique à l'application comment évaluer une condition. Voici les principes clés de cette syntaxe :

  1. La fonction principale ($func) : Au cœur de chaque filtre se trouve la clé "$func". Sa valeur (par exemple, "equal", "and", "date") détermine le type d'opération ou de logique que le filtre va appliquer. C'est le point de départ pour comprendre ce que fait un filtre.

  2. Cibler un champ (field) : Pour la plupart des opérations qui évaluent les données d'une entité, la clé "field" est utilisée. Elle indique le chemin d'accès au champ spécifique sur lequel la condition doit porter (par exemple, "entry.lifecycle:status" ou "entry.createdAt"). La construction de ce chemin est expliquée plus en détail dans la section "Format général des filtres".

  3. La valeur de référence (value) : Lorsqu'une comparaison ou une évaluation est effectuée, la clé "value" fournit la donnée de référence. Cela peut être une valeur fixe (comme un texte, un nombre), un mot-clé dynamique (comme @date.today pour la date du jour), ou parfois un autre objet JSON pour des opérations plus complexes.

  4. Combiner les conditions (left, right, node) :

    • Les filtres logiques comme "and" et "or" utilisent les clés "left" et "right" pour encapsuler les deux filtres (ou sous-conditions) qu'ils combinent.
    • Le filtre "not" utilise la clé "node" pour spécifier le filtre dont la condition doit être inversée.

En résumé, vous définissez une fonction ($func), vous lui indiquez sur quel champ (field) travailler et avec quelle valeur de référence (value) opérer, ou comment combiner (left/right/node) d'autres filtres. Les sections suivantes détailleront chaque "$func" disponible et ses paramètres spécifiques.

Si le champ ciblé fait partie d'un schéma d'attributs, la syntaxe pour y accéder est la suivante :

{
  "field": "<entityType>.attributes:SchemaName.path.to.value"
}

Où <entityType> doit correspondre au type d'objet à filtrer : entry, content ou user.

attributes et lifecycle

Pour accéder aux champs des sections attributes et lifecycle, il est impératif d'utiliser le caractère : entre le nom de la section et le chemin vers le champ. Par exemple : attributes:Model.demandeur.nom ou lifecycle:subStatus.name.

Les filtres booléens

Les filtres booléens permettent de combiner plusieurs conditions.

And

Le filtre $func: "and" est utilisé lorsque deux conditions, spécifiées dans les champs left et right, doivent être simultanément vérifiées (ET logique). Le filtre ne retourne un résultat positif que si ces deux conditions sont vraies.

Par exemple, pour sélectionner les entrées dont le type d'entrée ( entryType.identifier) est égal à "BulletinAdhesion" ET dont le statut du cycle de vie (lifecycle:status) est "workingCopy" :

{
    "$func": "and",
    "left": {
        "$func": "equal",
        "field": "entryType.identifier",
        "value": "BulletinAdhesion"
    },
    "right": {
        "$func": "equal",
        "field": "lifecycle:status",
        "value": "workingCopy"
    }
}

Or

Le filtre $func: "or" combine deux conditions (définies dans left et right) avec un OU logique. Le filtre retourne un résultat positif si au moins l'une des deux conditions est vraie.

Par exemple, pour sélectionner les entrées dont le statut du cycle de vie (entry.lifecycle:status) est "workingCopy" OU "current" :

{
  "$func": "or",
  "left": {
    "$func": "equal",
    "field": "entry.lifecycle:status",
    "value": "workingCopy"
  },
  "right": {
    "$func": "equal",
    "field": "entry.lifecycle:status",
    "value": "current"
  }
}

Les filtres de comparaison

Ces filtres évaluent la relation entre la valeur d'un champ et une valeur de référence.

Equal

Le filtre $func: "equal" vérifie si la valeur du champ spécifié dans field est égale à la valeur fournie dans value.

Exemple : Vérifier si le statut du cycle de vie de l'entrée (entry.lifecycle:status) est égal à "workingCopy".

{
    "$func": "equal",
    "field": "entry.lifecycle:status",
    "value": "workingCopy"
}

Lesser

Le filtre $func: "lesser" sélectionne les objets pour lesquels la valeur du champ field est strictement inférieure à la valeur spécifiée dans value.

Exemple : Filtrer les entry créées avant aujourd'hui.

{
  "$func": "lesser",
  "field": "entry.createdAt",
  "value": "@date.today"
}

LesserOrEqual

Le filtre $func: "lesserOrEqual" vérifie si la valeur du champ field est inférieure ou égale à la valeur spécifiée dans value.

Exemple : Filtrer les entry créées avant aujourd'hui, ou aujourd'hui même.

{
  "$func": "lesserOrEqual",
  "field": "entry.createdAt",
  "value": "@date.today"
}

Greater

Le filtre $func: "greater" sélectionne les objets pour lesquels la valeur du champ field est strictement supérieure à la valeur spécifiée dans value.

Exemple : Filtrer les entry créées après le 15 janvier 2025.

{
  "$func": "greater",
  "field": "entry.createdAt",
  "value": "2025-01-15"
}

GreaterOrEqual

Le filtre $func: "greaterOrEqual" sélectionne les objets pour lesquels la valeur du champ field est supérieure ou égale à la valeur spécifiée dans value.

Exemple : Filtrer les entry créées le 15 janvier 2025 ou après cette date.

{
    "$func": "greaterOrEqual",
    "field": "entry.createdAt",
    "value": "2025-01-15"
}

Different

Le filtre $func: "different" sélectionne les objets pour lesquels la valeur du champ field est différente de la valeur spécifiée dans value.

Exemple : Filtrer les entry qui n'ont pas le statut "workingCopy".

{
  "$func": "different",
  "field": "entry.lifecycle:status",
  "value": "workingCopy"
}

Like

Le filtre $func: "like" permet d'effectuer une recherche partielle (contenant une sous-chaîne) sur la valeur d'une propriété.

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

Ce filtre est sensible à la casse.

ILike

Le filtre $func: "iLike" permet d'effectuer une recherche partielle (contenant une sous-chaîne), non sensible à la casse, sur la valeur d'une propriété.

{
  "$func": "iLike",
  "field": "entry.attributes:BulletinAdhesion.garantie.natureDuContrat",
  "value": "Dra"
}

In

Le filtre $func: "in" vérifie si la valeur spécifiée dans value est présente dans le champ field, ce dernier devant être un tableau (array). Ceci est souvent utilisé pour des champs de type liste de choix multiple.

Exemple : Sélectionner les entry où l'attribut options (un tableau) du schéma BulletinAdhesion.garantie contient la valeur "Optique Plus".

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

Les filtres de comparaison avec plusieurs valeurs

Between

Le filtre $func: "between" sélectionne les objets pour lesquels la valeur du champ field est comprise entre deux valeurs distinctes. Ce filtre est essentiellement utilisé pour des plages de dates. La plage de valeurs doit être fournie dans value avec la syntaxe <valeur1>..<valeur2>.

Exemple : Filtrer les entry créées entre le 1er mars 2025 et le 31 mars 2025 (bornes incluses).

{
    "$func": "between",
    "field": "entry.createdAt",
    "value": "2025-03-01..2025-03-31"
}

Contain

Le filtre $func: "contain" vérifie si la valeur du champ field est présente dans la liste de valeurs fournie dans value. Le champ value doit donc être un tableau de valeurs ou un mot-clé résolvant en une liste de valeurs.

Exemple : Filtrer les entry où l'attribut BulletinAdhesion.demandeur.group.identifier est égal à au moins un des identifiants de groupe de l'utilisateur connecté.

{
  "$func": "contain",
  "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 (liste des identifiants des groupes de l'utilisateur)
  • id : @me.groups.id (liste des ID des groupes de l'utilisateur)

Les filtres sans valeurs

IsNull

Le filtre $func: "isNull" sélectionne les objets pour lesquels la valeur du champ field est nulle (null).

Exemple : Filtrer les binaryContent qui n'ont pas de contentType.

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

Not

Le filtre $func: "not" permet d'inverser la condition du filtre enfant spécifié dans la propriété node. Si le filtre node est vrai, le filtre not sera faux, et vice-versa.

Exemple : Filtrer les entry où le champ displayName n'est pas égal à "Exemple NOT".

{
  "$func": "not",
  "node": {
    "$func": "equal",
    "field": "entry.displayName",
    "value": "Exemple NOT"
  }
}

Les mots-clés

Les mots-clés sont des valeurs dynamiques qui peuvent être utilisées dans le champ value des filtres décrits précédemment.

Syntaxe

Les mots-clés peuvent être exprimés sous deux formes : 1. En tant qu'objet JSON (par exemple, pour le mot-clé date). 2. En tant que chaîne de caractères préfixée par @ (par exemple, @date.today).

Date

Les filtres sur les dates offrent des fonctionnalités étendues grâce à des mots-clés spécifiques. Ces mots-clés s'appuient sur les fonctionnalités de DateTimeInterface de PHP et de la librairie Carbon pour permettre des requêtes temporelles complexes (par exemple, toutes les entrées publiées ce mois-ci, cette semaine, etc.).

Date du jour, d'hier ou de demain

Pour obtenir la date du jour, utilisez la notation @date.today ou la structure JSON équivalente.

Format JSON : 

{
  "$func": "equal",
  "field": "entry.createdAt",
  "value": {
    "$func": "date",
    "today": true
  }
}

Format "@" : 

{
  "$func": "equal",
  "field": "entry.createdAt",
  "value": "@date.today"
}

Il est possible de remplacer today par yesterday (@date.yesterday) ou tomorrow (@date.tomorrow) pour obtenir respectivement la date d'hier ou de demain. Dans la notation JSON, vous utiliseriez "yesterday": true ou "tomorrow": true.

Ajouter ou soustraire une période à la date du jour

Il est possible de calculer une date relative à aujourd'hui en ajoutant ou soustrayant une période.

Par exemple, pour filtrer les entry créées au cours des 10 derniers jours (c'est-à-dire dont la date de création est supérieure à "aujourd'hui moins 10 jours") :

Format JSON : 

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

Format "@" : 

{
  "$func": "greater",
  "field": "entry.createdAt",
  "value": "@date.sub(10 days)"
}

Pour filtrer les entry dont l'attribut date BulletinAdhesion.demande.dateEcheance arrive à échéance dans les 12 prochains jours (c'est-à-dire dont la date d'échéance est supérieure à "aujourd'hui plus 12 jours") :

Format JSON : 

{
  "$func": "greater",
  "field": "entry.attributes:BulletinAdhesion.demande.dateEcheance",
  "value": {
    "$func": "date",
    "add": "12 days"
  }
}

Format "@" : 

{
  "$func": "greater",
  "field": "entry.attributes:BulletinAdhesion.demande.dateEcheance",
  "value": "@date.add(12 days)"
}
La chaîne de caractères pour add ou sub (par exemple, "10 days", "12 days", "1 month", "2 years") suit les formats relatifs reconnus par la fonction modify de PHP DateTime.

Me

Le mot-clé me permet d'utiliser des informations relatives à l'utilisateur actuellement connecté dans les filtres.

Format JSON (pour utiliser l'ID de l'utilisateur connecté) : 

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

Le mot-clé "Me" peut être utilisé avec la syntaxe @me ou en spécifiant un champ particulier avec @me.<field>. Les champs disponibles sont :

  • @me : l'ID de l'utilisateur connecté.
  • @me.id : l'ID de l'utilisateur connecté.
  • @me.identifier : l'identifiant métier de l'utilisateur connecté.
  • @me.displayName : le nom d'affichage de l'utilisateur connecté.
  • @me.email : l'adresse e-mail de l'utilisateur connecté.
  • @me.groups : la liste des ID des groupes auxquels l'utilisateur appartient.
  • @me.groups.identifier : la liste des identifiants métier des groupes auxquels l'utilisateur appartient.
  • @me.attributes.<path.vers.attribut> : la valeur d'un champ spécifique dans les attributs de l'utilisateur (par exemple, @me.attributes:SchemaUser.service).

Exemple d'utilisation de @me avec des attributs spécifiques :

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

Exemples de filtres complexes

Il est possible de combiner plusieurs fonctions pour créer des filtres plus élaborés. L'exemple suivant illustre une telle combinaison, souvent utilisée pour des vues spécifiques comme "Demandes du jour à qualifier".

Dans cet exemple, un filtre and est utilisé. Il combine deux conditions principales définies : 1. La première condition (left) vérifie si le champ entry.lifecycle:status est égal à "workingCopy" en utilisant une fonction equal 2. La seconde condition (right) vérifie si le champ entry.createdAt est supérieur ou égal à la date du jour. Ceci est réalisé en utilisant une fonction greaterOrEqual combinée à une fonction date qui retourne la date du jour.

Exemple de configuration de filtre :

{
  "$func": "and",
  "left": {
    "$func": "equal",
    "field": "entry.lifecycle:status",
    "value": "workingCopy"
  },
  "right": {
    "$func": "greaterOrEqual",
    "field": "entry.createdAt",
    "value": "@date.today"
  }
}