Personnaliser les requêtes de liens et d'autocomplétion

Dokos permet aux développeurs de filtrer dynamiquement les résultats affichés dans les champs de type Lien (sélection d'un document existant) et Autocomplétion (suggestion de valeurs). Cette personnalisation s'effectue via la méthode set_query, qui définit une fonction de filtrage appelée chaque fois que l'utilisateur ouvre la liste déroulante.

Exemple — Maison Verte SARL Sur le bon de commande de Maison Verte SARL, le champ "Personne de contact" doit être filtré en fonction du client sélectionné. Grâce à une requête personnalisée, seules les personnes de contact liées au client apparaissent dans la liste déroulante.

Principe

La méthode frm.set_query(fieldname, callback) associe une fonction de filtrage à un champ. Cette fonction reçoit des informations sur le document en cours et renvoie un objet de filtres ou une requête serveur personnalisée.

      
flowchart LR
    A[Utilisateur ouvre la liste déroulante] --> B[La fonction get_query est appelée]
    B --> C{Filtres renvoyés}
    C -->|Filtres simples| D[Liste filtrée côté serveur]
    C -->|Requête personnalisée| E[Résultats via query server]
    D --> F[Affichage des résultats]
    E --> F

    

Arguments passés à la fonction de requête

La fonction de filtrage reçoit désormais quatre arguments :

Nouveauté : Le quatrième argument frm est désormais transmis systématiquement à toutes les fonctions de requête, y compris dans les grilles (tables enfants) et l'autocomplétion. Auparavant, il fallait recourir à la variable globale cur_frm pour accéder au formulaire depuis la fonction.

Exemple de base

frappe.ui.form.on("Sales Order", {
    setup(frm) {
        frm.set_query("contact_person", (doc, cdt, cdn, frm) => {
            return {
                filters: { link_name: doc.customer }
            };
        });
    }
});

Dans cet exemple, la liste déroulante du champ contact_person n'affiche que les personnes de contact dont link_name correspond au client du bon de commande.

Utiliser le formulaire pour interagir avec l'interface

Le passage de l'objet frm permet d'effectuer des actions sur l'interface directement depuis la fonction de requête, par exemple faire défiler le formulaire vers un champ manquant.

Exemple — Bureau Moderne Sur le bon de commande, si l'utilisateur tente de sélectionner une personne de contact sans avoir choisi de client, Dokos le ramène automatiquement au champ "Client" en le mettant en évidence.

frm.set_query("contact_person", (doc, cdt, cdn, frm) => {
    if (!doc.customer) {
        frm.scroll_to_field("customer");
    }
    return { filters: { link_name: doc.customer } };
});

Comportement dans les tables enfants (grilles)

Dans une table enfant, la fonction de requête s'applique au champ de la ligne concernée. Les arguments cdt et cdn identifient la ligne en cours d'édition, tandis que frm donne accès au formulaire parent.

frappe.ui.form.on("Sales Order Item", {
    item_code(frm, cdt, cdn) {
        frm.set_query("warehouse", (doc, cdt, cdn, frm) => {
            return {
                filters: {
                    company: frm.doc.company,
                    is_group: 0
                }
            };
        });
    }
});

Bon à savoir : Le sélecteur d'ajout multiple dans une grille (bouton "Ajouter plusieurs lignes") transmet désormais le formulaire parent de la même manière qu'un champ de lien standard. Les fonctions de requête écrites pour les grilles n'ont plus besoin d'utiliser cur_frm.

Champ d'autocomplétion

Les champs de type Autocomplétion bénéficient du même mécanisme. La fonction de requête reçoit les quatre arguments identiques.

frm.set_query("mode_of_payment", (doc, cdt, cdn, frm) => {
    return {
        query: "erpnext.accounts.doctype.sales_invoice.sales_invoice.get_mode_of_payment",
        filters: { company: frm.doc.company }
    };
});

Compatibilité

Les fonctions de requête existantes qui n'utilisent que trois arguments continuent de fonctionner sans modification : le quatrième argument est simplement ignoré. Aucune migration n'est nécessaire.

Bonnes pratiques

• Préférez frm à cur_frm : la variable cur_frm reste disponible, mais l'argument frm est plus fiable, notamment dans les contextes de fenêtres modales ou de grilles imbriquées.
• Évitez les effets de bord lourds : la fonction de requête est appelée à chaque ouverture de la liste déroulante. Les appels réseau ou les calculs coûteux doivent être évités.
• Testez dans les grilles : assurez-vous que vos filtres fonctionnent à la fois en édition de ligne simple et en ajout multiple.