[ADD] developer: add new page on registries (js)

closes odoo/documentation#1216

X-original-commit: a5a669a5eb
Signed-off-by: Géry Debongnie (ged) <ged@openerp.com>

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

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 <javascript/registries/api/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,
+   });