trans($experimentName); ?> : trans('UxDolibarrContextHowItWork'); ?>

Introduction

DolibarrContext is a secure global JavaScript context for Dolibarr. It provides a single global object window.Dolibarr, which cannot be replaced. It allows defining non-replaceable tools and managing hooks/events in a modular and secure way.

This system is designed to provide long-term flexibility and maintainability. You can define reusable tools that encapsulate functionality such as standardized AJAX requests and responses, ensuring consistent data handling across Dolibarr modules. For example, tools can be created to wrap API calls and automatically process returned data in a uniform format, reducing repetitive code and preventing errors.

Beyond DOM-based events, DolibarrContext allows monitoring and reacting to business events using a hook-like mechanism. For instance, you can listen to events such as Dolibarr.on('addline:load:productPricesList', function(data) { ... }); without relying on DOM changes. This enables creating logic that reacts directly to application state changes.

Similarly, you can define tools that act as global helpers, like Dolibarr.tools.setEventMessage(). This tool can display notifications (similar to PHP's setEventMessage() in Dolibarr), initially using jNotify or any other library. In the future, the underlying library can change without affecting the way modules or external code call this tool, maintaining compatibility and reducing maintenance.

In summary, DolibarrContext provides a secure, extensible foundation for adding tools, monitoring business events, and standardizing interactions across Dolibarr's frontend modules.

Console help

Open your browser console with F12 to view the available commands.
If the help does not appear automatically, type Dolibarr.tools.showConsoleHelp(); in the console to display it.

Dolibarr.log() and debugMode()

Dolibarr.log() is a lightweight logging utility provided by the Dolibarr JS context. It does not replace console.log(), but it gives an important advantage: you can enable or disable all logs globally using Dolibarr.debugMode().

Why use Dolibarr.log() instead of console.log()?

• You can enable or disable logging dynamically from the browser console.
• Avoid polluting the console for end-users: logs appear only when debug mode is enabled.
• Ideal for module development: switch between quiet mode and verbose mode instantly.
• Useful in production debugging: you can activate logs without modifying any code.

How it works

When debugMode is disabled (default state), calls to Dolibarr.log() do nothing. When enabled, Dolibarr.log() behaves like console.log().

Summary

• console.log() → always prints messages, noisy, not controllable, but useful during active development and debugging.
• Dolibarr.log() → prints messages only when debug mode is ON; fully controllable. Ideal for Dolibarr core logs or when you want to keep logs available but silent in production.
• Dolibarr.debugMode(true) → enable verbose logs, activating Dolibarr.log() output.
• Dolibarr.debugMode(false) → disable all Dolibarr.log() output, silencing debug messages.

JS Dolibarr hooks

Dolibarr provides a hook system to allow modules and scripts to communicate with each other through named events. There are two ways to listen to these events in JS: Dolibarr.on() and document.addEventListener().

Event listener example

You can use Dolibarr.on() to listen to a hook. The main difference with standard document events is that the callback receives directly the data object passed when the hook is executed, without needing to access e.detail.

For backward compatibility and standard DOM integration, the same hook can also be caught using document.addEventListener(), but in this case the data is inside e.detail and the event name is prefixed by Dolibarr: so for a hook named A event name is Dolibarr:A

Practical usage

When Dolibarr is ready (DOM loaded and JS context initialized), you can register your hooks or trigger them. Both Dolibarr.on() and document.addEventListener() are valid, but Dolibarr.on() is simpler and more convenient because you get the data directly.

Difference between Dolibarr:Init and Dolibarr:Ready event

Dolibarr provides two main initialization events for its JavaScript context: Dolibarr:Init and Dolibarr:Ready. Understanding their difference is important when developing modules or tools.

• Dolibarr:Init is triggered immediately when the Dolibarr context is created. This event is intended for:
  • Defining or registering new tools via Dolibarr.defineTool().
  • Setting context variables (Dolibarr.setContextVar() / Dolibarr.setContextVars()).
  • Preparing configuration that must be available before the DOM is fully loaded.
  It occurs before Dolibarr:Ready, so it is ideal for setup tasks that other tools may depend on.
• Dolibarr:Ready is triggered once the DOM is ready, similar to $(document).ready() in jQuery. This event is intended for:
  • Running code that interacts with the DOM.
  • Attaching event listeners to elements on the page.
  • Executing functionality that requires all tools and context variables to be fully initialized.

In short, use Dolibarr:Init for setting up tools and context variables, and Dolibarr:Ready for code that needs the DOM and fully initialized context.

Examples of usage

In summary:

• Dolibarr:Init → early setup, tools, context variables, configuration.
• Dolibarr:Ready → DOM is ready, safe to manipulate elements and use tools defined in Init.

Async Hooks (Await Hooks) - sequential execution

Dolibarr supports asynchronous hooks using Dolibarr.onAwait() and Dolibarr.executeHookAwait(). These hooks allow you to register functions that execute in sequence and can modify data before passing it to the next hook. They are useful for complex workflows where multiple modules or scripts need to process or enrich the same data asynchronously.

Each hook can optionally specify before or after to control the execution order relative to other hooks. Every hook registration returns a unique id, which can be used to reference or unregister the hook later.

Unlike standard synchronous hooks registered with Dolibarr.on(), await hooks return a Promise when executed. This means you can await their results in your code, and any asynchronous operations inside a hook (e.g., API calls, timers) will be handled correctly before moving to the next hook.

Example of creating a new context tool

Defining Tools

You can define reusable and protected tools in the Dolibarr context using Dolibarr.defineTool.

See also dolibarr-context.mock.js for defining all standard Dolibarr tools and creating mock implementations to improve code completion and editor support.

Note : a tool can be a class not only a function

Protected Tools

Once a tool is defined on overwrite false, it cannot be replaced. Attempting to redefine it without overwrite will throw an error:

Reading Tools

You can read the list of available tools using Dolibarr.tools. It returns a frozen copy:

Set event message tool

Instead of calling JNotify directly in your code, use Dolibarr’s setEventMessage tool. Dolibarr provides the configuration option DISABLE_JQUERY_JNOTIFY, which disables the jQuery JNotify system, usually because another notification library will be used instead.

If you rely on Dolibarr.tools.setEventMessage(), your code remains compatible even if the underlying notification system changes. The setEventMessage tool can be replaced internally without requiring any changes in your modules or custom scripts.

This means all developers can write features without worrying about frontend compatibility or future library replacements. Enjoy!

Set and use context vars

The Context Vars system allows you to define and manage variables that are globally accessible within the Dolibarr JavaScript context. These variables can store configuration data, URLs, tokens, user IDs, object references, or any other values needed by your frontend code and tools. By using context vars, you can:

• Pass server-side data (from PHP) to JavaScript safely and consistently.
• Provide reusable configuration for Dolibarr tools, widgets, or modules without hardcoding values.
• Define overridable or non-overridable vars to protect critical values while allowing flexible overrides when necessary.
• Use Dolibarr.setContextVar for single values or Dolibarr.setContextVars to pass multiple values at once.
• Access these variables anywhere in your code via Dolibarr.getContextVar(key).
• Ensure that all your modules and tools can rely on consistent and up-to-date context information, improving maintainability and interoperability.

Add context var (overridable or not)

Add multiple context vars (overridable or not)

Get context var