diff --git a/content/developer/reference/javascript.rst b/content/developer/reference/javascript.rst index 356caa3a2..eb7426972 100644 --- a/content/developer/reference/javascript.rst +++ b/content/developer/reference/javascript.rst @@ -10,6 +10,7 @@ Javascript javascript/framework_overview javascript/javascript_modules javascript/owl_component_system + javascript/registries javascript/services javascript/javascript_cheatsheet javascript/javascript_reference diff --git a/content/developer/reference/javascript/registries.rst b/content/developer/reference/javascript/registries.rst new file mode 100644 index 000000000..14e24cdc0 --- /dev/null +++ b/content/developer/reference/javascript/registries.rst @@ -0,0 +1,135 @@ +========== +Registries +========== + +Registries are (ordered) key/value maps. They are the main web client extension +points: many features provided by the Odoo javascript framework simply look up +into a registry whenever it needs a definition for some object (such as fields, +views, client actions or services). Customizing the web client is then simply +done by adding specific values in the correct registry. + +.. code-block:: javascript + + import { Registry } from "@web/core/registry"; + + const myRegistry = new Registry(); + + registry.add("hello", "odoo"); + + console.log(registry.get("hello")); + +A useful feature of registries is that they maintain a set of sub registries, +obtained by the `category` method. If the sub registry does not exist yet, it +is created on the fly. All registries used by the web client are obtained +in such a way from one root registry, exported in `@web/core/registry`. + +.. code-block:: javascript + + import { registry } from "@web/core/registry"; + + const fieldRegistry = registry.category("fields"); + const serviceRegistry = registry.category("services"); + const viewRegistry = registry.category("views"); + +Registry API +============ + +constructor() + .. code-block:: + + @returns {Registry} + + creates a new registry. Note that a registry is an event bus, so one can + listen to the `UPDATE` event if necessary. + + Registries are ordered: the :ref:`getAll ` method returns a list of values ordered + according to their sequence number. + +add(key, value, options) + .. code-block:: + + @param {string} key + @param {any} value + @param {{force?: boolean, sequence?: number}} [options] + @returns {Registry} + + Inserts a value at a specific key. If the key is already used, this method + throws an error (unless the option `force` is set to true). The option + `sequence` is useful to insert the value at a specific position. This method + also triggers an `UPDATE` event. + + Returns the same registry, so `add` method calls can be chained. + +get(key, defaultValue) + .. code-block:: + + @param {string} key + @returns {any} + + Returns the value corresponding to the `key` argument. If the registry does + not contain that key, this method returns `defaultValue` if given, or throws + an error otherwise. + +contains(key) + .. code-block:: + + @param {string} key + @returns {boolean} + + Returns `true` if the `key` is present in the registry + +.. _javascript/registries/api/getAll: + +getAll() + .. code-block:: + + @returns {any[]} + + Returns the list of all elements in the registry. Note that it is ordered + according to the sequence numbers. + +remove(key) + .. code-block:: + + @param {string} key + + Removes a key/value pair from the registry. This operation triggers an + `UPDATE` event. + +category(subcategory) + .. code-block:: + + @param {string} subcategory + @returns {Registry} + + Returns the sub registry associated with the `subcategory`. If it does not + exist yet, the sub registry is created on the fly. + +Reference List +============== + +Main components registry +------------------------ + +The main component registry (`main_components`) is useful for adding top level +components in the web client. The webclient has a `MainComponentsContainer` as +direct child. This component is basically a live representation of the ordered +list of components registered in the main components registry. + +API + .. code-block:: + + interface { + Component: Owl Component class + props?: any + } + + +For example, the `LoadingIndicator` component can be added in the registry like +this: + +.. code-block:: javascript + + registry.category("main_components").add("LoadingIndicator", { + Component: LoadingIndicator, + });