Mastering Frappe Framework – Part 3: Your First Frappe App

Goal of This Tutorial

By the end of this guide, you’ll have:

• A new Frappe App
• A custom DocType called ToDo Plus
• A form to create tasks with fields: Title, Description, Due Date, and Status
• The ability to view and manage tasks in the Frappe desk

---

Step 1 – Create a New Frappe App

Make sure you’re inside your bench folder.

cd my-bench
bench new-app todo_plus

You’ll be asked:

• App Name: todo_plus
• App Title: ToDo Plus
• App Description: Simple task manager
• Publisher: Your Name
• Email: your@email.com
• License: MIT
• App Icon: (optional)

---

Step 2 – Install the App on Your Site

bench --site mysite.local install-app todo_plus

This makes the app available on your site.

Step 3 – Create Your First DocType

Run:

bench make-doctype "ToDo Plus" --module "ToDo Plus" --create-controller

This will:

• Create a database table (tabToDo Plus)
• Generate a Python controller file (todo_plus.py)
• Add the DocType to the Frappe UI

---

Step 4 – Add Fields in DocType

Go to your site in the browser → Desk → ToDo Plus → Customize

Add these fields:

1. Title – Data (Required)
2. Description – Small Text
3. Due Date – Date
4. Status – Select (Options: Pending, In Progress, Completed)

Save and reload.

---

Step 5 – Add Basic Server-Side Logic

In todo_plus/todo_plus/doctype/todo_plus/todo_plus.py:

import frappe
from frappe.model.document import Document

class ToDoPlus(Document):
    def validate(self):
        if self.status == "Completed" and not self.due_date:
            frappe.throw("Due Date must be set before completing a task.")

This ensures a task can’t be marked as completed without a due date.

---

Step 6 – Add a Client Script (Optional)

Create a JS file:

todo_plus/todo_plus/doctype/todo_plus/todo_plus.js

frappe.ui.form.on("ToDo Plus", {
    refresh: function(frm) {
        if (frm.doc.status === "Pending") {
            frm.add_custom_button("Mark In Progress", () => {
                frm.set_value("status", "In Progress");
                frm.save();
            });
        }
    }
});

This adds a quick action button.

---

Step 7 – Test Your App

1. Go to Desk → ToDo Plus → New
2. Add a task and save.
3. Try marking it as “Completed” without a due date — it should throw an error.
4. Use the Mark In Progress button to change status easily.

---

Step 8 – Access via API

Frappe auto-generates APIs for CRUD operations.

Example: Get all tasks

curl -X GET \
  http://mysite.local/api/resource/ToDo%20Plus \
  -H "Authorization: token <api_key>:<api_secret>"

Key Learnings from Part 3

• How to create a new app in Frappe
• How to define and customize a DocType
• How to add server-side validation
• How to make UI interactive with Client Scripts
• How to use built-in REST APIs

---

What’s Next?

In Part 4, we’ll focus on Backend Development in Frappe:

• Writing custom API endpoints
• Fetching and filtering data with Frappe ORM
• Scheduling background jobs
• Sending notifications