Creating Dynamic, Custom Form Scripts with Empress's Client Script Feature

Developers
1

Introduction

Empress’s Client Script feature allows developers to create dynamic, custom Form Scripts that execute directly on a user’s browser. This gives you the flexibility to customize your forms using any JavaScript APIs, Empress’ API, and any other JS or CSS libraries you’ve customized your Desk with.

This guide will take you through the process of creating a client script, its features, and examples of how to use it effectively.

Introduction: Why Client Script?

With the Client Script feature, you can create dynamic, custom form scripts that execute directly on a user’s browser. This bypasses the need for server-side processing, resulting in faster response times and a smoother user experience. This also allows for a higher degree of customization, as you can use any JavaScript APIs and libraries that you’ve customized your Desk with.

Note: In Version 13, Custom Script was renamed to Client Script.

How to create a Client Script

To create a Client Script:

  1. Ensure your role is System Manager to add or edit Client Scripts.
  2. Type “New Client Script” in the awesomebar and hit enter to create a new Client Script document.
  3. Select the DocType whose form you wish to customize.
  4. Update the script using the preset template and save your changes.
  5. Head over to the DocType you’ve customized to see the changes.

Features of Client Script

Client Scripts are less restrictive than Server Scripts. This is because the frontend APIs are secure by design. You can utilize all of JavaScript APIs, along with Empress’ and any other JS or CSS library you might’ve customized Desk with.

But remember, validations you add through Client Script will only be applied while using the standard form view accessible through the browser. If you want those to be applied through API or System Console access too, use Server Scripts.

Examples of Client Script usage

Custom validation

Add additional form validations while creating or updating a document from Empress’ 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');
    }
});

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');

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());
    }
});

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;
    }
});

In conclusion, the Client Script feature is a powerful tool that allows developers to create dynamic, custom form scripts executed directly on a user’s browser. This not only enhances the user experience but also allows for a higher degree of customization and control over forms in Empress.