Paramètres vides dans les requêtes BiBOARD : #NULL

Cette page explique comment gérer les paramètres vides dans les requêtes BiBOARD afin d’afficher toutes les données lorsqu’aucune valeur n’est sélectionnée dans un composant.

Objectif #

Dans un tableau de bord BiBOARD, un composant peut filtrer un autre composant à l’aide d’un lien.

Exemple :

• une liste déroulante filtre un tableau ;
• une tuile filtre un graphique ;
• un tableau filtre un autre tableau ;
• une carte filtre un indicateur.

Lorsqu’aucune valeur n’est sélectionnée dans le composant source, le composant cible reçoit une valeur spéciale appelée valeur nulle BiBOARD.

Il est important de gérer cette valeur dans la requête SQL.
Sinon, le composant cible peut afficher aucune donnée à l’ouverture du tableau de bord.

---

Principe général #

Quand un paramètre n’a pas de valeur sélectionnée, BiBOARD ne transmet pas toujours un vrai NULL SQL.
Il utilise une valeur spéciale selon le type du paramètre :

Type de paramètre	Valeur nulle BiBOARD
Chaîne de caractères	‘#NULL’
Date	‘1900-01-01’
Numérique	-987

Ces valeurs permettent de savoir que l’utilisateur n’a rien sélectionné.

---

Comportement attendu dans un tableau de bord #

Dans la plupart des cas, le comportement souhaité est le suivant :

Situation	Résultat attendu
Aucune sélection	afficher toutes les données
Une valeur sélectionnée	afficher uniquement cette valeur
Plusieurs valeurs sélectionnées	afficher les valeurs sélectionnées
Sélection supprimée	réafficher toutes les données

Pour obtenir ce comportement, il faut écrire la requête avec un filtre optionnel.

---

Cas d’usage #

Exemple 1 — Paramètre texte #

Cas simple #

On souhaite filtrer une table de ventes par pays.

Paramètre BiBOARD :

:p_Pays

Requête SQL :

Select
  Pays,
  DateCommande,
  Montant
From
  Ventes
Where
  (
    Pays = :p_Pays
    Or :p_Pays = '#NULL'
  )

Explication #

Si l’utilisateur sélectionne France, la requête devient équivalente à :

Where Pays = 'France'

Si l’utilisateur ne sélectionne rien, le paramètre vaut #NULL.
La condition suivante devient vraie :

:p_Pays = '#NULL'

La requête affiche donc toutes les lignes.

---

Exemple 2 — Paramètre date #

On souhaite filtrer une table par date de commande.

Paramètre BiBOARD :

:p_DateCommande

Requête SQL :

Select
  Pays,
  DateCommande,
  Montant
From
  Ventes
Where
  (
    DateCommande = :p_DateCommande
    Or :p_DateCommande = '1900-01-01'
  )

Explication #

Si l’utilisateur sélectionne une date, la requête filtre sur cette date.
Si aucune date n’est sélectionnée, BiBOARD envoie la valeur spéciale :

1900-01-01

La requête affiche alors toutes les dates.

---

Exemple 3 — Paramètre numérique #

On souhaite filtrer une table par numéro de commande.

Paramètre BiBOARD :

:p_NumCommande

Requête SQL :

Select
  NumCommande,
  DateCommande,
  Montant
From
  Commandes
Where
  (
    NumCommande = :p_NumCommande
    Or :p_NumCommande = -987
  )

Explication #

Si l’utilisateur sélectionne une commande, le filtre est appliqué.

Si aucune commande n’est sélectionnée, BiBOARD envoie la valeur numérique spéciale :

-987

La requête affiche donc toutes les commandes.

---

Exemple 4 — Plusieurs filtres dans la même requête #

Il est possible de gérer plusieurs paramètres dans une même requête.

Exemple :

Select
  Pays,
  DateCommande,
  NumCommande,
  Montant
From
  Commandes
Where
  (
    Pays = :p_Pays
    Or :p_Pays = '#NULL'
  )
And
  (
    DateCommande = :p_DateCommande
    Or :p_DateCommande = '1900-01-01'
  )
And
  (
    NumCommande = :p_NumCommande
    Or :p_NumCommande = -987
  )

Résultat #

Chaque filtre devient optionnel.
Si l’utilisateur ne sélectionne rien, toutes les données sont affichées.
Si l’utilisateur sélectionne uniquement un pays, seule la condition sur le pays est appliquée.
Si l’utilisateur sélectionne un pays et une date, les deux filtres sont appliqués.

---

Exemple 5 — Filtre avec plusieurs valeurs #

Certains composants peuvent envoyer plusieurs valeurs vers un paramètre.

Exemples :

