What is DocType in Frappe and How to Create a New One

In the world of Frappe App Development, Frappe framework has garnered significant attention, especially for building applications. Central to the Frappe framework is the concept of DocType, short for Document Type. DocType serves as the cornerstone of the Frappe ecosystem, defining the structure and behavior of documents within the system. In simpler terms, "DocTypes are the building blocks of data, representing various entities or business objects in Frappe applications."

A DocType is similar to a database table, but it comes with additional features and functionality, such as validation, permissions, and methods. Each DocType corresponds to a unique document, and documents of the same DocType share the same structure and fields.

Here are the main components that make up a DocType:

Key Components of a DocType

1. 1. Fields: At the heart of every DocType are its fields. These fields represent the data attributes of the document. Each field can have its own data type, default value, and additional properties like mandatory, read-only, or hidden. For instance, a "Customer" DocType may have fields like "Customer Name," "Contact Information," and "Credit Limit."

      1. Methods: DocTypes can define custom methods written in Python, providing powerful tools to implement specific business logic and behavior. For example, you can create a method to calculate the total amount based on the quantity and unit price of items in an invoice.

      2. Permissions: Security and access control are crucial aspects of any application. DocTypes come with built-in permissions, allowing administrators to grant or restrict access to specific roles or users. This ensures that sensitive data remains secure and confidential.

      3. Validations: To ensure data integrity and correctness, DocTypes support field validations. You can define rules that must be satisfied before saving data into a field. For instance, a "Date of Birth" field could have a validation to ensure the user enters a valid date.

      4. Links: In Frappe, DocTypes can establish relationships with other DocTypes through links. This enables data association and allows you to create meaningful connections between different entities within the system. For example, you could link a "Sales Order" to a "Customer" to keep track of customer-specific sales.

      5. Print Format: DocTypes offer the flexibility to define custom print formats, dictating how a document should appear when printed or exported to PDF. This feature helps maintain brand consistency and enables users to generate professional-looking documents.

Creating a New DocType

To harness the full potential of Frappe and tailor it to meet specific business needs, developers can create new DocTypes. Here's a step-by-step guide on how to create a new DocType:

1. Enable Developer Mode: First, access the Developer Mode in your Frappe/ERPNext instance. This mode grants you access to all the tools necessary for creating and customizing DocTypes.

2. Navigate to DocType List: Once in Developer Mode, head to the "List" module and search for "DocType."

3. Create a New DocType: Click on the "New" button to initiate the creation of a new DocType. You will be presented with a form to fill in essential details.

4. Provide Basic Information: In the form, specify a unique name for the DocType, which will serve as its identifier within the system. Also, select the appropriate module in which you want the DocType to reside.

5. Define Fields: Under the "Fields" section, add the necessary fields for your DocType. Assign data types and other properties to each field according to your requirements.

6. Add Custom Methods: If your DocType requires specific behaviors beyond the standard functionalities, define Python methods under the "Methods" section.

7. Set Permissions: Establish access control by defining permissions for the DocType based on user roles.

8. Apply Validations: Ensure data integrity by setting up field validations that adhere to the data constraints you wish to enforce.

9. Save and Create: Once you have provided all the relevant details, click on "Save" to create the new DocType.

10. Reload or Restart: To activate the changes, you may need to reload or restart your Frappe/ERPNext instance.

Creating a New DocType By Example.

While in Desk, navigate to the DocType List using the Awesomebar. This list will include DocTypes bundled with the framework, those that are a part of the installed Frappe apps and custom ones, which you can create specific to each site.

The first doctype we will create is Article. To create it, click on New.

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 (Type Issued, hit enter, then type Available)

   7. Publisher (Data)

Refer the following GIF to check how it should be done:

After adding the fields, click on Save.

You will see a Go to Article List button at the top right of the form. Click on it to go to the Article List. Here you will see a blank list with no records because the table has no records.

Let's create some records. But before that, we need to clear the Desk cache. Click on the Settings dropdown on the right side of the navbar and click on Reload.

Now, you should see the New button. Click on it and you will see the Form view of the Article doctype. Fill in the form and click on Save. You have created your first Article document. Go back to the list view and you should see one record.

What happened when you created the Article DocType?

1. Database Table

