From eea6a94411c0e5dccbe494ef3154bd403bb9f032 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= <ged@odoo.com>
Date: Fri, 22 Oct 2021 09:34:44 +0000
Subject: [PATCH] [ADD] developer: add a reference page on hooks (js)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

closes odoo/documentation#1208

Signed-off-by: Géry Debongnie (ged) <ged@openerp.com>
---
 content/developer/reference/javascript.rst    |  1 +
 .../developer/reference/javascript/hooks.rst  | 49 +++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 content/developer/reference/javascript/hooks.rst

diff --git a/content/developer/reference/javascript.rst b/content/developer/reference/javascript.rst
index eacd15c6e..3a054de50 100644
--- a/content/developer/reference/javascript.rst
+++ b/content/developer/reference/javascript.rst
@@ -13,6 +13,7 @@ Javascript
     javascript/registries
     javascript/services
     javascript/generic_components
+    javascript/hooks
     javascript/javascript_cheatsheet
     javascript/javascript_reference
     javascript/mobile
diff --git a/content/developer/reference/javascript/hooks.rst b/content/developer/reference/javascript/hooks.rst
new file mode 100644
index 000000000..c43235a09
--- /dev/null
+++ b/content/developer/reference/javascript/hooks.rst
@@ -0,0 +1,49 @@
+=====
+Hooks
+=====
+
+`Owl hooks <https://github.com/odoo/owl/blob/master/doc/reference/hooks.md>`_ are a
+way to factorize code, even if it depends on some component lifecycle. Most hooks
+provided by Owl are related to the lifecycle of a component, but some of them (such as 
+`useComponent <https://github.com/odoo/owl/blob/master/doc/reference/hooks.md#usecomponent>`_)
+provide a way to build specific hooks.
+
+Using these hooks, it is possible to build many customized hooks that help solve
+a specific problem, or make some common tasks easier. The rest of this page
+documents the list of hooks provided by the Odoo web framework.
+
+useBus
+======
+
+Location
+--------
+
+`@web/core/utils/hooks`
+
+Description
+-----------
+
+Add and clear an event listener to a bus. This hook ensures that
+the listener is properly cleared when the component is unmounted.
+
+.. code-block:: javascript
+
+    import { useBus } from "@web/core/utils/hooks";
+
+    class MyComponent {
+      setup() {
+        useBus(this.env.bus, "some-event", event => {
+          console.log(event);
+        });
+      }
+    }
+
+API
+---
+
+.. js:function:: useBus(bus, eventName, callback)
+
+    :param EventBus bus: the target event bus
+    :param string eventName: the name of the event that we want to listen to
+    :param function callback: listener callback
+