Frappe Framework Low-Code 101

In this blog post, we will be learning the fundamentals of development in

Frappe Framework as Low Code (no installation no deployment step). We will
be using Frappe Cloud to create a small "Expense Request Application" step
by step together. After this tutorial, you should be familiar with many moving
parts of the Framework, then for more detail you can always visit the official
Frappe Framework documentation

What is Frappe Framework?

 Web framework in Python and Javascript
 Low-code platform with battery included
 Simple and Straight Forward Technical Stack
 Beautiful, Polished and Complete

What is battery included?

 Metadata First
 Admin User Interface
 Roles and Permissions
 Extensible
 REST API + Webhooks
 Job Scheduler
 Socket.io
 Email Setup
 Multi-tenant
 Etc.

What will we build?

Tutorial Agenda
1. New Site on Frappe Cloud
2. Create Module Def
3. Create Doctype (data model) for Expense Request and Expense Lines
4. Polish Expense Request DocType & Form Layout
5. Document Series
6. Name and Title
7. Status Field
8. Server Script
9. Client Script, i..e, Onchange, Filtering
10.Single Doctype as Settings
11.Session Defaults
12.Button Actions
13.Create Workspace and add menu shortcut
14.Web Form
15.Web Page
16.Print Format
17.Report View
18.Dashboard View
19.Kanban View
20.Submittable Document
21.Approval Workflow
22.Permissions
23.More Magics

Create New Site on Frappe Cloud

 Sign Up @ https://frappecloud.com/
 Create Site, version 14, Singapore
 No need to install any App (only Frappe Framework will be installed)

 After site is created, on the Dashboard, login as Administrator to create

first user
 After login, user will see the "Desk"
 Desk (/app) is default entry point or "Workspace" for system users