A database table with the name tabArticle was created with the fields we specified in the fields table. You can confirm this by checking it from the MariaDB console

    $ bench --site library.test mariadb
    Welcome to the MariaDB monitor.  Commands end with ; or \g.
    Your MariaDB connection id is 2445938
    Server version: 10.4.13-MariaDB Homebrew

    Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

    Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

    MariaDB [_ad03fa1a016ca1c4]> desc tabArticle;
    +--------------+--------------+------+-----+-----------+-------+
    | Field        | Type         | Null | Key | Default   | Extra |
    +--------------+--------------+------+-----+-----------+-------+
    | name         | varchar(140) | NO   | PRI | NULL      |       |
    | creation     | datetime(6)  | YES  |     | NULL      |       |
    | modified     | datetime(6)  | YES  | MUL | NULL      |       |
    | modified_by  | varchar(140) | YES  |     | NULL      |       |
    | owner        | varchar(140) | YES  |     | NULL      |       |
    | docstatus    | int(1)       | NO   |     | 0         |       |
    | parent       | varchar(140) | YES  | MUL | NULL      |       |
    | parentfield  | varchar(140) | YES  |     | NULL      |       |
    | parenttype   | varchar(140) | YES  |     | NULL      |       |
    | idx          | int(8)       | NO   |     | 0         |       |
    | article_name | varchar(140) | YES  |     | NULL      |       |
    | image        | text         | YES  |     | NULL      |       |
    | author       | varchar(140) | YES  |     | NULL      |       |
    | description  | longtext     | YES  |     | NULL      |       |
    | isbn         | varchar(140) | YES  |     | NULL      |       |
    | status       | varchar(140) | YES  |     | Available |       |
    | publisher    | varchar(140) | YES  |     | NULL      |       |
    | _user_tags   | text         | YES  |     | NULL      |       |
    | _comments    | text         | YES  |     | NULL      |       |
    | _assign      | text         | YES  |     | NULL      |       |
    | _liked_by    | text         | YES  |     | NULL      |       |
    +--------------+--------------+------+-----+-----------+-------+
    21 rows in set (0.002 sec)

    MariaDB [_ad03fa1a016ca1c4]>

The fields we specified in Title Case were converted to snake case automatically, and are used as the column names in the table. For e.g., article_name, image, author , and description.

However, many other fields were created like name, creation, modified, modified_by . These are standard fields created for all doctypes. name is the primary key column.

If you created a record with the Form, you can also run a standard select query to get the rows.

    MariaDB [_ad03fa1a016ca1c4]> select * from tabArticle;
    +------------+----------------------------+----------------------------+---------------+---------------+-----------+--------+-------------+------------+-----+-----------------------------+--
    | name       | creation                   | modified                   | modified_by   | owner         | docstatus | parent | parentfield | parenttype | idx | article_name                | i
    +------------+----------------------------+----------------------------+---------------+---------------+-----------+--------+-------------+------------+-----+-----------------------------+--
    | bd514646b9 | 2020-10-10 16:24:43.033457 | 2020-10-10 16:24:43.033457 | Administrator | Administrator |         0 | NULL   | NULL        | NULL       |   0 | The Girl with all the Gifts | N
    +------------+----------------------------+----------------------------+---------------+---------------+-----------+--------+-------------+------------+-----+-----------------------------+--

    MariaDB [_ad03fa1a016ca1c4]>

2. Desk Views

There are a number of views that were also created for our DocType. The Article List is the list view that shows the records from the database table. The Form view is the view that is shown when you want to create a new document or view an existing one.

3. Form Layout

If you notice, the layout of fields in the form is according to how you ordered them in the Fields table. For e.g., Article Name is the first field followed by Image which is followed by Author. In later parts of the tutorial we will learn how to customize this further.

4. Boilerplate code

---

NOTE

Make sure you uncheck the 'Custom?' checkbox in the doctype configuration. Otherwise the files discussed below won't be generated. An explaination for this is given here

---

If you look at the changes in your app, you should find a number of files that were created. Go to your terminal and from the frappe-bench directory run the following commands.

    $ cd apps/library_management
    $ git status -u
    On branch master
    Untracked files:
      (use "git add <file>..." to include in what will be committed)
        library_management/library_management/doctype/__init__.py
        library_management/library_management/doctype/article/__init__.py
        library_management/library_management/doctype/article/article.js
        library_management/library_management/doctype/article/article.json
        library_management/library_management/doctype/article/article.py
        library_management/library_management/doctype/article/test_article.py

    nothing added to commit but untracked files present (use "git add" to track)

article.json - JSON file that defines 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

As you can see, a DocType describes a lot of things about the model. Not only does it define the table and column names but also how it will be rendered in various views in the Desk.

Good job following the tutorial so far. Let's keep going!