From 1f84bab97d8bbbdd069d50f696e1eff9a9489a8c Mon Sep 17 00:00:00 2001
From: luvi <luvi@odoo.com>
Date: Mon, 15 Nov 2021 11:27:45 +0000
Subject: [PATCH] [ADD] developer: scroller service added
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This commit adds the documentation related to
the scroller service. This service is used for
the webclient to handle clicks on links and there
were no documentation related until now.

closes odoo/documentation#1313

Signed-off-by: Géry Debongnie (ged) <ged@openerp.com>
---
 .../developer/reference/frontend/services.rst | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/content/developer/reference/frontend/services.rst b/content/developer/reference/frontend/services.rst
index b537d3660..89a8fecf7 100644
--- a/content/developer/reference/frontend/services.rst
+++ b/content/developer/reference/frontend/services.rst
@@ -128,6 +128,8 @@ Reference List
      - manage the browser url
    * - :ref:`rpc <frontend/services/rpc>`
      - send requests to the server
+   * - :ref:`scroller <frontend/services/scroller>`
+     - handle clicks on anchors elements
    * - :ref:`title <frontend/services/title>`
      - read or modify the window title
    * - :ref:`user <frontend/services/user>`
@@ -692,6 +694,57 @@ When a rpc fails, then:
   displayed and the server is regularly contacted until it responds. The
   notification is closed as soon as the server responds.
 
+.. _frontend/services/scroller:
+
+Scroller service
+----------------
+
+Overview
+~~~~~~~~
+
+- Technical name: `scroller`
+- Dependencies: none
+
+Whenever the user clicks on an anchor in the web client, this service automatically scrolls
+to the target (if appropriate).
+
+The service adds an event listener to get `click`'s on the document. The service checks
+if the selector contained in its href attribute is valid to distinguish anchors and Odoo 
+actions (e.g. `<a href="#target_element"></a>`). It does nothing if it is not the case.
+
+An event `SCROLLER:ANCHOR_LINK_CLICKED` is triggered on the main application bus if the click seems to be 
+targeted at an element. The event contains a custom event containing the `element` matching and its `id` as a reference.
+It may allow other parts to handle a behavior relative to anchors themselves. The original event is also 
+given as it might need to be prevented. If the event is not prevented, then the user interface will 
+scroll to the target element.
+
+API
+~~~
+
+The following values are contained in the `anchor-link-clicked` custom event explained above.
+
+.. list-table::
+    :widths: 25 25 50
+    :header-rows: 1
+
+    * - Name 
+      - Type
+      - Description
+    * - `element`
+      - `HTMLElement | null`
+      - The anchor element targeted by the href
+    * - `id`
+      - `string`
+      - The id contained in the href
+    * - `originalEv`
+      - `Event`
+      - The original click event
+
+.. note::
+   The scroller service emits a `SCROLLER:ANCHOR_LINK_CLICKED` event on the :ref:`main bus <frontend/framework/bus>`.
+   To avoid the default scroll behavior of the scroller service, you must use `preventDefault()` on the event given
+   to the listener so that you can implement your own behavior correctly from the listener.
+
 .. _frontend/services/title:
 
 Title Service