Understanding the Lifecycle of a Frappe DocType

Here’s the general order of file execution for the lifecycle of a DocType in Frappe, from loading the form to saving, submitting, and other operations. This sequence includes both client-side and server-side events.

1. DocType Metadata (JSON)

• File: your_app_name/your_app_name/your_app_name/doctype/your_doctype_name.json
• Execution: The DocType metadata is read first to determine the structure, fields, and permissions when loading the form. This happens both on the client and server side whenever the form is accessed.

2. JavaScript Client-Side Code (if applicable)

• File: your_app_name/your_app_name/your_app_name/doctype/your_doctype_name.js
• Execution: After the metadata is loaded, any client-side JavaScript (if defined) is executed. This handles actions like:
  • Form loading (frappe.ui.form.on('Your DocType', 'refresh', function() {}))
  • Client-side validations (validate event)
  • Actions based on user interaction (e.g., button clicks, field changes)

  This runs immediately in the browser when the form is loaded and during any client-side interactions.

3. Form Rendering

• Files:
  • your_doctype_name.html (if any custom HTML)
  • your_doctype_name.css (if any custom CSS)
• Execution: If you have custom HTML or CSS for the form, these files are applied after the form metadata and JavaScript are loaded, defining how the form looks and behaves on the client side.

4. Server-Side Python Code (DocType Model)

• File: your_app_name/your_app_name/your_app_name/doctype/your_doctype_name.py
• Execution: After client-side interactions, when data is saved or submitted, server-side logic is executed:
  • before_save: Triggered before saving the document.
  • before_insert: Triggered before the document is inserted into the database.
  • validate: Triggered during form validation before saving. It ensures all fields and business logic constraints are met.
  • on_update: Triggered after the document has been saved (updated).
  • on_submit: Triggered when the document is submitted (if it has a submit action).
  • on_cancel: Triggered when the document is canceled (if applicable).
  • on_trash: Triggered when the document is deleted.

  These Python methods provide hooks for adding custom business logic that runs server-side during different stages of the document’s lifecycle.

5. DocType Dashboard (Optional)

• File: your_app_name/your_app_name/your_app_name/doctype/your_doctype_name_dashboard.py
• Execution: If you have a custom dashboard for your DocType, this file will be executed to render specific metrics, links, or KPIs related to your document. This usually appears in the client after saving or interacting with the document.

6. Background Tasks / Workflow Events

• Execution: If any background tasks, scheduled jobs, or workflows are tied to the DocType, they are triggered at specific points (e.g., after submission, based on workflow rules). This might involve event hooks outside the direct scope of the DocType file itself, typically set in the hooks.py file of the app.

7. Automated Tests (if any)

• File: your_app_name/your_app_name/your_app_name/doctype/test_your_doctype_name.py
• Execution: This file is executed when you run tests for your DocType via the Frappe testing framework (bench run-tests). It is not part of the runtime lifecycle but ensures the functionality of your DocType is working as expected.