Create Module Def
On every customization, we can tag it with "Module" name, which is useful for
packaging after.
 Search for "Module Def" and "Add Module Def" (or type "New Module
Def" on search bar)

 Name it "Expense App" and Save (or Ctrl+S)

Create a Doctype
 Search for "Doctype" and "Add Doctype" (or type "New Module Def" on
search bar)
 New DocType = Expense Request, Module = Expense App
 Add some fields as following and Save (Ctrl+S)

 New Document Type "Expense Request" is ready to use

 You can now search for "Expense Request" to open the window
 You can use Create/Update/Delete for Expense Request
 Next, we want to create a child table, for expense lines
 New DocType = Expense Request Line, Module = Expense App
 Is Child Table = True
 Add some fields as following and Save (please ensure correct Data
Type)
  Next, we want to add "Expense Request Line" as child table of Expense
Request
 Or open Expense Request and click "Customize" to open its DocType
(or open DocType List and find Expense Request)

 On this "Expense Request" DocType add new field "Expense Lines" as

Table, options = "Expense Request Line"

 Save changes and click button "Go to Expense Request List" on Top of
page
 Now, you can see that you can add multiple Expense Lines in your
Expense Request

Polish Expense Request DocType & Form Layout

Final Required Layout

 List View
  Form View with 2 tabs

Configurations

 Open DocType = Expense Request and add fields / sections as

followings
  Edit User, Date and Total Amount to be in list view and in list filter

 Save changes and click button "Go to Expense Request List" on Top of
page
 You should see changes in List and Form view.

Document Series
There are many ways to setup Naming, in this case we want to use
Expression = format:EXP{YY}{####}
 Open DocType = Expense Request and setup Naming as follow,

 Now, create new Expense Request, you will see that the ID (name) is a
Running Series
Note:

 There are more types for series,

 Set by user
 Autoincrement
 By field name
 By "Naming Series" field
 Expression
 Random
 By script

Name and Title

For Frappe, name is ID of a record. It can be a long string, represent a name
and must be unique!!! As such, Link field will directly show the Name. Very
straight forward and fast (no joining occur).

As an option, you can set another field as Title, which will show in Link field
too.

Create a new DocType "Expense Type"

 As "Name" is auto field (ID), just add one more field "Title"

 Use title field as Title of the record

  Test by create 3 Expense Types as following,

 Title will be on the left most of the list view instead of Name (ID)
 Name (ID) is auto generated and will be on the right most of the list
view
Add Expense Type field as Link field in Expense Request
 Add Expense Type with Type "Link" with Options "Expense Type"

 Open Expense Request record, select an Expense Type

Note:

 if we did not use Tile option, we will see Expense Type by Name (ID) as
normal

Status field
Status field is a special field, which can have color highlighted

Add field "Status" for DocType "Expense Request"

 Make sure Status field is Type "Selection" with Options "Draft,
Approved, Rejected"

 Setup color for states in section "Document States" of DocType

Expense Request

 Once all has been set, we will see Status as part of the document
Server Script (Python)
In Frappe can write server side script with python for almost anything as Low-
Code, and hook it with DocType event.

For more info go to documentation.

To Calculate Total Amount based on Expense Lines' Amount

 Create new Server Script "Sum Total Amount"

 Following code will be executed for Expense Request on event "Before
Validate" (occur before create or update)

total = 0.0
for line in doc.expense_lines:
total = total + line.amount
doc.total_amount = total
 Test by adding Expense Lines with Amount, calculation will happen on
both create/update.

Types of Script

1. DocType Event
2. Scheduler Event
3. Permission Query (filter for list view and linked field)
4. API (public method)

Client Script (Javascript)

Frappe is having a good balance between Frontend and Backend. Think of
frontend code as standard javascript with Frappe JS library for ease of use
within frappe environment.

For more info go to documentation.

Onchange user set manager, and onchange line set total.

 Create new Client Script "Onhcange User - Manager"

// Onchange user: set Manager / Today
frappe.ui.form.on('Expense Request', {
user(frm) {
const date = new Date();
frm.set_value('date', date.toISOString().split('T')[0])
frm.set_value('manager', frm.doc.user)
}
})

// Onchange line amount: set total

frappe.ui.form.on('Expense Request Line', {
amount: function (frm, cdt, cdn) {
let total = 0.0
for (let i = 0; i < frm.doc.expense_lines.length; i++) {
total += frm.doc.expense_lines[i].amount
}
frm.set_value('total_amount', total)
}
})
  Let's test by select User, and add Expense Lines and see the effect

Add filtered on Expense Type link field.

 Create new Client Script "Filter Expense Type"
frappe.ui.form.on('Expense Request', {
onload(frm) {
frm.set_query("expense_type", function() {
return {
filters: {
"Title": "Travel"
}
}
})
}
})
 The field Expense Type is now filtered with only "Travel"
 After testing you may disable this script.
Single Doctype as Settings
Single Doctype is just the Doctype with single record. Mostly used
for settings.

Create Expense Settings for setting Default Expense Type

 Create DocType "Expense Settings", with Is Single = True
 Add Field "Default Expense Type" as Link Field "Expense Type"

 Go to Expense Settings and set Default Expense Type

Use this default expense type when create new Expense Request

 Create new Client Script "Set Default Expense Type"

frappe.ui.form.on('Expense Request', {
onload(frm) {
if (frm.doc.expense_type) {
return
}
frm.call({
method: 'frappe.client.get_single_value',
args: {
doctype: 'Expense Settings',
field: 'default_expense_type'
}
})
.then(r => {
frm.set_value('expense_type', r.message)
 });
}
})
 Test create new Expense Request, you will see the Expense Type is
now set to default type.

Session Default Settings

In the previous session, we use client script to get default value from
Expense Settings. Frappe has another easier way to set default value.
 Open Session Default Settings and add DocType = Expense Type

 Now, in any Document with link field "Expense Type", use can set
session default value.
 Go to Expense Request list, and open Session Defaults

 Set the default value for this user session

  Create new Expense Request, you will see the default value

Note:
 Default value is set for each user.

Button Action
Buttons (and any UI element) in Frappe is adding by client script. Normally, a
button is used to execute extra business logic for current form.

Add 2 actions, "Approve" and "Change status", under a button group "Actions"

 Create new Client Script "Approve Button"

frappe.ui.form.on('Expense Request', {
refresh(frm) {
// 1. Approve
frm.add_custom_button(__('Approve'), function(){
frm.set_value('status', 'Approved');
frm.save()
}, __('Actions'));
// 2. Change Status
frm.add_custom_button(__('Change Status'), function(){
frappe.prompt({
label: 'Change to Status',
fieldname: 'status',
fieldtype: 'Select',
options: 'Draft\nApproved\nRejected'
}, (r) => {
 frm.set_value('status', r.status);
frm.save();
})
}, __('Actions'));
}
})
 The above script will add Actions button with 2 actions
 Approve will set Status to "Approved" and save.
 Change Status will prompt for user to select Status and save.

Create Workspace and add menu shortcut

 Workspace can be Public (shared) or Private and is used to create
navigation
 Go to Home and Create Workspace as Public

 Click (+) to add new element and choose Shortcut

 Choose Document Type and link to Expense Request
 As optional, you can set filter and count

 Save change and refresh

  Go ahead play around and add more menus as you want.

Web Form
Web Form is a web page that map directly with a DocType. This make it easy
for external users to create records without having to access the "Desk".

This is similar to Google Form, but for Frappe database.

Create New Web Form

1. Create new Web Form

2. Fill form information
3. Get fields
4. Publish it
 Click on link See on Website, to link to the URL of the new Expense
Request Form

 URL: https://<your domain>/expense-request/new

  Test entering data and Save, the new Expense Request is created, you
can login to see it.

Polishing the Form

1. Multi Step Form

2. Enable Login and allow Editing
3. Add banner and response message

1. Multi Steps Form

 Open Web Form for "Expense Request" and make arrangement as

following
 Click link "See on Website" on the top left of page, you will see now we
have nicer multi step form
Note:

 Client Script on Expense Request won't affect the web form.

 If you need client script, you need to add it on Web Form itself.
See documentation.

2. Enable Login

 Enable Login
 As Login Enabled, we can allow CRUD operation and declare columns
on List View
  Save and "See on Website", you now see that now Login is required
 Test a full CRUD operations

3. Add nice banner and a response message

  Test submit a new record

Web Page
While Web Form link directly with a DocType, Web Page does not. Web Page is
the way to easily create website page from template (think wordpress).

To Create a landing page for Expense Request

 Go to Web Page, create a new web page "Expense".
 For simplicity, let's use some predefined templates, Content Type =
Page Builder.
 Create Building Block "Hero with Right Image", and Edit Value
 Fill in values
 Click "See on Website" on the top right of page
Note:
 You are now using the web templates for simplicity
 You can actually use HTML, Markdown, Javascript for custom look and
feel

Print Format
By default, every DocType will has "Standard" print format ready to use. But
user can always create more print format easily.

 Click print icon to open Print Page

 Standard format is based on the Doctype Layout

Create new Print Format

 Click "Customize" or "Try the new Print Format Builder" to create a

new Print Format
 Try out the Print Format Builder (please add Letter Head too, there is a
bug w/o letter head)
 You can play around with the form as you want here.

 Click "Save", the new Print Format will be created. You can go to Print
Format List to see it.
 Go to Expense Request form, and click "Print" again with new Print
Format
Note:

 Go to "Print Format List" to see all print formats

 For complex requirement, you can also use Jinja template to create
print format.

Report View
Report is another type of view that can show more columns (List view only
limit to 7 columns).

Similar to print format, every DocType comes with a Standard Report View.
User can create more reports with ease.

Open Report View

 Open Expense Request List

 Change to Report View
 There are many option on Report View

 Use "Pick Columns" to manage display columns

 Use "Export" to export as excel/csv

 Use "Save As" to create new Report "Approved Expense" based off
current report.
 Go to Report List, you will see the new Report

 Click on Approved Expenses report, this is report for "Expense

Request" of type "Report Builder"
 Click on "Show Report" button to run report again

 Configure report, i.e., Filter, Show Totals, Pick Columns

 For example, filter Status = Approved
  Save it (not Save As)

 Run report again, and it will show result as per last Save

Add Report to Workspace

 Click on Frappe icon to go to workspace

 Edit Workspace and add shortcut to the newly created report
  The new report is ready for use.
Note: There are more Report Type
 Query Report (SQL)
 Script Report (Coding)

Dashboard View
Dashboard View is the place to show Number Card and Chart for each
document type.

 Open Expense Request List

 Change to Dashboard View
 Create new Dashboard
 Add a New Chart (Number Card seem to not working for now)
  Save Customization

Note:

 You can Customize Dashboard later on and create as many chart / card
you want

Kanban View
Kanban View another to organize documents based on some Selection Field.

 Open Expense Request List

 Change to Kanban View, create one if not already exists
  Use "Kanban Settings" (on 3 dots) to add more data to display on card.
Note:
 You can create as many Kanban Board as you want.

Submittable Document
This is the way to control internal state of a document. Submitable only has 3
docstatus

1. Draft: docstatus = 0
2. Submitted: docstatus = 1
3. Cancelled: docstatus = 2

Document submitted or cancelled are Read-Only

To Set document as "submittable"

 Open Doctype "Expense Request"

 Set Is Submittable = True
Test submittable document

 Create a new Expense Request, now notice it has Submit button

 Change status to "Approved" and Save

 Click Submit button
 Now the document is not editable as it is submitted (docstatus = 1)

Note:
 As there is "Status" field, the label (green) will follow status after
submitted (Approved)
 If there is no "Status" field, the label will be "Submitted"

Approval Workflow
Each Doctype can has 1 active workflow. This is a simple workflow consisting
of States and Transition

Example:

Steps to create workflow

1. Create workflow states (optional)
2. Create required roles (optional)
3. Create the workflow
4. Add state and transitions
5. Activate it
 Go to Workflow State and create workflow states (if not yet created)

 Go to Role and Create required Roles (transition is executed based on

role)
  Create Workflow "Expense Approval Workflow" for Doctype "Expense
Request"

 Add States and Transition Rules

Explain the Workflow

 S1: When new Expense Request is created, the state is "Draft"
 S1: On "Draft", "All users" can Edit
 T1: All user can "Approve" to change state "Draft" to "Waiting Manager
Approval"
 S2: On "Waiting Manager Approval", only "Manager" can Edit
 T2: Only "Manager" can "Approve" to change state "Waiting Manager
Approval" to "Waiting CEO Approval"
 S3: On "Waiting CEO Approval", only "CEO" can Edit
 T3: Only "CEO" can "Approve" to change state "Waiting CEO
Approval" to "Approved"
 S4: docstatus = 1 (submitted) and status = Approved
Note:
 In Transition, user can set Condition with python logic for complex
workflow, i.e., based on amount, based on department etc.

Permissions
Permission in Frappe is very simple and straightforward, and it only has 3
types of permission.

1. Doctype Role Permission

 Open Role Permission Manager to manage roles permission

 All Doctype are assigned with Role(s). Each role can do a certain
things, i.e., Expense Request

 Special flag "Only If Creator" to allow only Creator to have access

2. Fields Level Permission

 Each fields can set Level group (0-9), default Level is 0

 Assign specific Role to view/edit that field level

To allow only user with role CEO to see field Description

 Edit Doctype "Expense Request", set Perm Level = 1

 Open Role Permission Manager and add new rule with Level = 1 for CEO
Role
  Login as user without CEO Role, and Description field will be invisible
 Login as user with CEO Role, and Description field will be visible
3. Document User Permission
 Record level permission goes by each User and based on Link fields
To allow a user to have access only Expense Type = Travel
 Go to User Permission and create a new User Permission

 Apply to All Document Types = True, any document with field Expense
Type will has this permission applied
 Click "View Permitted Documents" to find see what documents this
user has permission to see.
Some Magics
Following are some useful tools / features that I can think of now. There are
more...

System Console
 Run SQL or Python Code

Global Search

 Go to Document List / Report

 Create new record on the fly, type New <Doctype>

 As Calculator

 Find Document Name, i..e, 0018 in Expense Request

 Global Search and field (Config in Doctype Field and Global Search
Setting)
 Search by Tags
Rest API

 Built in Rest API for all Doctype

Copy / Paste

 Copy to clipboard

 JSON string will be in memory

 Crtl+V to paste it to create new record

Simple URL

 URL can be sent out and reopen with same Filters

Webhook

Track Changes / Track Seen / Track View

Version (Change Log)

Error Logs

Deleted Documents / Restoration

Auto Email Reports

Data Import Tool

END.