Listes déroulantes de relation
Transformez une colonne de clé étrangère brute en liste déroulante, en combobox avec recherche, ou en sélection multiple résolue par rapport à une autre table avec relation().
Ce que fait relation()
relation() relie une colonne réelle et éditable de la table courante (p. ex. payments.customerNumber) à une recherche dans une autre table. Le formulaire de création/édition affiche une liste déroulante des lignes de cette table au lieu d'une simple saisie d'identifiant numérique, et la liste affiche le nom résolu à la place de l'identifiant brut.
$xcrud->relation(
'customerNumber', 'customers', 'customerNumber', 'customerName',
"country = 'USA'", null, false, ' ', null, null, null, true
);La table cible doit elle-même être accessible de la même manière que n'importe quelle autre table du site - une vraie table, pas mise en liste noire, avec une clé primaire à une seule colonne. Elle n'a pas besoin de sa propre page CRUD ; relation() peut lire une table que rien d'autre sur le site ne parcourt jamais directement.
Paramètres
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
$field | string | - | La colonne réelle et éditable de cette table à relier (p. ex. customerNumber). |
$targetTable | string | - | La table dans laquelle rechercher les valeurs. |
$targetId | string | - | Colonne de $targetTable dont la valeur est réenregistrée dans $field. |
$targetName | string|array | - | Colonne(s) affichée(s) comme libellé d'option. Un tableau (p. ex. ['contactFirstName', 'contactLastName']) est joint avec $concatSeparator pour afficher quelque chose comme « Prénom Nom ». |
$where | array|string|null | null | Restreint les lignes cibles proposées. Un tableau est une égalité colonne=>valeur sûre, combinée par ET et liée comme paramètres. Une chaîne est du SQL brut de confiance, écrit par le développeur (même niveau de confiance que where_raw()), avec éventuellement des espaces réservés {field} substitués par la propre valeur de la ligne courante. |
$orderBy | string|null | null | Ordre de tri de la liste d'options. |
$multi | bool | false | Affiche une sélection multiple au lieu d'une liste déroulante simple ; la valeur enregistrée devient une liste d'identifiants séparés par des virgules. |
$concatSeparator | string | ' ' | Séparateur utilisé quand $targetName est un tableau de colonnes. |
$tree | mixed | null | Réservé pour une future liste déroulante hiérarchique/en arbre indenté - pas encore implémenté ; passer une valeur différente de la valeur par défaut déclenche une exception. |
$dependField | string|null | null | Colonne de $targetTable par laquelle filtrer, comparée à la valeur actuelle de $dependOn. Voir Listes déroulantes en cascade / dépendantes. |
$dependOn | string|null | null | Nom d'un autre champ configuré avec relation() sur cette table, dont la sélection actuelle pilote le filtre ci-dessus. |
$search | bool | false | Affiche une combobox avec recherche (une saisie de texte qui filtre la liste d'options récupérée au fur et à mesure de la frappe) au lieu d'un simple <select> - utile dès qu'il y a des dizaines d'options. Se combine avec $multi pour des puces amovibles. |
Filtrer la liste d'options
La forme tableau de $where est le choix sûr par défaut - simple égalité, paramétrée :
$xcrud->relation('catid', 'categories', 'cid', 'name', ['published' => 1]);La forme chaîne est un fragment SQL brut pour tout ce qu'un tableau d'égalité ne peut pas exprimer - c'est du SQL de confiance, écrit par le développeur, jamais construit à partir d'une entrée utilisateur :
$xcrud->relation('customerNumber', 'customers', 'customerNumber', 'customerName', "country = 'USA'");Quelle que soit la forme utilisée, la configuration de relation entière - table, colonne d'identifiant, colonne(s) de nom, where, order, multi - est signée par HMAC avec XcrudConfig::$appSecret de la même façon qu'un filtre where() de base, de sorte qu'elle ne peut pas être reciblée ou élargie en modifiant quoi que ce soit côté client.
subselect() : une colonne calculée en lecture seule
Là où relation() résout une clé étrangère éditable, subselect() ajoute une colonne d'affichage uniquement, calculée à partir d'une expression SQL corrélée arbitraire - rien n'y est réenregistré, et elle n'est jamais éditable, triable, ni consultable par recherche.
$xcrud->subselect(
'orderCount',
'SELECT COUNT(*) FROM orders o WHERE o.customerNumber = payments.customerNumber'
);$field devient une nouvelle colonne aux côtés des colonnes réelles de la table et doit être un identifiant valide qui n'est pas déjà un nom de colonne réel. $sql est du SQL de confiance, écrit par le développeur - comme la chaîne brute $where de relation(), elle est signée par HMAC avec XcrudConfig::$appSecret au rendu de la page et revérifiée à chaque requête, de sorte qu'un visiteur ne peut pas la falsifier, mais elle n'est jamais validée ni mise en bac à sable par rapport à ce que vous écrivez - gardez-la toujours écrite côté serveur, jamais assemblée à partir d'une entrée de requête.
Listes déroulantes en cascade
$dependField/$dependOn permettent aux options d'une liste déroulante de relation de se filtrer en fonction de la valeur actuellement sélectionnée d'un autre champ sur le même formulaire - par exemple une liste déroulante de villes qui ne propose que les villes du pays actuellement sélectionné. Voir Listes déroulantes en cascade / dépendantes pour le déroulé complet, chaînes multi-niveaux comprises.