sbknext/forge-frappe-skill

frappe-client-scripting

Customize Frappe desk forms and lists with client scripts — frappe.ui.form.on handlers, field events, setquery link filters, setdfproperty, custom buttons, frappe.call, and list view settings.

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/sbknext/forge-frappe-skill --skill frappe-client-scripting

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

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

javascript
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

javascript
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:

python
@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

javascript
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

javascript
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

javascript
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 matters

Desk 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_render

For 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 method

Performance: 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_value for child rows; mutating locals directly 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_js hook, not as DB "Client Script" records, for versioning.
  • NEVER rely on frappe.msgprint alone to abort saves — use frappe.throw in validate.
  • NEVER add action buttons only in setup/onload — refresh rebuilds 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
dallo stesso repository

Altri Skills

Tutti gli Skills
sbknext
Community

frappe-app-development

Scaffold, architect, and build production-grade custom Frappe/ERPNext apps. Covers app structure, DocType design, hooks.py configuration, background jobs, service layers, REST APIs, permissions, and testing. Use when creating a new Frappe app, adding a module, setting up scheduler events, implementing docevents, writing whitelisted APIs, or debugging Frappe-specific issues. Trigger on: "create Frappe app", "new DocType", "add a hook", "background job", "frappe.enqueue", "whitelist API", "custom

Installazioni / 1h
1
GitHub Stars
18
Aggiornato
7 giu
sbknext
Community

frappe-database-orm

Query and mutate data in Frappe safely — getdoc/getall/getlist, frappe.db.getvalue/setvalue, parameterized frappe.db.sql, Query Builder (frappe.qb), transactions, bulk ops, and performance. Use when reading or writing data, optimizing slow queries, or avoiding SQL injection. Trigger on: "frappe.db.sql", "frappe.getall", "query builder", "frappe.qb", "bulk update", "N+1", "db transaction", "getvalue setvalue".

Installazioni / 1h
1
GitHub Stars
18
Aggiornato
7 giu
sbknext
Community

frappe-report-development

Build Frappe reports — Query Reports (SQL), Script Reports (Python), filters, columns, charts, formatters, and report permissions. Use when creating analytics/listing reports, dashboards, or exportable views in Frappe/ERPNext. Trigger on: "query report", "script report", "Frappe report", "report filters", "report chart", "columns formatter", "report builder".

Installazioni / 1h
1
GitHub Stars
18
Aggiornato
7 giu
sbknext
Community

frappe-testing

Write and run tests for Frappe/ERPNext apps — FrappeTestCase, test records, fixtures, mocking, permission tests, running with bench run-tests, and CI. Use when adding test coverage, doing TDD on a DocType or API, or setting up a test pipeline. Trigger on: "Frappe test", "FrappeTestCase", "bench run-tests", "unit test DocType", "test fixtures", "TDD frappe".

Installazioni / 1h
1
GitHub Stars
18
Aggiornato
7 giu