Adventures with Frappe Charts and ERPNext Pages

Disclaimer: This article is “under construction”, and it combines several features of the Frappe framework, ERPNext and their nifty Frappe charts. As usual, and for the foreseeable future, I clarify I am a developer in learning originating from a farming background, so, expect errors and major oversights. This assumes you have already setup a development ERPNext server, or even a production server, with enabled developer mode and have created an application. For more on that, see this.

My Quest for Simple Data

Ever since before my foray into entrepeneurial pursuits, it became quite obvious that having information was essential to make rational decisions with value-adding consequences for business. In short, you need data to make the right decisions. Today we read and hear about the much-hyped big-data revolution, but, what will it give us? After many years of working in agriculture it was clear what kind of data was necessary to fulfill our agreements successfully.

In an ideal world, that data is neatly served in a dashboard format, analyzed previously and ready to simplify your task.

However, too much time is spent hunting down this data, then scanning it or copying it unto spreadsheets, configuring graphs and then interpreting the data. Once analyzed, new patterns emerge and you wish to further explore some analysis idea. Long days were spent gathering the data. Even then, confidence in its veracity was low.

Discovering Frappé and ERPNext have provided me with a vision of the future, where data is clearly shown, tools for analyzing it are easily available and after developing these tools and configuring them, one spends less time in the office or on the computer, and your staff scrambling to enter it or prepare it for analysis.

My Goal

Having self-deployed an instance of Frappé/ERPNext in early 2016, I have been hooked. I run my startup business entirely on ERPNext, and I continue learning and discovering many things about it. It’s quite straightforward for new users, and although documentation is always in need of improvement (at the time I started writing this), users can quickly learn the basics and become experts as time goes by. For new developers, the panorama is a bit more spartan. I aim to help in changing that as I learn by writing these blog posts/articles.

So aside from having a functional realtime dashboard feeding from data generated by all users in the business, I want to share my learning journey so others can travel this path with more ease.

Pages

Frappe, the framework that is used to run ERPNext, has as a basis the DocType, where you enter and manipulate data. I have had sufficient success creating them, coding with them and learning along with the community and my team of programmers. However, I have not yet mastered a view called “Page”. I think of the page more like an artists’ canvas, where you can draw anything.

The page is useful to show data in tabular format, or to show graphs. Since this is one of my ultimate goals, I have finally found some time to dedicate to this endeavour. Once complete I will merge this article with my Basic Coding Guide to Frappé / ERPNext Part 2 series.

Creating a Page

So, you have created an Application as per my guide above. Now, you are ready to create your page.

On your web browser, access the Desk and go to the awesome bar on top. Type Page List. You will see all the existing Page DocTypes. You can click on the New button on the top right to create a new page.

A faster, alternative way is to directly type, in the awesome bar, this command:

New Page

Both routes above will allow you to specify the basics for creating your boilerplate (a template) for a page in ERPNext. At a minimum, you must specify:

Name: Pick a name that will be used systemwide, usually something without spaces.

Title: Although it is not required, give your page a title.

Module: Select the module you want the page to appear in, if you are using it on your custom application, pick that module from the dropdown.

Standard: specify if yes or no.

Roles: Add the roles that can have access to the page.

Click on Save and your page boilerplate is created. Now we can access it on the server for coding.

Either with a shared folder in your development VirtualBox, or on the local machine, or even vía the console access the directory for the page boilerplate:

/apps/[your-app-name]/[your-app-name]/[your-app-name]/page/[page_name]/

In that directory you will find three files:

__init__.py
[page_name].js
[page_name].json

For clarity in the article, we shall henceforth name our [page_name].js file like this: test-page.js, open it up so we can begin:

At this point, the page can only be accessed on the server using a direct link, in this case:

[Server URL]/desk#testpage

If you type it into your browser, you shall find this:

Empty Page in ERPNext

Let’s Play

Now that we have an empty page in ERPNext, we can begin our artwork. We’ll start with some basics and then move on to other items I consider important.

If we add a menu button, we can provide the user with controls that allow him to perform several actions on the page. For this example, we will simply add a link to the Projects page. We do so like this:

And the result when we reload the page is this:

Adding a Menu

If you click on the link created in the menu, you will be taken to the Projects list view. Feel free to test it. Click on the back arrow in your browser.

You can also specify the breadcrumb route on the top left, so you can navigate from within ERPNext to the Module where you came from, by adding this line:

frappe.breadcrumbs.add("[Module-name]")

This must be added within the frappe.pages[].on_page_load function.

One of the things I like a lot about Frappe is how it is constantly evolving. They deployed their own independent library of charts last year called Frappe Charts. I witnessed the presentation in person at the Mumbai Auditorium during the conference in October 2017, and given all that there is to learn about ERPNext it is until now that I sit down and actually play with it.

Just yesterday I managed to successfully load the sample chart onto this same page. Although the element I picked in the page was adequate. I ended up with this:

TK Pending upload of image of chart deployment covering entire page.

The code above has two additional blocks of code. Each is defined with JavaScript’s const for variables whose variable identifier cannot be reassigned. The value can change.

The issue I was having this weekend as I tried to implement it is my failure in using the correct property value in the chart object for parent. Finally, referring to some examples in Frappe Chart’s blog by Prateeksha I stumbled upon the correct methodology, which is using jQuery to refer to the DOM, for the div tag with class = layout-main-section

parent: $('.layout-main-section'),

And as I continued working on it, I finally was able to have a successful display of the sample chart. Working code is below, complete with english and spanish comments.

The jQuery portion of this code was graciously provided by Prateeksha Singh.

Pending:

  1. Play around with different graph types.
  2. Connect to desired data in DB to parse and show it.

Special thanks to Prateeksha Singh and Faris Ansari on their wonderful video which I am using as a guide to write this article.

As I build upon the page, I feel compelled to add useful elements to have a sort of “template” which I can easily use as my source to create similarly styled pages in the future by copying blocks of code and pasting in a new .js file for each page, a sort of “toolbox” for future reference.

frappe.msgprint()

The frappe.msgprint() method will launch a Message box/pop-up to the user. It will be a pop-up style window with a close button and the desired message. This is useful for confirming certain actions have ocurred. Use sparingly!

TK an example

frappe.throw()

The frappe.throw() is similar to msgprint, except it clearly shows the title Error.

Users can include more than just a single line of text, they can include a table or similar, which serves as confirmation or where the user can be prompted to add some details to a DocType or validation.

Reminder:

All the code shown after this must go within this wrapper element!

frappe.pages[‘testpage’].on_page_load = function(wrapper) {}

Let’s begin with an example of a dialog on our sample page:

// en-US: This is the basic Dialog controller for Frappe. We create a dialog object, with the title attribute set to “Hi” and assign it to a variable “d”d = new frappe.ui.Dialog({title: “Hello World”});// en-US: Here we command that the dialog assigned to “d” be shown on the page using the show() method.d.show()

The result should be this:

Behold! There is a lot of lettuce, basil, kale, arugula, etc. (and plenty of useful, valuable software code too!)

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store