Dolibarr ERP/CRM is a powerful, open-source software platform used by thousands of businesses around the world. While it comes with robust features out of the box, one of its most underutilized yet impactful capabilities is the customization of dashboards using widgets. This detailed guide will walk you through everything you need to know to build your own personalized dashboard in Dolibarr, ensuring that you can tailor the system to your operational and strategic needs.

Table of Contents

  1. Introduction to Dolibarr Dashboards

  2. Why Customize Your Dashboard?

  3. Overview of Dolibarr’s Widget System

  4. Understanding the Technical Structure

  5. Preparing Your Dolibarr Environment

  6. Activating and Using Built-in Widgets

  7. Creating Your Own Custom Widgets

  8. Adding Widgets to the Dashboard

  9. Advanced Customization Techniques

  10. Managing User-Specific Dashboards

  11. Tips for Effective Dashboard Design

  12. Maintaining Your Custom Dashboard

  13. Troubleshooting and Debugging

  14. Final Thoughts and Best Practices

1. Introduction to Dolibarr Dashboards

Dolibarr dashboards provide a centralized place where users can quickly access important data and KPIs. By default, the home screen includes a general overview of system information and some quick stats. However, the platform allows for more detailed and role-specific dashboards by adding and configuring widgets.

These dashboards can be customized per user profile or even per individual user, offering a tailored experience that supports more productive workflows and faster decision-making.

2. Why Customize Your Dashboard?

Out-of-the-box dashboards often don’t reflect the exact needs of every business. Customizing your Dolibarr dashboard can help:

  • Focus on key performance indicators relevant to specific roles (e.g., sales vs. finance)

  • Reduce time spent navigating the system

  • Improve the user experience

  • Align system visuals with business goals

Custom dashboards transform Dolibarr from a generic ERP system into a powerful, personalized business hub.

3. Overview of Dolibarr’s Widget System

In Dolibarr, widgets are small, reusable components that display a piece of information or a summary of data. Examples include:

  • Latest invoices

  • Sales performance graphs

  • Inventory alerts

  • Calendar and reminders

Widgets can be moved around and configured individually, allowing users to personalize their views based on job function or personal preferences.

There are two types of widgets in Dolibarr:

  • Built-in Widgets: Pre-installed and available immediately after setup.

  • Custom Widgets: Developed manually or through modules to meet specific needs.

4. Understanding the Technical Structure

To create or modify dashboards and widgets, it’s essential to understand Dolibarr's structure. Core files and modules are organized under the /htdocs directory, and custom modules can be added without interfering with the core system.

Relevant folders include:

  • /htdocs/main.inc.php: Main file initializing the environment

  • /htdocs/core/modules/dashboard/: Contains dashboard-specific modules

  • /htdocs/theme/: Contains UI and styling elements

  • /htdocs/custom/: Recommended location for custom modules

Creating custom widgets often involves a mix of PHP, HTML, and JavaScript. Understanding object-oriented programming and the MVC pattern will also help in more advanced customizations.

5. Preparing Your Dolibarr Environment

Before beginning customization, make sure your Dolibarr environment is set up properly:

  • Use a development installation separate from your production environment.

  • Ensure your user account has administrator rights.

  • Install any required modules (e.g., Developer Tools).

  • Back up your instance before making changes.

You should also configure your IDE or code editor (such as VSCode or PhpStorm) for PHP development with syntax highlighting, version control (Git), and SFTP capabilities if working remotely.

6. Activating and Using Built-in Widgets

Dolibarr includes several built-in widgets. These are easy to activate and provide a foundation for your custom dashboard.

To access dashboard widgets:

  1. Navigate to Home > Setup > Display.

  2. Enable dashboard modules if they are not already active.

  3. Go to your homepage (usually Home > Dashboard).

  4. Click on the settings gear icon or "Add Widget" button.

You’ll be able to add predefined widgets such as:

  • Total customers

  • Number of open proposals

  • Sales pipeline visualization

  • Task summary

