Implementing and Understanding DocType in the Empress Framework

Developers
1

Introduction

In the Empress framework, DocType serves as the blueprint for the Model, defining properties and behavior. By understanding and adeptly implementing DocTypes, developers can significantly enhance the functionality and customization of their applications. Let’s delve into the technicalities of DocType, mirroring the sophistication and clarity of Apple’s guide style.

Enable Developer Mode

Before creating DocTypes, it is necessary to enable developer mode on your bench. This allows boilerplate creation when forming doctypes and aids in tracking them into version control with your app.

To activate developer mode, open your terminal and quit the bench server, if running. From the frappe-bench directory, execute the following commands:

$ bench set-config -g developer_mode true
$ bench start

Creating a DocType

In Desk, navigate to the DocType List. The list contains DocTypes packaged with the framework, those belonging to installed Empress apps, and custom ones specific to each site.

To create a new DocType, click on ‘New’. We will create a DocType named Article with the following steps:

  1. Enter Name as ‘Article’
  2. Select ‘Library Management’ in Module
  3. Add the following fields in the Fields table:
    1. Article Name (Data, Mandatory)
    2. Image (Attach Image)
    3. Author (Data)
    4. Description (Text Editor)
    5. ISBN (Data)
    6. Status (Select) - Enter two options: Issued and Available
    7. Publisher (Data)

After configuring the fields, click on ‘Save’. Navigate to the Article List by clicking Go to Article List on the top right of the form. As the table currently has no records, the list will be blank.

To populate the list, we need to clear the Desk cache. Click on the Settings dropdown on the right side of the navbar and click Reload.

Use the New button to create a new Article document. Fill in the form details and click ‘Save’. Your first Article document is now created!

Understanding the DocType Creation Process

When a DocType is created, several actions are triggered:

1. Database Table Creation

A database table named tabArticle is created with the fields specified in the fields table. Fields specified in Title Case are automatically converted to snake case and used as column names in the table. Standard fields like name, creation, modified, modified_by are created for all doctypes, with name being the primary key column.

2. Desk Views Creation

Several views for the DocType are created. The Article List is the list view that displays the records from the database table. The Form view is used for creating a new document or viewing an existing one.

3. Form Layout

The layout of fields in the form is determined by the order in which they were arranged in the Fields table.

4. Boilerplate Code Generation

Several files are generated in your app, including:

  • article.json - JSON file defining the doctype attributes
  • article.js - Client-side controller for the Form view
  • article.py - Python controller for Article
  • test_article.py - Python Unit Test boilerplate for writing tests

Remember to uncheck the ‘Custom?’ checkbox in the doctype configuration to ensure these files are generated.

By creating a DocType, you define not only the table and column names, but also how it will be rendered in various views in the Desk. Good job following this guide! Stay tuned for more insights on Empress’ features and functionalities.