Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Personnalisation

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

Filtrer les résultats des champs Lien et Autocomplétion avec la méthode set_query, par exemple selon le client choisi.

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 Exemple fictif : sur la commande client 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.

Arguments passés à la fonction de requête

La fonction de filtrage reçoit quatre arguments :

ArgumentDescription
docLe document du formulaire (frm.doc). Dans une table enfant, c'est aussi le document parent.
cdtLe type de document du champ. Dans une table enfant, c'est le type de la ligne.
cdnLe nom du document. Dans une table enfant, c'est le nom de la ligne.
frmLe formulaire courant. Utilisez-le à la place de la variable globale cur_frm.

La fonction renvoie soit un objet (filters, query), soit une chaîne. Une chaîne est le chemin d'une méthode serveur de recherche.

Exemple de base

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

Dans cet exemple, la liste déroulante du champ contact_person n'affiche que les contacts liés au client de la commande. La méthode serveur contact_query lit la table des liens du contact.

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 Exemple fictif : sur la commande client, si l'utilisateur tente de sélectionner une personne de contact sans avoir choisi de client, le formulaire défile jusqu'au champ "Client".

frm.set_query("contact_person", (doc, cdt, cdn, frm) => {
    if (!doc.customer) {
        frm.scroll_to_field("customer");
    }
    return {
        query: "frappe.contacts.doctype.contact.contact.contact_query",
        filters: { link_doctype: "Customer", link_name: doc.customer }
    };
});

Comportement dans les tables enfants (grilles)

Pour un champ d'une table enfant, passez le nom du champ de la table en deuxième argument : frm.set_query(champ, champ_table, fonction). Les arguments cdt et cdn identifient la ligne. Lisez la ligne avec locals[cdt][cdn].

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

Le sélecteur d'ajout multiple d'une grille appelle la même fonction, avec frm en quatrième argument.

Champ d'autocomplétion

Les champs de type Autocomplétion utilisent le même mécanisme. La fonction reçoit les mêmes quatre arguments et renvoie le même type de résultat.

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 : cur_frm désigne le dernier formulaire affiché, pas forcément celui du champ.
  • É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.