Agent-Skills.md

Agent Skills: Frappe Client Script Generator

Generate JavaScript client-side form scripts for Frappe DocTypes. Use when creating form customizations, field validations, custom buttons, or client-side logic for Frappe/ERPNext forms.

UncategorizedID: vyogotech/frappe-apps-manager/frappe-client-script-generator

Repository

vyogotech/frappe-apps-manager
vyogotechLicense: MIT
31

Install this agent skill to your local

pnpm dlx add-skill https://github.com/vyogotech/frappe-apps-manager/tree/HEAD/.cursor/skills/frappe-client-script-generator

Skill Files

Browse the full folder contents for frappe-client-script-generator.

Download Skill

Loading file tree…

.cursor/skills/frappe-client-script-generator/SKILL.md

Skill Metadata

Name
frappe-client-script-generator
Description
Generate JavaScript client-side form scripts for Frappe DocTypes. Use when creating form customizations, field validations, custom buttons, or client-side logic for Frappe/ERPNext forms.

Frappe Client Script Generator

Generate production-ready JavaScript form scripts for Frappe DocTypes with proper event handlers, validations, and custom functionality.

When to Use This Skill

Claude should invoke this skill when:

  • User wants to add client-side form customizations
  • User needs field validations or calculations
  • User requests custom buttons or actions on forms
  • User wants to filter or fetch data dynamically
  • User mentions form scripts, client scripts, or JavaScript for DocTypes
  • User wants to show/hide fields conditionally
  • User needs to set field values based on other fields

Capabilities

1. Form Event Handlers

Generate event handlers for DocType forms following Frappe patterns from core apps.

Refresh Event (runs when form loads):

// Pattern from: erpnext/accounts/doctype/sales_invoice/sales_invoice.js
frappe.ui.form.on('Sales Invoice', {
    refresh: function(frm) {
        // Add custom buttons
        if (frm.doc.docstatus === 1) {
            frm.add_custom_button(__('Create Payment'), function() {
                frm.events.make_payment_entry(frm);
            });
        }

        // Set field properties
        frm.set_df_property('customer', 'reqd', 1);

        // Show/hide fields
        frm.toggle_display('discount_section', frm.doc.apply_discount);
    }
});

Setup Event (runs once when form is created):

// Pattern from: erpnext/stock/doctype/stock_entry/stock_entry.js
frappe.ui.form.on('Stock Entry', {
    setup: function(frm) {
        // Set query filters for Link fields
        frm.set_query('item_code', 'items', function() {
            return {
                filters: {
                    'is_stock_item': 1,
                    'has_serial_no': 0
                }
            };
        });
    }
});

Onload Event (runs on form load, before refresh):

// Pattern from: erpnext/accounts/doctype/payment_entry/payment_entry.js
frappe.ui.form.on('Payment Entry', {
    onload: function(frm) {
        if (frm.is_new()) {
            frm.set_value('posting_date', frappe.datetime.get_today());
        }
    }
});

2. Field Change Handlers

Single Field Change:

// Pattern from: erpnext/selling/doctype/sales_order/sales_order.js
frappe.ui.form.on('Sales Order', {
    customer: function(frm) {
        if (frm.doc.customer) {
            // Fetch customer details
            frappe.db.get_value('Customer', frm.doc.customer, 'customer_group')
                .then(r => {
                    if (r.message) {
                        frm.set_value('customer_group', r.message.customer_group);
                    }
                });
        }
    }
});

Multiple Field Dependencies:

// Pattern from: erpnext/accounts/doctype/sales_invoice/sales_invoice.js
frappe.ui.form.on('Sales Invoice', {
    customer: function(frm) {
        frm.events.set_dynamic_field_label(frm);
    },
    currency: function(frm) {
        frm.events.set_dynamic_field_label(frm);
    },
    set_dynamic_field_label: function(frm) {
        if (frm.doc.currency) {
            frm.set_currency_labels(['total', 'grand_total'], frm.doc.currency);
        }
    }
});

3. Child Table (Grid) Events

Child Table Row Events:

