Client Script
A Client Script lets you dynamically define a custom Form Script that is executed on a user's browser. If you choose to utilize non standard tools or libraries, make sure to test them on different browsers to ensure compatibility across your userbase.
In Version 13, Custom Script was renamed to Client Script
1. How to create a Client Script
To create a Client Script
-
To add/edit Client Script, ensure your role is System Manager.
-
Type "New Client Script" in the awesomebar and hit enter to create a new Client Script document.
-
Select the DocType whose form you wish to customize.
-
Update the script using the preset template and save.
-
Head over to the DocType you've customized and see the changes.
2. Features
As compared to the restrictive nature of Server Scripts, everything is fair game in Client Scripts. This is because the frontend APIs are secure by design. You can utilize all of JavaScript APIs, along with Frappe's and any other JS or CSS library you might've customized Desk with.
The validations you add through Client Script will only be applied while using the standard form view accessible through the browser. In case you wish for those to be applied through API or System Console access too, use Server Scripts .
3. Examples
3.1 Custom validation
Add additional form validations while creating or updating a document from Frappe's standard form view.
// additional validation on Task dates
frappe.ui.form.on('Task', 'validate', function(frm) {
if (frm.doc.from_date < get_today()) {
msgprint('You can not select past date in From Date');
}
});
3.2 Fetching values on field updates
Fetch
local_tax_no
on changing value of the
customer
field.
cur_frm.add_fetch('customer', 'local_tax_no', 'local_tax_no');
3.3 Customize field properties
Make a field
ibsn
read only after creating the document.
// make a field read-only after saving
frappe.ui.form.on('Task', {
refresh: function(frm) {
frm.set_df_property('ibsn', 'read_only', !frm.is_new());
}
});
3.4 Customize field properties
Calculate incentives on a Sales Invoice form on save.
// calculate sales incentive
frappe.ui.form.on('Sales Invoice', {
validate: function(frm) {
// calculate incentives for each person on the deal
total_incentive = 0
$.each(frm.doc.sales_team, function(i, d) {
// calculate incentive
let incentive_percent = 2;
if(frm.doc.base_grand_total > 400) incentive_percent = 4;
// actual incentive
d.incentives = flt(frm.doc.base_grand_total) * incentive_percent / 100;
total_incentive += flt(d.incentives)
});
frm.doc.total_incentive = total_incentive;
}
});
3.5 Filter email recipients
You can restrict the available emails via a Client Script . Every form can specify what email addresses should be selectable. This reduces the cognitive load for the user and avoids sending emails to wrong recipients.
CommunicationComposer
(the email dialog) will check if there is a
Client Script
supplying filters for the "recipients", "cc" and "bcc" fields. For example, if a
Quotation
should only show email addresses linked to the recipient of the
Quotation
, we can add the following script:
frappe.ui.form.on("Quotation", {
get_email_recipient_filters: function (frm, field) {
// field can be "recipients", "cc" or "bcc"
if (field === "recipients") {
return [
[
"Dynamic Link",
"link_doctype",
"=",
frm.doc.quotation_to
],
[
"Dynamic Link",
"link_name",
"=",
frm.doc.party_name
],
];
}
},
// ...
};
The filters are referring to the Contact DocType and it's Links child table.
Even with filters, it remains possible to paste arbitrary recipients.
3.6 Set default email recipients
In standard processes like Sales Order -> Delivery Note -> Sales Invoice , the email recipients are often pre-defined. For example, this could be done in advance by the account manager.
You can set default email recipients via a Client Script . Every form can programmatically supply it's own default recipients.
CommunicationComposer
(the email dialog) will check if there is a
Client Script
supplying default recipients. For example, if your
Quotation
DocType contains a field named
BCC
(
"custom_bcc"
), you can add the following
Client Script
to use it as default BCC in the email dialog:
frappe.ui.form.on("Quotation", {
get_email_recipients: function (frm, field) {
// field can be "recipients", "cc" or "bcc"
if (field === "bcc") {
return [frm.doc.custom_bcc]
}
},
// ...
};