• liste à sélection multiple ;
• tuile avec sélection multiple ;
• tableau utilisé comme source de filtre.

Dans ce cas, on utilise généralement IN.

Exemple avec un filtre sur les mois :

Select
  CodeMois,
  NomMois,
  Montant
From
  VentesMensuelles
Where
  (
    :p_CodeMois = '#NULL'
    Or CodeMois in (:p_CodeMois)
  )
Order By
  CodeMois

Explication #

À l’ouverture du tableau de bord, aucune tuile ou aucune valeur n’est sélectionnée.
Le paramètre vaut donc :

#NULL

La condition suivante est vraie :

:p_CodeMois = '#NULL'

La requête affiche tous les mois.
Si l’utilisateur sélectionne plusieurs mois, par exemple février et mars, le filtre devient équivalent à :

CodeMois in (2, 3)

Le tableau affiche alors uniquement les mois sélectionnés.

---

Exemple complet avec une tuile qui filtre un tableau #

Besoin fonctionnel #

On a une tuile qui affiche les mois.
Quand aucun mois n’est sélectionné, le tableau doit afficher tous les mois.
Quand un ou plusieurs mois sont sélectionnés, le tableau doit afficher uniquement les mois sélectionnés.

Requête du tableau cible #

Select
  CodeMois,
  NomMois,
  Ratio,
  Nombre
From
  SatisfactionClient
Where
  (
    :p_CodeMois = '#NULL'
    Or CodeMois in (:p_CodeMois)
  )
Order By
  CodeMois

Résultat attendu #

Action utilisateur	Valeur du paramètre	Résultat
Ouverture du tableau de bord	#NULL	tous les mois
Clic sur Février	2	février uniquement
Clic sur Février et Mars	2,3	février et mars
Désélection	#NULL	tous les mois

---

Bonnes pratiques pour les Designers #

Toujours gérer le cas “aucune sélection” #

Lorsqu’un composant est filtré par un autre composant, il faut toujours se poser la question :

Que doit afficher le composant cible si l’utilisateur n’a encore rien sélectionné ?

Dans la majorité des cas, la réponse est :

• Il doit afficher toutes les données.
• Il faut donc gérer la valeur nulle BiBOARD dans la requête.

---

Toujours mettre les conditions entre parenthèses #

Il est recommandé d’écrire chaque filtre optionnel entre parenthèses.

Exemple :

Where
  (
    Pays = :p_Pays
    Or :p_Pays = '#NULL'
  )
And
  (
    Annee = :p_Annee
    Or :p_Annee = -987
  )

Cela évite les erreurs de priorité entre AND et OR.

---

Ne pas confondre NULL SQL et valeur nulle BiBOARD #

Il ne faut pas écrire uniquement :

Where Pays is null

ou :

Where :p_Pays is null

Dans ce cas précis, BiBOARD utilise une valeur spéciale comme #NULL.

Il faut donc tester cette valeur :

Or :p_Pays = '#NULL'

---

Adapter la valeur nulle au type du paramètre #

La valeur à tester dépend du type du paramètre BiBOARD.

Type	Test à utiliser
Texte	:p_Parametre = ‘#NULL’
Date	:p_Parametre = ‘1900-01-01’
Numérique	:p_Parametre = -987

---

Tester la requête dans l’aperçu

Dans l’éditeur de requête, il est conseillé de tester le paramètre avec sa valeur nulle.

Exemples :

Type de paramètre	Valeur à tester
Texte	#NULL
Date	1900-01-01
Numérique	-987

Cela permet de vérifier que le composant affiche bien toutes les données lorsqu’aucune sélection n’est faite.

---

Pourquoi gérer les paramètres vides dans les requêtes BiBOARD ? #

Dans un tableau de bord, un composant peut filtrer un autre composant à l’aide d’un paramètre. Si aucune valeur n’est sélectionnée, BiBOARD transmet une valeur spéciale. La requête SQL doit donc prévoir ce cas pour éviter d’afficher un tableau vide au chargement.

---

Résumé #

Pour qu’un composant affiche toutes les données lorsqu’aucune valeur n’est sélectionnée, il faut rendre le filtre optionnel dans la requête SQL.

Modèle général :

Where
  (
    Champ = :Parametre
    Or :Parametre = ValeurNulleBiBOARD
  )

Pour plusieurs valeurs :

Where
  (
    :Parametre = ValeurNulleBiBOARD
    Or Champ in (:Parametre)
  )

Valeurs nulles BiBOARD à retenir :

Type	Valeur nulle
Chaîne de caractères	‘#NULL’
Date	‘1900-01-01’
Numérique	-987

Cette méthode est valable de manière générale pour les composants BiBOARD utilisant des paramètres dans leurs requêtes.