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 ` - send requests to the server + * - :ref:`scroller ` + - handle clicks on anchors elements * - :ref:`title ` - read or modify the window title * - :ref:`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. ``). 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 `. + 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