// Pattern from: erpnext/accounts/doctype/sales_invoice/sales_invoice_item.js
frappe.ui.form.on('Sales Invoice Item', {
    item_code: function(frm, cdt, cdn) {
        let row = locals[cdt][cdn];
        if (row.item_code) {
            frappe.call({
                method: 'erpnext.stock.get_item_details.get_item_details',
                args: {
                    item_code: row.item_code,
                    company: frm.doc.company
                },
                callback: function(r) {
                    if (r.message) {
                        frappe.model.set_value(cdt, cdn, 'rate', r.message.price_list_rate);
                        frappe.model.set_value(cdt, cdn, 'uom', r.message.stock_uom);
                    }
                }
            });
        }
    },

    qty: function(frm, cdt, cdn) {
        frm.events.calculate_totals(frm, cdt, cdn);
    },

    rate: function(frm, cdt, cdn) {
        frm.events.calculate_totals(frm, cdt, cdn);
    }
});

Grid Operations:

// Pattern from: erpnext/stock/doctype/stock_entry/stock_entry.js
frappe.ui.form.on('Stock Entry', {
    items_add: function(frm, cdt, cdn) {
        let row = locals[cdt][cdn];
        row.s_warehouse = frm.doc.from_warehouse;
        row.t_warehouse = frm.doc.to_warehouse;
    },

    items_remove: function(frm) {
        frm.events.calculate_totals(frm);
    }
});

4. Custom Buttons and Actions

Standard Button Patterns:

// Pattern from: erpnext/accounts/doctype/sales_invoice/sales_invoice.js
frappe.ui.form.on('Sales Invoice', {
    refresh: function(frm) {
        if (frm.doc.docstatus === 1 && frm.doc.outstanding_amount > 0) {
            frm.add_custom_button(__('Payment'), function() {
                frm.events.make_payment_entry(frm);
            }, __('Create'));
        }

        // Add custom button in toolbar
        if (frm.doc.docstatus === 0) {
            frm.add_custom_button(__('Get Items from Sales Order'), function() {
                erpnext.utils.map_current_doc({
                    method: 'erpnext.selling.doctype.sales_order.sales_order.make_sales_invoice',
                    source_doctype: 'Sales Order',
                    target: frm,
                    setters: {
                        customer: frm.doc.customer || undefined
                    },
                    get_query_filters: {
                        docstatus: 1,
                        status: ['not in', ['Closed', 'On Hold']]
                    }
                });
            });
        }
    },

    make_payment_entry: function(frm) {
        return frappe.call({
            method: 'erpnext.accounts.doctype.payment_entry.payment_entry.get_payment_entry',
            args: {
                dt: frm.doc.doctype,
                dn: frm.doc.name
            },
            callback: function(r) {
                let doc = frappe.model.sync(r.message);
                frappe.set_route('Form', doc[0].doctype, doc[0].name);
            }
        });
    }
});

5. Data Fetching and API Calls

Fetch from Database:

// Pattern from: erpnext/stock/doctype/item/item.js
frappe.ui.form.on('Item', {
    item_group: function(frm) {
        if (frm.doc.item_group) {
            frappe.db.get_value('Item Group', frm.doc.item_group, 'default_warehouse')
                .then(r => {
                    if (r.message && r.message.default_warehouse) {
                        frm.set_value('default_warehouse', r.message.default_warehouse);
                    }
                });
        }
    }
});

Server Method Calls:

// Pattern from: erpnext/accounts/doctype/payment_entry/payment_entry.js
frappe.ui.form.on('Payment Entry', {
    party: function(frm) {
        if (frm.doc.party_type && frm.doc.party) {
            frappe.call({
                method: 'erpnext.accounts.party.get_party_details',
                args: {
                    party: frm.doc.party,
                    party_type: frm.doc.party_type,
                    company: frm.doc.company
                },
                callback: function(r) {
                    if (r.message) {
                        frm.set_value('party_name', r.message.party_name);
                        frm.set_value('party_account', r.message.party_account);
                    }
                }
            });
        }
    }
});

6. Form Validations

Before Save Validation:

// Pattern from: erpnext/accounts/doctype/sales_invoice/sales_invoice.js
frappe.ui.form.on('Sales Invoice', {
    validate: function(frm) {
        // Validate posting date
        if (frm.doc.posting_date > frappe.datetime.get_today()) {
            frappe.throw(__('Posting Date cannot be future date'));
        }

        // Validate items
        if (!frm.doc.items || frm.doc.items.length === 0) {
            frappe.throw(__('Please add at least one item'));
        }

        // Validate total
        if (frm.doc.grand_total <= 0) {
            frappe.throw(__('Grand Total must be greater than 0'));
        }
    }
});

