Agent skill

frappe-impl-clientscripts

Use when implementing client-side form features in Frappe/ERPNext: field visibility, cascading filters, calculated fields, custom buttons, server calls, form validation, child table logic, debugging. Covers step-by-step workflows from Setup > Client Script through migration to custom app JS. Keywords: how to implement client script, form logic workflow, dynamic UI, calculate fields, frm.call, frappe.call, frappe.xcall, client script testing, field dependency, custom button.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/frappe-impl-clientscripts

Metadata

Additional technical details for this skill

author
OpenAEC-Foundation
version
2.0

SKILL.md

Client Scripts — Implementation Workflows

Step-by-step workflows for building client-side form features. For exact API syntax, see frappe-syntax-clientscripts.

Version: v14/v15/v16 | Note: v13 renamed "Custom Script" to "Client Script"

Quick Decision: Client or Server?

MUST the logic ALWAYS execute (imports, API, Data Import)?
├── YES → Server Script or Controller
└── NO  → What is the goal?
         ├── UI feedback / UX → Client Script
         ├── Show/hide fields → Client Script
         ├── Link filters → Client Script
         ├── Data validation → BOTH (client for UX, server for integrity)
         └── Calculations → Client for display, server for critical

Rule: ALWAYS use Client Scripts for UX. ALWAYS back critical logic with server-side validation.

Workflow 1: Create a Client Script via UI

  1. Navigate to Setup > Client Script (or type "New Client Script" in awesomebar)
  2. Select the target DocType
  3. ALWAYS set Enabled checkbox
  4. Write script using the frappe.ui.form.on pattern
  5. Save — script is active immediately (no restart needed)
  6. Open target DocType form → test behavior
  7. Open browser DevTools Console (F12) for debugging

When to migrate to custom app: ALWAYS migrate when the script exceeds 50 lines, needs version control, or must be deployed across environments.

Workflow 2: Choose the Right Event

WHAT DO YOU WANT?
├── Set link filters         → setup (once, earliest lifecycle)
├── Add custom buttons       → refresh (re-added after each render)
├── Show/hide fields         → refresh + {fieldname} (BOTH needed)
├── Validate before save     → validate (frappe.throw stops save)
├── Action after save        → after_save
├── Calculate on change      → {fieldname} handler
├── Child row added          → {tablename}_add
├── Child row removed        → {tablename}_remove
├── Child field changed      → Child DocType: {fieldname}
├── One-time init            → setup or onload
└── After full DOM render    → onload_post_render

See references/decision-tree.md for complete event timing matrix.

Workflow 3: Field Visibility Toggle

Goal: Show "delivery_date" only when "requires_delivery" is checked.

Step 1: Implement BOTH refresh and fieldname events:

javascript
frappe.ui.form.on('Sales Order', {
    refresh(frm) {
        frm.trigger('requires_delivery'); // Set initial state
    },
    requires_delivery(frm) {
        frm.toggle_display('delivery_date', frm.doc.requires_delivery);
        frm.toggle_reqd('delivery_date', frm.doc.requires_delivery);
    }
});

Why both? refresh sets state on form load. {fieldname} responds to user interaction. NEVER use only one — the form will show wrong state on load or on change.

Workflow 4: Cascading Link Filters

Goal: Filter "city" based on selected "country".

javascript
frappe.ui.form.on('Customer', {
    setup(frm) {
        // ALWAYS set filters in setup — ensures consistency
        frm.set_query('city', () => ({
            filters: { country: frm.doc.country || '' }
        }));
    },
    country(frm) {
        frm.set_value('city', ''); // ALWAYS clear dependent field
    }
});

Rule: ALWAYS put set_query in setup. ALWAYS clear child fields when parent changes.

Workflow 5: Calculated Fields (Child Table)

Goal: Calculate row amounts and document totals.

javascript
frappe.ui.form.on('Invoice Item', {
    qty(frm, cdt, cdn) { calculate_row(frm, cdt, cdn); },
    rate(frm, cdt, cdn) { calculate_row(frm, cdt, cdn); },
    amount(frm) { calculate_totals(frm); }
});

frappe.ui.form.on('Invoice', {
    items_remove(frm) { calculate_totals(frm); }
});

function calculate_row(frm, cdt, cdn) {
    let row = frappe.get_doc(cdt, cdn);
    frappe.model.set_value(cdt, cdn, 'amount',
        flt(row.qty) * flt(row.rate));
}

function calculate_totals(frm) {
    let total = (frm.doc.items || []).reduce(
        (sum, row) => sum + flt(row.amount), 0);
    frm.set_value('grand_total', flt(total, 2));
}

