Listes déroulantes en cascade / dépendantes

Le principe

Les paramètres $dependField/$dependOn de relation() transforment deux champs de relation ordinaires en une paire parent/enfant : choisir une valeur dans le champ parent récupère à nouveau les propres options du champ enfant, filtrées pour ne montrer que ce qui appartient au parent qui vient d'être choisi - un champ Ville qui n'affiche que les villes du pays actuellement sélectionné, par exemple.

$dependOn nomme l'AUTRE champ de relation sur cette table à surveiller (il doit lui-même être configuré avec relation() - il faut une vraie liste déroulante à laquelle rattacher la cascade). $dependField nomme la colonne de la propre table cible de l'enfant par laquelle filtrer, comparée à la valeur actuelle de $dependOn.

Un exemple à 2 champs

Une relation Pays et une relation Ville, reliées entre elles - choisir un pays récupère à nouveau les options de la liste déroulante des villes (uniquement les villes dont le country_id correspond au pays qui vient d'être choisi) :

$xcrud->relation('country', 'meta_location', 'id', 'local_name', "type = 'CO'");

$xcrud->relation(
    'city', 'meta_location', 'id', 'local_name',
    "type = 'CI'", null, false, ' ', null, 'in_location', 'country'
);

Ici 'in_location' est $dependField (la colonne de meta_location par laquelle filtrer) et 'country' est $dependOn (le nom du champ de relation parent sur cette table). La convention de l'ancien xCrud consistant à passer '' plutôt qu'à omettre un argument final est également acceptée pour $where/$orderBy/$tree - '' est traité de la même façon que si on l'avait omis.

Paramètres importants ici

Les deux doivent soit être définis ensemble, soit être omis ensemble - l'un sans l'autre n'a aucune colonne de filtre avec laquelle s'apparier, et relation() déclenche une exception plutôt que d'ignorer silencieusement l'incohérence.

Chaînes multi-niveaux

Les chaînes de plus de deux champs fonctionnent de la même façon, un maillon à la fois - chaque maillon ne connaît que son propre parent immédiat. Une chaîne Pays → Région → Ville sur une seule table auto-référencée :

$xcrud->relation('country', 'meta_location', 'id', 'local_name', "type = 'CO'");

$xcrud->relation(
    'region', 'meta_location', 'id', 'local_name',
    "type = 'RE'", null, false, ' ', null, 'in_location', 'country'
);

$xcrud->relation(
    'city', 'meta_location', 'id', 'local_name',
    "type = 'CI'", null, false, ' ', null, 'in_location', 'region'
);

Choisir un pays récupère à nouveau les options de région (type = 'RE' AND in_location = {id du pays}) et réinitialise à la fois région et ville, puisque le propre parent de ville (région) vient lui aussi de devenir obsolète. Choisir une région récupère de même à nouveau les options de ville et réinitialise ville. Une cascade à un seul niveau (p. ex. Bureau → Responsable, filtrant les employés jusqu'au personnel d'un seul bureau) fonctionne exactement de la même façon avec un seul maillon.

Un second exemple : Bureau → Responsable

$xcrud->relation('office', 'offices', 'officeCode', 'city');

$xcrud->relation(
    'manager', 'employees', 'employeeNumber', ['firstName', 'lastName'],
    null, null, false, ' ', null, 'officeCode', 'office'
);

Ici, la table cible de la liste déroulante des responsables est employees, filtrée par sa propre colonne officeCode par rapport au bureau actuellement choisi - et le libellé est construit à partir de deux colonnes (firstName, lastName) jointes par le séparateur par défaut ' '.