doctype-patterns

What this skill does

# Frappe DocType Patterns

Comprehensive guide to creating and configuring DocTypes in Frappe Framework, the core building block for all Frappe applications.

## When to Use This Skill

- Creating new DocTypes
- Adding or modifying fields on DocTypes
- Designing data models and relationships
- Setting up naming patterns and autoname
- Configuring permissions and workflows
- Creating child tables
- Working with Virtual or Single DocTypes

## DocType Directory Structure

When you create a DocType named "My Custom DocType" in module "My Module":

```
my_app/
└── my_module/
    └── doctype/
        └── my_custom_doctype/
            ├── my_custom_doctype.json      # DocType definition
            ├── my_custom_doctype.py        # Python controller
            ├── my_custom_doctype.js        # Client script
            ├── test_my_custom_doctype.py   # Test file
            └── __init__.py
```

## DocType JSON Structure

```json
{
  "name": "My Custom DocType",
  "module": "My Module",
  "doctype": "DocType",
  "engine": "InnoDB",
  "field_order": ["field1", "field2"],
  "fields": [
    {
      "fieldname": "field1",
      "fieldtype": "Data",
      "label": "Field 1",
      "reqd": 1
    }
  ],
  "permissions": [
    {
      "role": "System Manager",
      "read": 1,
      "write": 1,
      "create": 1,
      "delete": 1
    }
  ],
  "autoname": "naming_series:",
  "naming_rule": "By \"Naming Series\" field",
  "is_submittable": 0,
  "istable": 0,
  "issingle": 0,
  "track_changes": 1,
  "sort_field": "modified",
  "sort_order": "DESC"
}
```

## Field Types Reference

### Text Fields
| Type | Description | Use Case |
|------|-------------|----------|
| `Data` | Single line text (140 chars) | Names, codes, short text |
| `Small Text` | Multi-line text | Short descriptions |
| `Text` | Multi-line text (unlimited) | Long descriptions |
| `Text Editor` | Rich text with formatting | Content, notes |
| `Code` | Syntax-highlighted code | Python, JS, JSON |
| `HTML Editor` | WYSIWYG HTML | Email templates |
| `Markdown Editor` | Markdown input | Documentation |
| `Password` | Masked input | Secrets (stored encrypted) |

### Numeric Fields
| Type | Description | Use Case |
|------|-------------|----------|
| `Int` | Integer | Counts, quantities |
| `Float` | Decimal number | Measurements |
| `Currency` | Money with precision | Prices, amounts |
| `Percent` | 0-100 percentage | Discounts, rates |
| `Rating` | Star rating (0-1) | Reviews, scores |

### Date/Time Fields
| Type | Description | Use Case |
|------|-------------|----------|
| `Date` | Date only | Birth dates, due dates |
| `Datetime` | Date and time | Timestamps |
| `Time` | Time only | Schedules |
| `Duration` | Time duration | Task duration |

### Selection Fields
| Type | Description | Use Case |
|------|-------------|----------|
| `Select` | Dropdown options | Status, type |
| `Check` | Boolean checkbox | Flags, toggles |
| `Autocomplete` | Text with suggestions | Tags |

### Link Fields
| Type | Description | Use Case |
|------|-------------|----------|
| `Link` | Reference to another DocType | Foreign key relationship |
| `Dynamic Link` | Reference based on another field | Polymorphic links |
| `Table` | Child table (1-to-many) | Line items, details |
| `Table MultiSelect` | Many-to-many via link | Multiple selections |

### Special Fields
| Type | Description | Use Case |
|------|-------------|----------|
| `Attach` | Single file attachment | Documents |
| `Attach Image` | Image with preview | Photos, logos |
| `Image` | Display image from URL field | Gallery |
| `Signature` | Signature pad | Approvals |
| `Geolocation` | Map coordinates | Locations |
| `Barcode` | Barcode/QR display | Inventory |
| `JSON` | JSON data | Configuration |

### Layout Fields
| Type | Description | Use Case |
|------|-------------|----------|
| `Section Break` | Horizontal section divider | Form organization |
| `Column Break` | Vertical column divider | Multi-column layout |
| `Tab Break` | Tab navigation | Large forms |
| `HTML` | Static HTML content | Instructions, headers |
| `Heading` | Section heading | Visual separation |
| `Button` | Clickable button | Actions |