Rules:

  • ALWAYS use flt() for numeric operations (handles null/undefined)
  • ALWAYS handle items_remove — totals must recalculate on row deletion
  • NEVER call refresh_field after set_value — it triggers automatically

Workflow 6: Server Calls — Which Method to Use

NEED TO CALL THE SERVER?
├── Fetch a single value?
│   └── frappe.db.get_value(doctype, name, fields)
│       Returns: Promise — lightweight, no whitelist needed
│
├── Call a document's controller method?
│   └── frm.call(method, args)
│       Requires: @frappe.whitelist() on controller method
│       Auto-includes: doctype, docname, doc context
│
├── Call a standalone whitelisted function?
│   └── frappe.call({method: 'dotted.path', args: {}})
│       Requires: @frappe.whitelist() decorator
│       Returns: Promise with r.message
│
└── Need Promise-only (no callback)?
    └── frappe.xcall('dotted.path', args)
        Same as frappe.call but returns clean Promise

Example — frm.call:

javascript
frm.call('calculate_taxes').then(r => {
    frm.reload_doc();  // Refresh after server-side changes
});

Example — frappe.xcall:

javascript
let result = await frappe.xcall(
    'myapp.api.check_credit', { customer: frm.doc.customer });

Workflow 7: Custom Button Implementation

javascript
frappe.ui.form.on('Sales Order', {
    refresh(frm) {
        // ALWAYS check conditions before adding buttons
        if (!frm.is_new() && frm.doc.docstatus === 1) {
            frm.add_custom_button(__('Create Invoice'), () => {
                create_invoice(frm);
            }, __('Create'));  // Group label
        }
    }
});

Rules:

  • ALWAYS add buttons in refresh — they are cleared on each render
  • ALWAYS check frm.is_new() — buttons on unsaved docs cause errors
  • ALWAYS wrap button labels in __() for translation
  • NEVER add buttons in setup or onload — UI not ready

Workflow 8: Async Validation with Server Check

javascript
frappe.ui.form.on('Sales Order', {
    async validate(frm) {
        if (!frm.doc.customer || !frm.doc.grand_total) return;

        let r = await frappe.call({
            method: 'myapp.api.check_credit',
            args: {
                customer: frm.doc.customer,
                amount: frm.doc.grand_total
            }
        });

        if (r.message && !r.message.allowed) {
            frappe.throw(__('Credit limit exceeded. Available: {0}',
                [r.message.available]));
        }
    }
});

Rules:

  • ALWAYS use async/await for server calls in validate
  • ALWAYS use frappe.throw() to stop save — msgprint does NOT stop it
  • NEVER put slow server calls in validate without user expectation

Workflow 9: Debugging in Browser

  1. Open F12 DevTools > Console
  2. Add console.log(frm.doc) in your event handler
  3. Use cur_frm in Console to inspect current form state
  4. Check Network tab for failed frappe.call requests
  5. Use frappe.ui.form.handlers to see registered event handlers

Debug pattern:

javascript
frappe.ui.form.on('MyDocType', {
    my_field(frm) {
        console.log('Field changed:', frm.doc.my_field);
        // ... actual logic
    }
});

Workflow 10: Migrate Client Script to Custom App

  1. Create JS file: myapp/myapp/public/js/sales_order.js
  2. Move script content to the file (keep frappe.ui.form.on wrapper)
  3. Register in hooks.py:
    python
    doctype_js = {
    "Sales Order": "public/js/sales_order.js"
}
  4. Run bench build (or bench watch for development)
  5. Delete the Client Script document from Setup
  6. Test on the form — behavior must be identical

ALWAYS migrate when: version control needed, multi-environment deployment, script > 50 lines, team collaboration required.

Performance Rules

Rule Why
set_query in setup only Prevents re-registration on every refresh
Batch set_value calls frm.set_value({a: 1, b: 2}) — one update, not two
Cache server responses Store in frm._cache_key to avoid repeat calls
NEVER query in loops Fetch all data once, build lookup map
Use frappe.db.get_value Lighter than frappe.call for simple lookups

Related Skills

  • frappe-syntax-clientscripts — Exact API syntax and method signatures
  • frappe-errors-clientscripts — Error handling and common pitfalls
  • frappe-syntax-whitelisted — Server methods callable from client
  • frappe-core-database — frappe.db.* client-side API
  • frappe-impl-serverscripts — When to move logic server-side

See references/decision-tree.md for event selection. See references/workflows.md for extended patterns. See references/examples.md for 10+ complete examples.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results