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.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/sbknext/forge-frappe-skill --skill frappe-client-scripting

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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
같은 저장소의 Skills

더 많은 Skills

모든 Skills
sbknext
커뮤니티

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

1시간 설치 수
1
GitHub Stars
18
업데이트
6월 7일
sbknext
커뮤니티

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".

1시간 설치 수
1
GitHub Stars
18
업데이트
6월 7일
sbknext
커뮤니티

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".

1시간 설치 수
1
GitHub Stars
18
업데이트
6월 7일
sbknext
커뮤니티

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".

1시간 설치 수
1
GitHub Stars
18
업데이트
6월 7일