Dexciss Technology - Mastering Frappe Form Dashboards: A Developer’s How-To Guide

Introduction

Frappe has hidden Form Dashboard features which can help make our forms a lot more user friendly. These features are not well-documented, so this guide aims to provide a comprehensive overview of how to use them effectively.

Source

Frappe’s Form Dashboard code 44

Features

The dashboard is part of the form and consists of several sections:

1. Progress Area
2. Heatmap Area
3. Chart Area
4. Stats Area
5. Connections Area (for related documents)
6. Custom Section Area
7. Headline Area
8. Badge Area

🔍 What Are Form Dashboards?

Form Dashboards appear at the top of the form view in Frappe. They typically display:

1. Linked DocType counts (e.g., how many Sales Invoices are linked to a Customer)
2. Custom HTML content
3. Chart summaries

They give users instant visibility into related documents and KPIs, enhancing the UX without custom reports.

🛠️ How to Add a Custom Dashboard

You can add dashboard data using the frappe.ui.form.on() client-side hook and calling frm.dashboard.add_doctype_section().

Here’s a basic example:

js

CopyEdit

frappe.ui.form.on('Customer', {

 refresh(frm) {

              frm.dashboard.add_doctype_section('Sales Invoice', 'Customer');

         }

    });

This adds a “Sales Invoice” summary to the Customer form dashboard.

Key Features and Implementation

1. Progress Indicators

Use progress indicators to show completion status or any quantitative measure.

frm.dashboard.add_progress(title, percent, message) 
frm.dashboard.show_progress(title, percent, message) 

Usage:

frm.dashboard.add_progress("Task Completion", 75, "3 of 4 tasks completed");
frm.dashboard.show_progress("Task Completion", 80, "4 of 5 tasks completed");

2. Heatmaps

Heatmaps are great for showing activity over time.

frm.dashboard.render_heatmap()

Usage:

frm.dashboard.render_heatmap({
    data: {
        dataPoints: {
            "1632441600": 5,
            "1632528000": 8,
            // ... more data points
        },
        start: new Date("2021-09-24"),
        end: new Date("2022-09-23")
    }
});

3. Charts and Graphs

Add visual representations of data with charts:

render_graph(args) 

Usage:

frm.dashboard.render_graph({
    data: {
        labels: ["Jan", "Feb", "Mar", "Apr", "May"],
        datasets: [{
            name: "Sales",
            values: [100, 120, 115, 110, 125]
        }]
    },
    type: 'line',
    colors: ['#7cd6fd']
});

4. Stat Indicators

Display key statistics or metrics:

frm.dashboard.add_indicator(label, color)

Usage:

frm.dashboard.add_indicator("Total Sales", "green");
frm.dashboard.add_indicator("Pending Orders", "orange");

5. Related Documents (Transactions)

Show links to related documents:

frm.dashboard.add_transactions(opts)

Usage:

frm.dashboard.add_transactions({
    label: "Related Documents",
    items: ["Sales Order", "Delivery Note", "Sales Invoice"]
});

6. Custom Sections

Add custom HTML sections to the dashboard:

frm.dashboard.add_section(body_html, label = null, css_class = "custom", hidden = false)

Usage:

let custom_section = frm.dashboard.add_section(
    `<h3>Custom Information</h3> <p>This is a custom section with any HTML content.</p>`,
    "My Custom Section"
);

7. Dynamic Updates

Update dashboard elements based on user actions or server responses:

frm.dashboard.set_headline(html, color, permanent = false)

frm.dashboard.clear_headline()

Usage:

frm.dashboard.set_headline("Document is under review", "orange");
frm.dashboard.clear_headline();

8. Badges and Counts

Display counts for related documents:

frm.dashboard.set_badge_count_for_external_link(doctype, open_count, count)

Usage:

frm.dashboard.set_badge_count_for_external_link("Sales Order", 5, 10);

9. Additional Dashboard Methods

There are several other useful methods:

Reset Dashboard

Reset the entire dashboard to its initial state:

frm.dashboard.reset()

Hide and Show Dashboard

Control the visibility of the entire dashboard:

frm.dashboard.hide()

frm.dashboard.show()

Clear Sections

Remove specific sections from the dashboard:

frm.dashboard.clear_section(section_name)

Usage:

frm.dashboard.clear_section("chart");

Set Document Status

Update the status indicator of the document:

frm.dashboard.set_docstatus_icon(status)

Usage:

frm.dashboard.set_docstatus_icon("Submitted");

Add Comments

Add a comment to the form:

frm.dashboard.add_comment(text, alert_class, permanent) 

Usage:

frm.dashboard.add_comment("New comment added", "alert-info", false);

Conclusion

This guide provides an overview of the key features available in Frappe’s Form Dashboard. We can use these functions to create more informative and interactive form experiences for our users. Remember to refer to the source code 44 for the most up-to-date implementation details and additional features.

Please share screenshots and your usage examples here or as a pull request via github 8.