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
Features
The dashboard is part of the form and consists of several sections:
- Progress Area
- Heatmap Area
- Chart Area
- Stats Area
- Connections Area (for related documents)
- Custom Section Area
- Headline Area
- Badge Area
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 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.
