Desk Scripting in Frappe Framework v15

What Is Desk Scripting in Frappe?

Desk Scripting in Frappe Framework v15 allows developers and administrators to customize how forms behave inside the Frappe Desk using JavaScript. It enables dynamic validations, UI changes, field logic, and server interactions without modifying core ERPNext code.
Desk scripting is implemented primarily through Client Scripts and Custom Scripts.

Why Use Desk Scripting in ERPNext?

Desk scripting makes ERPNext flexible and adaptable to business-specific workflows.

Key Benefits

• Customize form behavior without core changes
• Add validations and automation
• Improve user experience and data accuracy
• Rapid customization with minimal risk

It is the most commonly used customization mechanism in ERPNext.

Who Uses Desk Scripting?

Target Audience

• ERPNext Developers
• ERP Administrators
• Functional Consultants
• Custom App Developers

Technical Prerequisites

• Frappe Framework v15
• JavaScript (ES6 basics)
• Understanding of DocTypes and fields

How Does Desk Scripting Work in Frappe v15?

Desk scripting hooks into form lifecycle events and UI triggers. Scripts run in the browser and interact with the form object (frm) to control fields, buttons, and actions.

Core Components

• Client Script DocType
• Form Events (refresh, validate, onload)
• frm JavaScript API

Module: Desk
Verified Source (v15): frappe/public/js/frappe/form

What Are Client Scripts?

A Client Script is a JavaScript snippet linked to a specific DocType that runs in the Desk.

Client Script Types

• Form Scripts – Triggered on form events
• List Scripts – Customize list views

Client Scripts are stored as records and can be edited without deployment.

How to Create a Client Script in Frappe v15?

Step-by-Step

• Open Awesome Bar → Client Script
• Click New
• Select DocType
• Choose Script Type (Form/List)
• Write JavaScript logic
• Save

The script is immediately applied to the Desk UI.

Common Form Events Used in Desk Scripting

These events allow fine-grained control of form behavior.

Example: Basic Desk Script (Frappe v15)

frappe.ui.form.on('Sales Invoice', {
validate(frm) {
if (frm.doc.grand_total <= 0) {
frappe.throw('Grand Total must be greater than zero');
}
}
});

What this does:

Prevents saving a Sales Invoice if the total amount is zero or negative.

How to Modify Fields Dynamically?

frm.set_df_property('discount_amount', 'read_only', 1);
frm.toggle_display('remarks', false);

Desk scripting can:

• Show or hide fields
• Make fields mandatory or read-only
• Set default values dynamically

How to Call Server Logic from Desk Scripts?

Desk scripts commonly use server calls for validations or data fetching.

frappe.call({
method: "my_app.api.get_rate",
args: { item: frm.doc.item_code },
callback(r) {
frm.set_value('rate', r.message);
}
});

This bridges frontend behavior with backend logic.

Real-World ERPNext Use Cases

Industry Relevance

• Sales: Pricing rules and validations
• Manufacturing: BOM checks and automation
• Finance: Tax calculations
• HR: Attendance and leave validations

Desk scripting enables industry-specific workflows.

Best Practices for Desk Scripting

• Keep scripts short and readable
• Avoid heavy business logic in JavaScript
• Use server calls for critical validations
• Comment scripts clearly
• Test scripts in staging before production

Common Issues and Troubleshooting

Script Not Executing

• Verify DocType name
• Check script type (Form/List)
• Clear browser cache

Conflicting Behavior

• Review multiple Client Scripts
• Avoid duplicate event handlers

Advanced Desk Scripting Concepts

Client Scripts vs Custom Apps

Use Client Scripts for UI and form-level logic.

Integration Patterns

Desk scripting integrates with:

• Server Calls
• Form Tours
• Attachments
• Print Formats
• Workflows

It acts as the interaction layer of ERPNext.

Official References (Verified)

Desk Scripting Documentation (v15):

https://docs.frappe.io/framework/user/en/desk/scripting

Frappe GitHub (v15):

https://github.com/frappe/frappe/tree/version-15