erpnext-client-script-guide

# 📖 ERPNext Client Script Guide

This guide explains the **structure** and **functions** available for Client Scripts in ERPNext (via Frappe Framework).

---

## 🚀 What is a Client Script?

A **Client Script** is a custom JavaScript file that runs in the browser to customize ERPNext DocType forms without modifying core code.

---

## 📂 How to Create a Client Script

1. Go to **Client Script** list in ERPNext (search in AwesomeBar).
2. Click **New**.
3. Select the **DocType** to customize.
4. Paste your JavaScript code in the **Script** field.
5. Save and reload the form.

---

## 🧩 Client Script Structure

```js
frappe.ui.form.on("Your DocType", {
  onload(frm) {
    // Runs when the form is loaded
  },
  refresh(frm) {
    // Runs every time form is refreshed
  },
  validate(frm) {
    // Runs before saving
  },
  before_save(frm) {
    // Runs just before saving
  },
  on_submit(frm) {
    // Runs after submission
  },
  fieldname(frm) {
    // Runs when the field value changes
  },
});
```

---

## 🔧 Common API Functions

| Function | Description |
|----------|-------------|
| `frm.set_value(field, value)` | Set a field value dynamically |
| `frm.set_df_property(field, property, value)` | Change field properties (e.g., make read-only, hide/show) |
| `frm.add_custom_button(label, handler)` | Add a custom button to the form |
| `msgprint("Message")` or `frappe.msgprint(__("Message"))` | Show popup alert |
| `cur_frm.add_fetch(link_field, source_field, target_field)` | Auto-fetch values from linked DocTypes |
| `frappe.call({...})` | Call server-side methods from client script |

---

## 📜 Example Snippets

### ✅ 1. Set a Field as Read-Only for Existing Documents

```js
frappe.ui.form.on("Task", {
  refresh(frm) {
    frm.set_df_property("title", "read_only", !frm.is_new());
  },
});
```

---

### ✅ 2. Validate a Field Before Saving

```js
frappe.ui.form.on("Task", {
  validate(frm) {
    if (frm.doc.start_date < get_today()) {
      frappe.msgprint("Start date cannot be in the past");
      frappe.validated = false;
    }
  },
});
```

---

### ✅ 3. Fetch Value from Linked DocType

```js
cur_frm.add_fetch("customer", "tax_id", "customer_tax_id");
```

---

### ✅ 4. Add Custom Button

```js
frappe.ui.form.on("Sales Order", {
  refresh(frm) {
    frm.add_custom_button("Ship Now", () => {
      frappe.call({
        method: "my_app.api.ship_order",
        args: { so: frm.doc.name },
        callback(r) {
          frappe.msgprint("Shipment created");
        },
      });
    });
  },
});
```

---

## 📋 Event Reference Table

| Event Name   | When It Runs |
|--------------|--------------|
| `onload`     | When the form is first loaded |
| `refresh`    | When the form is refreshed |
| `validate`   | Before saving |
| `before_save`| Just before saving |
| `on_submit`  | After submission |
| `fieldname`  | When a specific field changes |

---

## 📝 Template

```js
frappe.ui.form.on("Your DocType", {
  onload(frm) {
    // Setup logic
  },
  refresh(frm) {
    // UI adjustments
  },
  validate(frm) {
    // Validation logic
  },
  before_save(frm) {
    // Logic before saving
  },
  on_submit(frm) {
    // After submission logic
  },
  your_fieldname(frm) {
    // Field change reaction
  },
});
```

---

### ✅ Tips
- Always **clear browser cache** after saving a new script.
- Use **refresh event** to modify values after ERPNext auto-calculations.
- Keep code modular and clean for maintainability.

---