Before Submit Validation:

// Pattern from: erpnext/stock/doctype/stock_entry/stock_entry.js
frappe.ui.form.on('Stock Entry', {
    before_submit: function(frm) {
        let has_qty = false;
        frm.doc.items.forEach(function(item) {
            if (item.qty > 0) {
                has_qty = true;
            }
        });

        if (!has_qty) {
            frappe.throw(__('Please enter quantity for at least one item'));
        }
    }
});

7. Conditional Field Display

Show/Hide Fields:

// Pattern from: erpnext/accounts/doctype/payment_entry/payment_entry.js
frappe.ui.form.on('Payment Entry', {
    payment_type: function(frm) {
        frm.events.toggle_fields(frm);
    },

    toggle_fields: function(frm) {
        let is_receive = (frm.doc.payment_type === 'Receive');
        let is_pay = (frm.doc.payment_type === 'Pay');

        frm.toggle_display('paid_from', is_pay);
        frm.toggle_display('paid_to', is_receive);
        frm.toggle_reqd('paid_from', is_pay);
        frm.toggle_reqd('paid_to', is_receive);
    }
});

Field Property Changes:

// Pattern from: erpnext/selling/doctype/sales_order/sales_order.js
frappe.ui.form.on('Sales Order', {
    refresh: function(frm) {
        // Make field read-only based on condition
        frm.set_df_property('customer', 'read_only', frm.doc.docstatus === 1);

        // Change field label
        frm.set_df_property('delivery_date', 'label',
            frm.doc.order_type === 'Sales' ? __('Delivery Date') : __('Delivery By'));

        // Set field as mandatory
        frm.toggle_reqd('delivery_date', frm.doc.order_type === 'Sales');
    }
});

8. Calculations and Totals

Calculate Child Table Totals:

// Pattern from: erpnext/accounts/doctype/sales_invoice/sales_invoice.js
frappe.ui.form.on('Sales Invoice', {
    calculate_totals: function(frm) {
        let total = 0;
        frm.doc.items.forEach(function(item) {
            item.amount = flt(item.qty) * flt(item.rate);
            total += item.amount;
        });
        frm.set_value('total', total);

        // Calculate tax and grand total
        let tax_amount = flt(total * frm.doc.tax_rate / 100);
        frm.set_value('total_taxes_and_charges', tax_amount);
        frm.set_value('grand_total', total + tax_amount);
    }
});

frappe.ui.form.on('Sales Invoice Item', {
    qty: function(frm, cdt, cdn) {
        let item = locals[cdt][cdn];
        frappe.model.set_value(cdt, cdn, 'amount',
            flt(item.qty) * flt(item.rate));
        frm.events.calculate_totals(frm);
    },

    rate: function(frm, cdt, cdn) {
        let item = locals[cdt][cdn];
        frappe.model.set_value(cdt, cdn, 'amount',
            flt(item.qty) * flt(item.rate));
        frm.events.calculate_totals(frm);
    }
});

9. Link Field Filters (set_query)

Filter Link Field Options:

// Pattern from: erpnext/stock/doctype/stock_entry/stock_entry.js
frappe.ui.form.on('Stock Entry', {
    setup: function(frm) {
        // Filter items based on item group
        frm.set_query('item_code', 'items', function(doc, cdt, cdn) {
            return {
                filters: {
                    'item_group': ['in', ['Raw Material', 'Sub Assemblies']],
                    'is_stock_item': 1
                }
            };
        });

        // Dynamic filters based on doc values
        frm.set_query('warehouse', function() {
            return {
                filters: {
                    'company': frm.doc.company,
                    'is_group': 0
                }
            };
        });
    }
});

Complex Query Filters:

// Pattern from: erpnext/accounts/doctype/payment_entry/payment_entry.js
frappe.ui.form.on('Payment Entry', {
    setup: function(frm) {
        frm.set_query('party', function() {
            let party_type = frm.doc.party_type;
            if (party_type === 'Customer') {
                return {query: 'erpnext.controllers.queries.customer_query'};
            } else if (party_type === 'Supplier') {
                return {query: 'erpnext.controllers.queries.supplier_query'};
            }
        });

        frm.set_query('reference_doctype', 'references', function() {
            let doctypes = [];
            if (frm.doc.party_type === 'Customer') {
                doctypes = ['Sales Invoice', 'Sales Order'];
            } else if (frm.doc.party_type === 'Supplier') {
                doctypes = ['Purchase Invoice', 'Purchase Order'];
            }
            return {
                filters: {
                    'name': ['in', doctypes]
                }
            };
        });
    }
});

