156 lines
4.3 KiB
ReStructuredText
156 lines
4.3 KiB
ReStructuredText
.. _frontend/hooks:
|
|
|
|
=====
|
|
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.
|
|
|
|
.. list-table::
|
|
:widths: 30 70
|
|
:header-rows: 1
|
|
|
|
* - Name
|
|
- Short Description
|
|
* - :ref:`useAssets <frontend/hooks/useassets>`
|
|
- load assets
|
|
* - :ref:`useBus <frontend/hooks/usebus>`
|
|
- subscribe and unsubscribe to a bus
|
|
* - :ref:`usePosition <frontend/hooks/useposition>`
|
|
- position an element relative to a target
|
|
|
|
.. _frontend/hooks/useassets:
|
|
|
|
useAssets
|
|
=========
|
|
|
|
Location
|
|
--------
|
|
|
|
`@web/core/assets`
|
|
|
|
Description
|
|
-----------
|
|
|
|
See the section on :ref:`lazy loading assets <frontend/assets/lazy_loading>` for
|
|
more details.
|
|
|
|
.. _frontend/hooks/usebus:
|
|
|
|
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
|
|
|
|
.. _frontend/hooks/useposition:
|
|
|
|
usePosition
|
|
===========
|
|
|
|
Location
|
|
--------
|
|
|
|
`@web/core/position/position_hook`
|
|
|
|
Description
|
|
-----------
|
|
|
|
Helps positioning a component (or a specific HTMLElement) relatively to a target
|
|
HTMLElement. This hook ensures the positioning is updated when the window is
|
|
resized/scrolled.
|
|
|
|
.. code-block:: javascript
|
|
|
|
import { usePosition } from "@web/core/position/position_hook";
|
|
|
|
class MyPopover {
|
|
setup() {
|
|
// Here, the target is an HTMLElement
|
|
usePosition(this.props.target);
|
|
}
|
|
}
|
|
MyPopover.template = owl.tags.xml`<div>I am positioned through a wonderful hook!</div>`
|
|
|
|
|
|
.. note::
|
|
The following CSS classes can be used to style the target HTMLElement:
|
|
|
|
- `o-popper-position`
|
|
- `o-popper-position--{D}{V}` where `{D}` and `{V}` are replaced by the first letter of the corresponding Direction and Variant (see Options table below for valid directions and variants). E.g.: for position `bottom-end`, the class name will be `o-popper-position--be`.
|
|
|
|
API
|
|
---
|
|
|
|
.. js:function:: usePosition(reference[, options])
|
|
|
|
:param reference: the target HTMLElement to be positioned from
|
|
:type reference: HTMLElement or ()=>HTMLElement
|
|
:param Options options: the positioning options (see table below)
|
|
|
|
.. list-table::
|
|
:widths: 20 20 60
|
|
:header-rows: 1
|
|
|
|
* - Option
|
|
- Type
|
|
- Description
|
|
* - `popper`
|
|
- string | undefined
|
|
- this is the element that will get positioned. You can provide here a
|
|
`useRef reference <https://github.com/odoo/owl/blob/master/doc/reference/hooks.md#useref>`_.
|
|
If not provided, `this.el` is used (default: `undefined`).
|
|
* - `container`
|
|
- HTMLElement
|
|
- the container from which the popper is expected not to overflow. If
|
|
overflowing occurs, other popper positions are tried until a not
|
|
overflowing one is found. (default: the `<html/>` node)
|
|
* - `margin`
|
|
- number
|
|
- added margin between popper and reference elements (default: `0`)
|
|
* - `position`
|
|
- string
|
|
- the desired position. It is a string composed of one direction and one
|
|
variant separated by a dash character. Valid directions are: `top`,
|
|
`bottom`, `right`, `left`. Valid variants are: `start`,
|
|
`middle`, `end`. The variant can be omitted (default variant is
|
|
`middle`). Examples of valid positions: `right-end`, `top-start`,
|
|
`left-middle`, `left`. (default position: `bottom`)
|