📌 **References:**  
- [ERPNext Client Script Docs](https://docs.frappe.io/framework/user/en/desk/scripting/client-script)  
- [ERPNext Community Scripts](https://github.com/frappe/erpnext/wiki/Community-Developed-Custom-Scripts)  

erpnext-docType-guide.md

📖 ERPNext DocType Guide

This guide explains what a DocType is, its structure, and how to create and configure DocTypes in ERPNext.

---

🚀 What is a DocType?

A DocType is the core data model in ERPNext. It defines the structure, behavior, and storage of records in the system. Every form in ERPNext is based on a DocType.

---

📂 How to Create a DocType

1. Go to DocType list in ERPNext (search in AwesomeBar).

2. Click New.

3. Fill in the basic details:

   • Name – Internal name of the DocType.
   • Module – The app/module where it belongs.
   • Custom – Check this if you are creating a custom DocType.

4. Add fields under the Fields table.

5. Save and reload the page.

---

🧩 DocType Structure

Property	Description
Name	Internal identifier for the DocType
Module	The module in which it is stored
Is Submittable	Allows records to be submitted after save
Is Child Table	Marks the DocType as a table for use in parent forms
Permissions	Controls which roles can Read, Write, Create, Submit, etc.

---

🔧 Field Types

Some common field types you can use:

Field Type	Purpose
Data	Single-line text
Text	Multi-line text
Date/Datetime	Stores date or date & time
Int/Float/Currency	Numeric values
Check	Checkbox (Yes/No)
Select	Dropdown options
Link	Link to another DocType
Table	Add a child table

---

📜 Example DocType Fields

Label	Fieldname	Fieldtype	Options
Customer	customer	Link	Customer
Start Date	start_date	Date
Description	description	Text
Amount	amount	Currency
Is Active	is_active	Check

---

📝 Permissions

Permissions define which roles can read, write, create, delete, submit, etc.

Role	Read	Write	Create	Delete	Submit
Sales User	✅	✅	✅
Accounts User	✅
System Manager	✅	✅	✅	✅	✅

---

📌 Best Practices

✅ Use naming series if you need auto-generated IDs (e.g., CUST-.YYYY.-).
✅ Keep fieldnames lowercase and without spaces (use underscores).
✅ Use Child Tables for line items or repeating records.
✅ Define permissions carefully to control access.

---

📌 References:

• ERPNext DocType Documentation

workflow-guild.md

📖 ERPNext Workflow Guide

This guide explains what a Workflow is, how to create one, and how to use it to manage document approval processes in ERPNext.

---

🚀 What is a Workflow?

A Workflow in ERPNext defines a sequence of approval states and transitions for a specific DocType. It is used to manage document approval, review, or custom status flow.

---

📂 How to Create a Workflow

1. Go to Workflow list in ERPNext (search in AwesomeBar).

2. Click New.

3. Enter details:

   • Workflow Name – A unique name.
   • Document Type – Select the DocType for which you are creating the workflow.
   • Is Active – Enable this to make the workflow functional.

4. Add States (statuses like Draft, Pending Approval, Approved, Rejected).

5. Add Transitions (rules for moving from one state to another).

6. Save.

---

🧩 Workflow Structure

Key Components

Component	Description
States	Different stages of the document (e.g., Draft, Approved)
Transitions	The actions to move between states
Permissions	Which roles can approve, reject, or edit

---

🔧 Workflow States

State Name	Doc Status	Update Field	Allow Edit for
Draft	0		All Users
Pending Approval	0		Approvers
Approved	1		None
Rejected	0		All Users

---

🔄 Workflow Transitions

Action	From State	To State	Allowed Role
Submit for Approval	Draft	Pending Approval	Employee
Approve	Pending Approval	Approved	Manager
Reject	Pending Approval	Rejected	Manager

---

📜 Example Use Case

Workflow for Leave Application

1. States:

   • Draft (default)
   • Pending Approval
   • Approved
   • Rejected

2. Transitions:

   • Employee submits -> Pending Approval
   • Manager approves -> Approved
   • Manager rejects -> Rejected

---

📝 Tips

✅ Assign roles carefully to avoid unauthorized approvals.
✅ Use Doc Status correctly:

• 0 → Draft
• 1 → Submitted
• 2 → Cancelled

✅ Combine workflows with notifications to inform users of approvals or rejections.

---

📌 References:

• ERPNext Workflow Documentation