Understanding DocTypes


- Controller Methods
- Controller Hooks

Child DocType
Single DocType
Actions and Links


A DocType is the core building block of any application based on the Frappe Framework. It describes the Model and the View of your data. It contains what fields are stored for your data, and how they behave with respect to each other. It contains information about how your data is named. It also enables rich Object Relational Mapper (ORM) pattern which we will discuss later in this guide. When you create a DocType, a JSON object is created which in turn creates a database table.

ORM is just an easy way to read, write and update data in a database without writing explicit SQL statements.


To enable rapid application development, Frappe Framework follows some standard conventions.

DocType is always singular. If you want to store a list of articles in the database, you should name the doctype Article.
Table names are prefixed with tab. So the table name for Article doctype is tabArticle.
The standard way to create a DocType is by typing new doctype in the search bar in the Desk.

A DocType not only stores fields, but also other information about how your data behaves in the system. We call this Meta. Since this meta-data is also stored in a database table, it makes it easy to change meta-data on the fly without writing much code. Learn more about Meta.

A DocType is also a DocType. This means that we store meta-data as the part of the data.

After creating a DocType, Frappe can provide many features out-of-the-box. If you go to /desk#List/ToDo you will be routed to the List View in the desk.

Similarly, you get a Form View at the route /desk#Form/ToDo/000001. The Form is used to create new docs and view them.


A DocType will always belong to a module, to enable easier grouping of related models. Frappe comes with a lot of built-in modules. For e.g

Core - contains doctypes like DocType, DocField, Report, System Settings, etc
Desk - contains doctypes like ToDo, Event, Note, Kanban Board, etc
Email - contains doctypes like Email Account, Newsletter, Email Group, etc

Modules also helps in grouping of code files in directories. The controller files generated by a DocType will live in it's respective Module directory.


A DocField is a list of fields which describes what properties a DocType will have. For instance, a ToDo doctype has fields description, status and priority. These ultimately become columns in the database table tabToDo.

Similar to the depends_on property which determines whether a field will be displayed or not, in Version 12 we have introduced two new properties:

mandatory_depends_on: If this condition is satisfied, the field will be mandatory.
read_only_depends_on: If this condition is satisfied, the field will be read only.
Frappe comes with more than 30 different fieldtypes out-of-the-box. These fieldtypes serve a variety of use-cases. Learn more about Field Types.


All docs in Frappe have a primary key called name. This is the unique id by which you will be finding records and manipulating them using the ORM. You can configure how docs should be named when a new document is created. The following are the ways you can setup naming in a DocType.

1. field:[fieldname]

The doc name is fetched from the value of the field provided.

2. [series]

You can provide a naming pattern which will be incremented automatically. For e.g, if you set it as PRE.#####, the first document created will have the name as PRE00001, and second one will be PRE00002 and so on.

3. naming_series:

The naming pattern is derived from a field in the document. For e.g, you have a field naming_series in your document and it's value is set as PRE.#####, then that will be the pattern used for generating the name. This value can change per document. So the next document can have a different pattern.

This works only if you have a field called naming_series in your DocType.

4. Prompt

If you set it as Prompt, the name is required to be filled in manually.

5. Format

This is the most flexible one when it comes to configuring your naming schemes.

Let's say we have


Everything outside the curly braces are plain text. Keywords inside the curly braces will be evaluated based on what they represent. In this case:

MM: will be replaced by the current month
fieldname1: will be replaced by the value of fieldname1 in the document
#####: will generate a series, which starts with 00001

So the final name may look like, EXAMPLE-02-test-value1-value2-00001


A Document is an instance of a DocType. It usually maps to a single row in the database table. We refer to it as doc in code.


Let's say we have a DocType ToDo with the following fields:


Now, if we want to query a document from the database, we can use the ORM.

You get the values of description, status and priority, but you also get fields like creation, owner and modified_by which are fields added by default by the framework on all++docs++.


A Controller is a normal python class which extends from frappe.model.Document base class. This base class is the core logic of a DocType. It handles how values are loaded from the database, how they are parsed and saved back to the database.

When you create a DocType named Person, a python file is created by the name person.py and the contents look like:

All the fields are available to the class as attributes.

Controller Methods

You can add custom methods to your Controller and it will be callable using the doc object. For example,

You can also override the pre-defined document methods to add your own behaviour. For e.g to override the save() method,

Controller Hooks

To add custom behaviour during the lifecycle of a document, we have controller hooks.

To use a controller hook, just define a class method with that name. For e.g

1. Create a document

To create a new document and save it to the database,

2. Load a document

To get an existing document from the database,

Child DocType

Up until now we have only seen DocTypes that can have a single value for each field. However, there might be a need for storing multiple records against one record, also known as many-to-one relationships. A Child DocType is doctype which can only be linked to a parent DocType. To make a Child DocType make sure to check Is Child Table while creating the doctype.

Child DocType records are directly attached to the parent doc.

Single DocType

A Single DocType is a DocType that holds only one record in the database. It is useful for persisting things like System Settings, which don't make sense to have multiple records.

Actions and Links


A DocType may also have Daily Action that will result in a button creation on the DocType View. Supported actions are:

Server Action: This will trigger a whitelisted server action.


A standard navigation aid to the DocType view is the Links section on the dashboard. This helps the viewer identify at a glance which document types are connected to this DocType and can quickly create new related documents.

Configuration of Actions and Links

Was this article helpful?
Thank you!