Each widget usually allows for basic configuration such as filtering by user, date, or status.

7. Creating Your Own Custom Widgets

Creating custom widgets provides a higher level of personalization. Follow these steps to build one:

Step 1: Create a Module

If you don’t have a custom module structure, create one:

mkdir /htdocs/custom/mymodule

Include the following files:

  • mymodule.php

  • class/actions_mymodule.class.php

  • core/modules/dashboard/widget_mywidget.php

Step 2: Write the Widget Code

In widget_mywidget.php, use Dolibarr’s widget framework:

class MyWidget extends DolibarrWidget {
    public function __construct($db, $user) {
        global $langs;
        $this->db = $db;
        $this->user = $user;
        $this->enabled = true;
        $this->description = $langs->trans("My custom widget");
    }

    public function render() {
        $html = "<div class='widget'>";
        $html .= "<h3>Custom Data</h3>";
        $html .= "<p>Display your custom metrics here.</p>";
        $html .= "</div>";
        return $html;
    }
}

Step 3: Enable the Module

Install and enable your module via:

  • Home > Setup > Modules

  • Find and activate your new module (mymodule)

Your custom widget should now appear in the dashboard widget selection menu.

8. Adding Widgets to the Dashboard

Once your widget is created or enabled:

  1. Go to Home > Dashboard.

  2. Click "Add Widget" or use the configuration icon.

  3. Select your custom widget from the list.

  4. Drag and drop to reposition.

You can add multiple instances of the same widget with different configurations.

9. Advanced Customization Techniques

You can enhance your widgets by integrating:

  • AJAX calls to fetch dynamic data

  • Charts using libraries like Chart.js

  • User-specific filters

  • Date range selectors

Example with Chart.js:

$html .= "<canvas id='salesChart'></canvas>";
$html .= "<script> new Chart(document.getElementById('salesChart'), { type: 'bar', data: {...} }); </script>";

Ensure any third-party libraries are properly enqueued using Dolibarr’s asset management system.

10. Managing User-Specific Dashboards

Dolibarr allows dashboards to be customized per user:

  • Each user can select their own set of widgets.

  • Admins can define default widgets for new users.

  • Profiles can be cloned to replicate dashboard configurations across teams.

This flexibility is essential for businesses with diverse roles and departments.

11. Tips for Effective Dashboard Design

When designing dashboards, keep these principles in mind:

  • Clarity: Avoid clutter. Show only relevant data.

  • Consistency: Use similar formatting across widgets.

  • Color coding: Use color to indicate status (e.g., red for overdue tasks).

  • Interactivity: Allow filters, buttons, or links where helpful.

  • Performance: Keep queries optimized to avoid slowing down the interface.

12. Maintaining Your Custom Dashboard

To ensure your dashboard remains effective:

  • Regularly review and update widget data sources

  • Archive or remove unused widgets

  • Track usage to identify valuable components

  • Document your customizations for easier maintenance

This is especially important during Dolibarr updates that may impact your modules.

13. Troubleshooting and Debugging

Common issues when working with custom dashboards include:

  • Widgets not displaying: Check for errors in the widget class or module configuration.

  • Permission issues: Make sure the user has rights to view the data source.

  • Broken layout: Inspect HTML structure and CSS for conflicts.

Use browser developer tools and Dolibarr logs (/dolibarr/documents/dolibarr.log) to investigate problems.

14. Final Thoughts and Best Practices

Custom dashboards in Dolibarr are a game-changer for companies that want to boost efficiency and data visibility. With a bit of development knowledge and strategic planning, you can create dashboards that:

  • Highlight essential data for quick decision-making

  • Improve navigation and usability

  • Support department-specific needs

Best practices include:

  • Starting with built-in widgets before building new ones

  • Keeping user interface clean and functional

  • Regularly updating widgets based on business changes

Dolibarr’s flexibility makes it a great fit for companies of all types. Investing time into custom dashboards pays off in better team performance and a stronger grasp of your operations.