Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/sbknext/forge-frappe-skill --skill frappe-client-scriptingAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
Frappe Client Scripting
Client scripts run in the browser on desk forms/lists. Use them for UX; never for security (enforce on the server).
Form events
frappe.ui.form.on("Sales Order", {
refresh(frm) {
if (frm.doc.docstatus === 1) {
frm.add_custom_button("Sync Now", () => run_sync(frm));
}
},
customer(frm) { // fires when 'customer' changes
frm.set_value("currency", "");
},
validate(frm) {
if (frm.doc.grand_total < 0) {
frappe.throw(__("Total cannot be negative"));
}
},
});
// Child table events
frappe.ui.form.on("Sales Order Item", {
qty(frm, cdt, cdn) {
const row = locals[cdt][cdn];
frappe.model.set_value(cdt, cdn, "amount", row.qty * row.rate);
},
});Dynamic link filters
frm.set_query("item_code", "items", () => ({
filters: { is_sales_item: 1, disabled: 0 },
}));
// Server-side query method (for complex filters)
frm.set_query("item_code", "items", () => ({
query: "myapp.queries.item_query",
filters: { is_sales_item: 1 },
}));Server query methods must be @frappe.whitelist() and decorated with @frappe.validate_and_sanitize_search_inputs to prevent SQL injection:
@frappe.whitelist()
@frappe.validate_and_sanitize_search_inputs
def item_query(doctype, txt, searchfield, start, page_len, filters):
return frappe.db.sql("""SELECT name FROM `tabItem`
WHERE name LIKE %(txt)s LIMIT %(page_len)s""",
{"txt": f"%{txt}%", "page_len": page_len})Field control at runtime
frm.set_df_property("discount", "hidden", frm.doc.status !== "Draft");
frm.toggle_reqd("reason", frm.doc.status === "Rejected");
frm.set_value("approved_by", frappe.session.user);Calling the server
frappe.call({
method: "myapp.api.order_summary",
args: { customer: frm.doc.customer },
freeze: true,
callback: (r) => {
if (!r.exc) frappe.msgprint(`${r.message.count} orders`);
},
});List view settings
frappe.listview_settings["Sales Order"] = {
add_fields: ["status"],
get_indicator(doc) {
return doc.status === "Closed"
? [__("Closed"), "green", "status,=,Closed"]
: [__("Open"), "orange", "status,=,Open"];
},
};Client vs server
MUST the logic ALWAYS run (imports, API, bulk import, bench console)?
├── YES → controller validate / hooks / Server Script
└── NO → client script for UX; pair validation on server when integrity mattersDesk Client Script records vs app `doctype_js`: use DB Client Scripts for prototypes; ship production logic in git-tracked JS via hooks.py when scripts exceed ~50 lines or need CI. (Legacy name Custom Script = same Desk DocType.)
Deep reference: skills/frappe/script-types-decision-tree.md.
Choose the right form event
Need → handler
├── Link filters → setup (once; avoid re-registering in refresh)
├── Custom buttons → refresh
├── Show/hide / mandatory toggles → refresh AND {fieldname}
├── Block bad saves → validate (frappe.throw)
├── After save side effects → after_save
├── Recalculate on field edits → {fieldname}
├── Grid row lifecycle → {table}_add / {table}_remove / child handlers
└── Needs fully rendered DOM → onload_post_renderFor visibility toggles, call frm.trigger('fieldname') from refresh to sync initial state.
Server calls from the form
├── Single field lookup → frappe.db.get_value (promise)
├── Method on current document → frm.call (controller @frappe.whitelist)
├── Any whitelisted function → frappe.call / frappe.xcall
└── Avoid server calls in tight loops → batch via one whitelist methodPerformance: register set_query only in setup; batch frm.set_value({...}); use flt() for arithmetic; recalculate totals on {table}_remove, not only field edits.
Rules
- Client scripts are UX only — duplicate every guard in a server
validate/permission check. - Use
__("...")for all user-facing strings (translatable). - Prefer
frappe.model.set_valuefor child rows; mutatinglocalsdirectly won't refresh the grid. - Don't put secrets or privileged logic in client scripts — they're shipped to the browser.
- Ship reusable logic as an app JS file via
doctype_jshook, not as DB "Client Script" records, for versioning. - NEVER rely on
frappe.msgprintalone to abort saves — usefrappe.throwinvalidate. - NEVER add action buttons only in
setup/onload—refreshrebuilds UI chrome. - Clear dependent Link fields when parent filters change:
frm.set_value('child_link', '').
From Frappe docs
- Server-side link query override (
set_query+ custom method): https://docs.frappe.io/framework/user/en/guides/app-development/overriding-link-query-by-custom-script
Source (upstream decision trees)
- https://github.com/vyogotech/frappe-apps-manager/blob/main/.cursor/skills/frappe-client-script-logic/SKILL.md