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:

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

{fieldname}

Workflow 4: Cascading Link Filters

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

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

setup

Workflow 5: Calculated Fields (Child Table)

Goal: Calculate row amounts and document totals.

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:

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

Example — frappe.xcall:

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

Workflow 7: Custom Button Implementation

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

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:

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

   :

   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

set_query

setup

set_value

frm.set_value({a: 1, b: 2})

frm._cache_key

frappe.db.get_value

frappe.call

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.