## Field Options

### Common Field Properties
```json
{
  "fieldname": "customer",
  "fieldtype": "Link",
  "label": "Customer",
  "options": "Customer",
  "reqd": 1,
  "unique": 0,
  "in_list_view": 1,
  "in_standard_filter": 1,
  "in_global_search": 1,
  "bold": 1,
  "read_only": 0,
  "hidden": 0,
  "print_hide": 0,
  "no_copy": 0,
  "allow_in_quick_entry": 1,
  "translatable": 0,
  "default": "",
  "description": "Select the customer",
  "depends_on": "eval:doc.is_customer",
  "mandatory_depends_on": "eval:doc.status=='Active'",
  "read_only_depends_on": "eval:doc.docstatus==1"
}
```

### Link Field Options
```json
{
  "fieldname": "customer",
  "fieldtype": "Link",
  "options": "Customer",
  "filters": {
    "disabled": 0,
    "customer_type": "Company"
  },
  "ignore_user_permissions": 0
}
```

### Select Field Options
```json
{
  "fieldname": "status",
  "fieldtype": "Select",
  "options": "\nDraft\nPending\nApproved\nRejected",
  "default": "Draft"
}
```

### Dynamic Link
```json
{
  "fieldname": "party_type",
  "fieldtype": "Link",
  "options": "DocType"
},
{
  "fieldname": "party",
  "fieldtype": "Dynamic Link",
  "options": "party_type"
}
```

## Naming Patterns (autoname)

### Naming Series
```json
{
  "autoname": "naming_series:",
  "naming_rule": "By \"Naming Series\" field"
}
```
Add a naming_series field:
```json
{
  "fieldname": "naming_series",
  "fieldtype": "Select",
  "options": "INV-.YYYY.-\nINV-.MM.-.YYYY.-",
  "default": "INV-.YYYY.-"
}
```

### Field-Based Naming
```json
{
  "autoname": "field:customer_code",
  "naming_rule": "By fieldname"
}
```

### Expression-Based
```json
{
  "autoname": "format:{customer_type}-{###}",
  "naming_rule": "Expression"
}
```

### Hash/Random
```json
{
  "autoname": "hash",
  "naming_rule": "Random"
}
```

### Prompt (Manual)
```json
{
  "autoname": "Prompt",
  "naming_rule": "Set by user"
}
```

## Controller Lifecycle Hooks

```python
# my_doctype.py
import frappe
from frappe.model.document import Document

class MyDocType(Document):
    # ===== BEFORE DATABASE OPERATIONS =====

    def autoname(self):
        """Set the document name before saving"""
        self.name = f"{self.prefix}-{frappe.generate_hash()[:8]}"

    def before_naming(self):
        """Called before autoname, can modify naming logic"""
        pass

    def validate(self):
        """Validate data before save (called on insert and update)"""
        self.validate_dates()
        self.calculate_totals()

    def before_validate(self):
        """Called before validate"""
        pass

    def before_save(self):
        """Called before document is saved to database"""
        self.modified_by_script = True

    def before_insert(self):
        """Called before new document is inserted"""
        self.set_defaults()

    # ===== AFTER DATABASE OPERATIONS =====

    def after_insert(self):
        """Called after new document is inserted"""
        self.notify_users()

    def on_update(self):
        """Called after document is saved (insert or update)"""
        self.update_related_docs()

    def after_save(self):
        """Called after on_update, always runs"""
        pass

    def on_change(self):
        """Called when document changes in database"""
        pass

    # ===== SUBMISSION WORKFLOW =====

    def before_submit(self):
        """Called before document is submitted"""
        self.validate_for_submit()

    def on_submit(self):
        """Called after document is submitted"""
        self.create_gl_entries()

    def before_cancel(self):
        """Called before document is cancelled"""
        self.validate_cancellation()

    def on_cancel(self):
        """Called after document is cancelled"""
        self.reverse_gl_entries()

    def on_update_after_submit(self):
        """Called when submitted do