frappe/docs/docs.dev.quickstart.md

_label
Quickstart

Preamble

wnframework is, a Python based, meta-data driven framework. The framework implements its own object-relational model (ORM) and provides a rich client interface based on Javascript. It is primararily used to develop ERPNext

To develop on wnframework, you must have a basic understanding of how web applications and client-server architectures work. On the server-side, requests are handled by Python modules via CGI. So each request is a new thread and there is no state preservation on the server. Session data is stored in memcached server.

WNFramework also has way you metadata is defined, called a DocType. Everything object in the system like a Customer or Journal Voucher is a DocType.

Overall, be prepared for a slight learning curve. A lot of the inner code / design is not very elegant and you might encounter spaghetti at certain places. We are working to reduce all of that.

---

Meta data

Base model in wnframework is called a DocType. A DocType represents a database table, a web form and a controller to execute business logic. In classical MVC terms it is all three model, view and controller to an extent.

DocType objects have DocFields that are properties of the model.

---

Client-Server Setup

Let us understand how to setup web folders via ERPNext

An ERPNext setup contains 2 repositories erpnext and wnframework. In the main folder of the erpnext setup there are 3 folders:

+ lib
+ app
+ public

The lib folder represents wnframework, the app folder represents erpnext and the public folder is served on the web.

To build the public folder for the first time, run this utility from the base folder:

$ lib/wnf.py -b

All web pages are served by public/web.py and all data requests are served by public/server.py

The server-side libraries are in lib/webnotes and client-side libraries are in lib/public/wn folders.

Requests & Routings

There are 2 types of requests, requests for web pages (when the user is not logged in) and data requests when the user is logged in. Let us see data requests:

All data requests are made on public/server.py. The method and parameters are passed as form parameters.

The cmd paramter represents the python method to be executed. This is the “routing” used in wnframwork. Use the @webnotes.whitelist() decorator to whitelist a particular method to be accessible by the web.

For example, the request:

server.py?cmd=accounts.utils.get_account&account_name=Test

will call the get_account method in app/accounts/utils.py.

Repsonse

The return to that will be sent as a JSON object

{
  "message": "returned by get_account", 
  "server_messages":"Any popup messages to be displayed", 
  "exc": "Any exceptions encountered"
}

Once the control is passed on to the method, the response is sent back via JSON.

---

Front End

The front end is a Javascript based client application. You can login by opening the login page from your browser. If you have setup your apache routes correctly, just go to
localhost/public/login or equivalent to see the login page. This actually translates into public/web.py?page=login.

Once you login, you will be redirected to app.html that fires up the application front-end.

URL routing:

Different pages / objects are accessed by url fragments #

Forms

All objects are accessible via #Form/[DocType]/[Doument Name] on the URL.

To open the customer DocType, you can go to #Form/DocType/Customer or to open a Customer, Customer A, go to #Form/Customer/Customer A

Pages

Static pages in the application are accessed by their name. For example, the home page called desktop can be accessed by #desktop

Client Application

The client application is bunch of js libraries that help in navigation, rendering forms, reports and other components. The application code in public/js/all-app.js is built by combining files specified in lib/public/build.json and app/public/build.json. To rebuild the client application after making a change, call lib/wnf.py -b from the command line.

---

Application / Module Development

Creating / Editing DocTypes

To create or edit the DocType “schema” you will have to fire the front-end via a web-browser and login as Administrator. To open a DocType, go to Document > Search > DocType and select the DocType to edit.

The DocType form should be self explanatory. It has a list of fields that are used for both the database table and form. Special fields like Column Break and Section Break are present to make the form layout that is processed sequentially.

DocType is discovered via permissions (DocPerm) and by URL routes.

Once you save a DocType, the database schema is automatically update, while developing, you should fire up a mysql command-line or viewer to see the impact of your database changes.

Adding code to DocTypes

You can add business logic by writing event code on both client and server side. The server side events are written in Python and client side events are written in Javascript.

The files from where these events are picked up are in the module folders in the repositories. Apart from the core module, all modules are parts of erpnext (app folder). Each DocType has its own folder in the module in a folder called doctype. If you browse the files of erpnext, you should be able to locate these files easily.

Server-side modules

For example, the server-side script for DocType Account in module Accounts will be present in the folder app/accounts/doctype/account/account.py

The events are declared as a part of class called DocType. In the DocType class there are two main useful properties:

• doc: Represents the main record.
• doclist: Represents list of records (including child records) that are associated with this DocType. For example the doclist of Sales Order will have the main record and all Sales Order Item records.

The main serverside events are:

• validate: Called before the INSERT or UPDATE method is called.
• on_update: Called after saving.
• on_submit: Called after submission
• on_cancel: Called after cancellation.

See a sample server side file for more info!

---

Custom UI: Pages

Custom UI like Chart of Accounts etc, is made by Pages. Pages are free form virtual pages in that are rendered on the client side. A page can have an .html (layout), .py (server calls), .js (user interface) and .css (style) components.

Understand how pages work, it is best to open an existing page and see how it works.

---

Patching & Deployment

Data / schema changes are done to wnframwork via patches released in the app/patches module (see erpnext folder for more details). To run all latest patches that have not been executed, run lib/wnf.py -l

wnframework deployment is done by the lib/wnf.py utility.

See lib/wnf.py --help for more help.

Good luck!