What is a Client Script in Frappe?

A Client Script in Frappe v15 is a JavaScript-based customization tool used to modify the behavior of forms (DocTypes) on the client side.

It allows developers to:

• Trigger logic on form events
• Validate field inputs
• Dynamically update UI elements
• Interact with server-side methods

Client Scripts run in the browser and are linked to a specific DocType.

Why Use Client Script in ERPNext?

Client Scripts are used when you need real-time UI interaction without modifying core code.

Key Benefits:

• No core code changes (upgrade-safe)
• Instant UI updates
• Custom validations
• Improved user experience

How to Create a Client Script in Frappe v15?

Step-by-Step:

1. Go to Desk → Customization → Client Script
2. Click New
3. Select the DocType
4. Add your JavaScript code
5. Save and refresh the form

Basic Structure of Client Script

frappe.ui.form.on('DocType Name', {
event_name: function(frm) {
// your logic here
}
});
Example:
frappe.ui.form.on('Sales Order', {
validate: function(frm) {
if (!frm.doc.customer) {
frappe.msgprint('Customer is required');
}
}
});

What Are Common Form Events in Client Script?

Client Scripts work using predefined form events.

Frequently Used Events:

How to Trigger Field-Based Events?

You can run scripts when a specific field changes.

frappe.ui.form.on('Sales Order', {
customer: function(frm) {
frappe.msgprint('Customer Changed');
}
});

How to Modify Field Properties Dynamically?

Client Scripts allow dynamic UI control.

Example: Make Field Mandatory

frm.set_df_property('fieldname', 'reqd', 1);

Example: Hide Field

frm.toggle_display('fieldname', false);

Example: Set Field Value

frm.set_value('fieldname', 'value');

How to Call Server-Side Methods from Client Script?

Use frappe.call() to interact with backend Python methods.

frappe.call({
method: 'app.module.method_name',
args: {
key: value
},
callback: function(response) {
console.log(response.message);
}
});

Real-World Example: Auto Calculate Total

frappe.ui.form.on('Sales Order', {
validate: function(frm) {
let total = 0;
frm.doc.items.forEach(item => {
total += item.qty * item.rate;
});
frm.set_value('total_amount', total);
}
});

Advanced Usage in Frappe v15

1. Add Custom Buttons

frappe.ui.form.on('Sales Order', {
refresh: function(frm) {
frm.add_custom_button('Click Me', () => {
frappe.msgprint('Button Clicked');
});
}
});

2. Restrict Field Editing

frm.set_df_property('fieldname', 'read_only', 1);

3. Filter Link Fields

frm.set_query('customer', function() {
return {
filters: {
customer_group: 'Commercial'
}
};
});

Best Practices for Client Script

• Keep scripts lightweight and efficient
• Avoid heavy loops in UI events
• Use server calls only when necessary
• Follow naming conventions for clarity
• Test scripts in UAT before production

Troubleshooting Common Issues

Issue: Script Not Working

• Ensure correct DocType name
• Check browser console (F12)
• Clear cache and reload

Issue: Event Not Triggering

• Verify correct event name
• Ensure script is saved and enabled

Target Audience

• ERPNext Developers
• Frappe Developers
• Technical Consultants
• ERP Implementation Teams

Technical Prerequisites

• Basic JavaScript knowledge
• Understanding of DocTypes
• Familiarity with Frappe Desk

Industry Relevance

Client Scripts are widely used across:

• Manufacturing ERP
• Real Estate ERP
• Chemical Industry ERP
• Retail & Distribution

Official References

Frappe Docs (Client Script):

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

Frappe GitHub v15:

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

Conclusion

Frappe Client Script in Version 15 is a powerful way to customize ERPNext forms without altering core code. By leveraging form events, field manipulation, and API calls, developers can build highly dynamic and user-friendly applications.