+ 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.
+
+
+
+ ">',
+ ' document.addEventListener(\'Dolibarr:Ready\', async function(e) {',
+ '',
+ ' // Register async hooks will be executed in first place',
+ ' Dolibarr.onAwait(\'calculateDiscount\', async function(order) {',
+ ' order.total *= 0.9; // Apply 10% discount',
+ ' return order;',
+ ' }, { id: \'discount10\' });',
+ '',
+ ' // Register async hooks will be executed in third place',
+ ' Dolibarr.onAwait(\'calculateDiscount\', async function(order) {',
+ ' if(order.total > 1000) order.total -= 50; // Extra discount over 1000',
+ ' return order;',
+ ' }, { id: \'discountOver1000\', after: \'discount10\' });',
+ '',
+ ' // Register async hooks will be executed in second place',
+ ' // this hook item as no id so plus10HookItemId will receive a unique random id ',
+ ' let plus10HookItemId = Dolibarr.onAwait(\'calculateDiscount\', async function(order) {',
+ ' order.newObjectAttribute = \'My value\';',
+ ' order.total += 10;',
+ ' return order;',
+ ' }, { before: \'discountOver1000\' });',
+ '',
+ ' document.getElementById(\'try-event-yourCustomAwaitHookName\').addEventListener(\'click\', async function(e) {',
+ ' // Execute all registered await hooks sequentially',
+ ' let order = {total: 1200};',
+ ' order = await Dolibarr.executeHookAwait(\'calculateDiscount\', order);',
+ ' console.log(order); // order.total : 1200 -> 1080 -> 1090 -> 1040',
+ ' });',
+ '',
+ ' });',
+ '',
+ );
+ echo $documentation->showCode($lines, 'php'); ?>
+
+ Open your console F12 and click on
+
+
+
+
+
+
+
+
+
+
Difference between Dolibarr:Init and Dolibarr:Ready
+
+
+ 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().
Preparing configuration that must be available before the DOM is fully loaded.
+
+ It occurs beforeDolibarr: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.
+
+
+
+
+
+
+
+
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
',
+ 'document.addEventListener(\'Dolibarr:Init\', function(e) {',
' // Define a simple tool',
' let overwrite = false; // Once a tool is defined, it cannot be replaced.',
' Dolibarr.defineTool(\'alertUser\', (msg) => alert(\'[Dolibarr] \' + msg), overwrite);',
+ '});',
'',
+ 'document.addEventListener(\'Dolibarr:Ready\', function(e) {',
' // Use the tool',
' Dolibarr.tools.alertUser(\'hello world\');',
+ '});',
'',
);
echo $documentation->showCode($lines, 'php'); ?>
-