10. Dialogs and Prompts

Create Custom Dialog:

// Pattern from: erpnext/stock/doctype/stock_entry/stock_entry.js
frappe.ui.form.on('Stock Entry', {
    get_items: function(frm) {
        let dialog = new frappe.ui.Dialog({
            title: __('Get Items'),
            fields: [
                {
                    fieldtype: 'Link',
                    label: __('Warehouse'),
                    fieldname: 'warehouse',
                    options: 'Warehouse',
                    reqd: 1,
                    get_query: function() {
                        return {
                            filters: {
                                'company': frm.doc.company
                            }
                        };
                    }
                },
                {
                    fieldtype: 'Link',
                    label: __('Item Group'),
                    fieldname: 'item_group',
                    options: 'Item Group'
                }
            ],
            primary_action_label: __('Get Items'),
            primary_action: function(values) {
                frappe.call({
                    method: 'get_items',
                    doc: frm.doc,
                    args: values,
                    callback: function(r) {
                        dialog.hide();
                        frm.refresh_field('items');
                    }
                });
            }
        });
        dialog.show();
    }
});

References

Frappe Core Client Script Examples (Primary Reference)

Learn from Frappe Framework:

  • Frappe Form Scripts: https://github.com/frappe/frappe/tree/develop/frappe/desk/doctype
    • form/form.js - Core form functionality
    • todo/todo.js - Simple form script example
  • Frappe UI Components: https://github.com/frappe/frappe/tree/develop/frappe/public/js/frappe/ui

ERPNext Client Script Examples:

  • Sales Invoice: https://github.com/frappe/erpnext/blob/develop/erpnext/accounts/doctype/sales_invoice/sales_invoice.js
  • Purchase Order: https://github.com/frappe/erpnext/blob/develop/erpnext/buying/doctype/purchase_order/purchase_order.js
  • Stock Entry: https://github.com/frappe/erpnext/blob/develop/erpnext/stock/doctype/stock_entry/stock_entry.js
  • Payment Entry: https://github.com/frappe/erpnext/blob/develop/erpnext/accounts/doctype/payment_entry/payment_entry.js
  • Item: https://github.com/frappe/erpnext/blob/develop/erpnext/stock/doctype/item/item.js

Official Documentation (Secondary Reference)

  • Form Scripts: https://frappeframework.com/docs/user/en/desk/scripting/form-scripts
  • Client API: https://frappeframework.com/docs/user/en/api/form
  • frappe.ui.form.on: https://frappeframework.com/docs/user/en/api/form#frappeuiformon

Best Practices

  1. Event Handler Organization: Group related handlers together
  2. Reusable Functions: Extract common logic into reusable methods
  3. Null Checks: Always validate data before using it
  4. Async Operations: Use callbacks for database and API calls
  5. User Feedback: Use frappe.show_alert() for success/error messages
  6. Performance: Debounce expensive operations in change handlers
  7. Translation: Use __() for translatable strings
  8. Error Handling: Wrap risky operations in try-catch
  9. Child Tables: Use locals[cdt][cdn] to access child table rows
  10. Field Updates: Use frappe.model.set_value() for child table fields

File Output Format

Generated client scripts should be saved at:

apps/<app_name>/<module>/doctype/<doctype_name>/<doctype_name>.js

Always include:

  • Clear comments explaining functionality
  • Proper indentation (4 spaces or tab as per project)
  • Event handler grouping
  • Error handling where appropriate
  • Translation wrappers for user-facing strings

Common Patterns Summary

  • refresh: Add buttons, set field properties
  • setup: One-time setup, set query filters
  • onload: Initialize values for new docs
  • validate: Pre-save validations
  • before_submit: Pre-submission checks
  • field_name: Handle field changes
  • child_table_field: Handle child table field changes
  • items_add/remove: Handle row additions/removals

Decision Tree & Reference

Source skill: frappe-syntax-clientscripts (Frappe Claude Skill Package workspace). Summarizes event timing, API cheatsheet, handler choice, and hard rules—supplements the ERPNext-pattern examples above, does not replace them.

Quick Reference (syntax cheatsheet)

