Frappe Framework
Scripts de formulaire
Un fichier {doctype}.js ou un Client Script de site. frm enregistre, soumet, ajoute un bouton et appelle une méthode en liste blanche.
Où écrire
Un DocType neuf reçoit {doctype}.js. frappe.ui.form.on(doctype, { événement }). L’exemple todo.js, dans frappe/desk/doctype/todo/todo.js, sur refresh, ajoute un bouton vers le formulaire référencé si reference_type et reference_name sont remplis. Le script propre au site est un Client Script : Home, Customization, Client Script, New. Le partage entre sites passe par une application. Voir Script client.
Le script d’une table enfant est dans le fichier du parent. Pour Quotation Item, item_code(frm, cdt, cdn) lit la ligne avec frappe.get_doc(cdt, cdn). cdt est le DocType enfant, cdn le nom de la ligne.
Événements
Le handler reçoit frm.
| Événement | Moment |
|---|---|
| setup | Une fois, à la création du formulaire |
| before_load | Avant le chargement |
| onload | Chargé, avant le rendu |
| refresh | Chargé et rendu |
| onload_post_render | Après le rendu |
| validate | Avant before_save |
| before_save / after_save | Autour de l’enregistrement |
| before_submit / on_submit | Autour de la soumission |
| before_cancel / after_cancel | Autour de l’annulation |
| before_discard / after_discard | Autour de l’abandon |
| timeline_refresh | Après la chronologie |
{fieldname}_on_form_rendered | Une ligne ouverte en formulaire dans une table |
{fieldname} | La valeur change |
| get_email_recipient_filters | Filtres du dialogue e-mail, pour recipients, cc ou bcc, liés au DocType Contact |
| get_email_recipients | Adresses par défaut pour le même champ |
Enfant, avec cdt et cdn : before_{fieldname}_remove, {fieldname}_add, {fieldname}_remove, {fieldname}_move, form_render. L’exemple Dynamic Link, le texte écrit « DoctType », écoute links_add et affiche qu’une ligne a été ajoutée, avec un emoji. Depuis la v16, les trois premiers événements valent aussi pour Table MultiSelect.
frm
set_value un champ ou un objet, et renvoie une promesse. Cela déclenche le changement. refresh reprend le serveur et enchaîne before_load, onload, refresh, timeline_refresh, onload_post_render. save déclenche validate, before_save, after_save, timeline_refresh et refresh. save('Submit'), save('Cancel') et save('Update') lancent l’action correspondante. Tous renvoient une promesse.
enable_save et disable_save selon que frappe.user_roles contient Custom Role. email_doc ouvre le dialogue, avec un message optionnel qui interpole customer_name. reload_doc recharge puis refresh. refresh_field rafraîchit le champ et ses dépendances.
is_dirty est vrai si des valeurs ne sont pas enregistrées. L’alerte d’exemple demande d’enregistrer avant une pièce jointe. dirty pose l’indicateur Not Saved. L’exemple écrit browser_data depuis navigator.appVersion, marque sale, puis enregistre. Sans dirty, un toast dit « No changes in document ». is_new est vrai tant que le document n’est pas enregistré.
set_intro(message, color). Couleurs : blue, red, orange, green, yellow. Défaut blue.
Les boutons reprennent l’API Page. add_custom_button(libellé, action) ou un troisième argument de groupe, par exemple Set Status qui met status à Closed. change_custom_button_type(libellé, groupe, type) : primary sans groupe (null), danger dans le groupe. remove_custom_button et clear_custom_buttons.
set_df_property change une propriété et rafraîchit : fieldtype Text, options Open et Closed, reqd 1, read_only 1. toggle_enable rend modifiable si la condition est vraie. L’exemple passe vrai quand l’utilisateur a System Manager, pour status et priority. Le commentaire dit l’inverse en lecture seule sans ce rôle. toggle_reqd et toggle_display prennent un champ ou une liste.
set_query filtre un Link. L’appeler tôt, dans setup ou onload. Territoire India, ou ['in', ['India', 'Nepal', 'Japan']]. Pour item_code dans la table items, le groupe Products. Une méthode serveur : query en chemin pointé. Signature custom_query(doctype, txt, searchfield, start, page_len, filters). La phrase publiée dit « Just the set ». Le filtre de lien côté serveur est aussi dans Surcharger la requête d’un champ Link.
add_child('items', { item_code, qty }) puis refresh_field. frm.call exige @frappe.whitelist. L’exemple get_linked_doc lève si le lié manque et que throw_if_missing est vrai, sinon le renvoie. Le client lit r.message. frm.trigger lance un événement, par exemple set_mandatory_fields depuis refresh.
get_selected renvoie les lignes cochées : clé le champ table, valeur les noms. L’exemple a items et taxes.
frm.ignore_doctypes_on_cancel_all, posé dans onload, est un tableau de DocTypes à ne pas annuler avec le document. L’appel frappe.ui.form.on publié ne ferme pas la parenthèse.
Point d’attention
set_query trop tard ne filtre pas la liste. save sans dirty n’enregistre pas et affiche le toast. frm.call sans liste blanche n’est pas joignable.