Personnaliser les requêtes de liens et d'autocomplétion
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 :
| Argument | Description |
|---|---|
doc | Le document du formulaire (frm.doc). Dans une table enfant, c'est aussi le document parent. |
cdt | Le type de document du champ. Dans une table enfant, c'est le type de la ligne. |
cdn | Le nom du document. Dans une table enfant, c'est le nom de la ligne. |
frm | Le 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_frmdé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.