| Action | Code | |--------|------| | Set value | frm.set_value('field', value) or frm.set_value({ ... }) | | Get value | frm.doc.fieldname | | Hide field | frm.toggle_display('field', false) | | Mandatory | frm.toggle_reqd('field', true) | | Read-only | frm.toggle_enable('field', false) | | DF property | frm.set_df_property('field', 'options', [...]) | | Filter Link | frm.set_query('field', () => ({ filters: {} })) | | Server | frappe.call({ method, args }) | | Doc method | frm.call('method_name', { args }) | | Block save | frappe.throw(__('...')) in validate | | Child row | frm.add_child('table', { ... }); frm.refresh_field('table') | | Alert | frappe.show_alert({ message: __('...'), indicator: 'green' }) |

Event execution order (condensed)

  • Load: setup → onload → refresh → onload_post_render
  • Save: validate → before_save → [server] → after_save → refresh
  • Submit: validate → before_submit → [server] → on_submit → refresh
  • Cancel: before_cancel → [server] → after_cancel → refresh
  • Reload / frm.refresh: before_load → onload → refresh → onload_post_render

Form event reference table

| Event | When | Params | Typical use | |-------|------|--------|--------------| | setup | Once per form instance | (frm) | set_query, one-time config | | onload | Loaded, before render | (frm) | Defaults, preprocessing | | refresh | After load/reload/save | (frm) | Buttons, visibility | | onload_post_render | DOM ready | (frm) | DOM-dependent work | | validate | Before save/submit | (frm) | Block with frappe.throw() | | before_save | After validate | (frm) | Last-minute values | | after_save | After save | (frm) | Follow-up UI/notifications | | before_submit | Before submit | (frm) | Pre-submit checks | | on_submit | After submit | (frm) | Post-submit actions | | before_cancel / after_cancel | Around cancel | (frm) | Cancel hooks | | before_workflow_action / after_workflow_action | Workflow | (frm) | Workflow hooks | | timeline_refresh | Timeline rendered | (frm) | Timeline customization |

Field change handlers: use exact fieldname as event key—they run on UI change, frm.set_value(), and child frappe.model.set_value(); they do not run after raw frm.doc.field = … assignments.

Child DocType handlers: register on the child DocType (frappe.ui.form.on('Sales Order Item', { … })). Grid lifecycle: {table}_add, {table}_remove, {table}_move, {table}_before_remove (v14+).

setup vs refresh

| Aspect | setup | refresh | |--------|---------|-----------| | Frequency | Once | Every load/reload/save | | Use for | set_query, formatters | Buttons, dynamic UI |

Event decision tree (syntax)

What do you need?
├── One-time setup (queries, formatters)?
│   └── ALWAYS use setup — once per form instance
├── Show/hide, buttons, refresh UI each load?
│   └── ALWAYS use refresh
├── Validate before save?
│   └── ALWAYS use validate — frappe.throw() to block
├── Change values immediately before save?
│   └── Use before_save
├── After persisted save?
│   └── Use after_save
├── React to field change?
│   └── Use fieldname handler
├── Workflow transition?
│   └── before_workflow_action / after_workflow_action
└── After full DOM render?
    └── onload_post_render — NEVER manipulate fields via bare jQuery

ALWAYS / NEVER (syntax-critical)

  1. ALWAYS call frm.refresh_field('table') after child table mutations (add_child, clear_table, bulk row edits) so the grid stays in sync.
  2. NEVER assign frm.doc.field = value on the parent form—use frm.set_value() so triggers, dirty state, and UI update run.
  3. ALWAYS wrap user-facing strings in __().
  4. ALWAYS define set_query in setup, not refresh (callbacks still read fresh frm.doc).
  5. NEVER use async: false on frappe.call (locks the UI).
  6. ALWAYS guard custom action buttons (frm.is_new(), docstatus, business fields).
  7. NEVER drive field visibility or enablement by raw jQuery—use frm.toggle_display, frm.toggle_enable, frm.set_df_property.
  8. NEVER keep form state in global variables—stash on frm (e.g. frm._cache_key).
  9. ALWAYS check r.message before using frappe.call results unless you rely on upstream guarantees.
  10. In validate, ALWAYS block saves with frappe.throw(); with async/server checks use async validate + await—NEVER rely on callbacks that finish after validate returns.

Async validation: NEVER fire an un-awaited frappe.call inside validate—saving continues before your callback resolves; use async/await instead.