odoo-forge-bundle 0.1.0

package/payload/skills/odoo18-docs/references/docs/developer/reference/frontend/hooks.md

@@ -0,0 +1,341 @@
+---
+title: ""
+source_url: "https://docs.odoo.sbggai.top/developer/reference/frontend/hooks.html"
+---
+
+.. _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:`useAutofocus <frontend/hooks/useAutofocus>`
+     - focus automatically an element referenced by autofocus
+   * - :ref:`useBus <frontend/hooks/usebus>`
+     - subscribe and unsubscribe to a bus
+   * - :ref:`usePager <frontend/hooks/usepager>`
+     - Display the pager of the control panel of a view.
+   * - :ref:`usePosition <frontend/hooks/useposition>`
+     - position an element relative to a target
+   * - :ref:`useSpellCheck <frontend/hooks/useSpellCheck>`
+     - activate spellcheck on focus for input or textarea
+
+.. _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/useAutofocus:
+
+# useAutofocus
+
+## Location
+
+`@web/core/utils/hooks`
+
+## Description
+
+Focus an element referenced by a t-ref="autofocus" in the current component as
+soon as it appears in the DOM and if it was not displayed before.
+
+```javascript
+
+    import { useAutofocus } from "@web/core/utils/hooks";
+
+    class Comp {
+      setup() {
+        this.inputRef = useAutofocus();
+      }
+      static template = "Comp";
+    }
+
+```xml
+
+    <t t-name="Comp">
+      <input t-ref="autofocus" type="text"/>
+    </t>
+
+## API
+
+.. js:function:: useAutofocus()
+
+    :returns: the element reference.
+
+.. _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.
+
+```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/usepager:
+
+# usePager
+
+## Location
+
+`@web/search/pager_hook`
+
+## Description
+
+Display the :ref:`Pager <frontend/pager>` of the control panel of a view. This hooks correctly sets `env.config` to provide the props to the pager.
+
+```javascript
+
+    import { usePager } from "@web/search/pager_hook";
+
+    class CustomView {
+      setup() {
+        const state = owl.hooks.useState({
+          offset: 0,
+          limit: 80,
+          total: 50,
+        });
+        usePager(() => {
+          return {
+            offset: this.state.offset,
+            limit: this.state.limit,
+            total: this.state.total,
+            onUpdate: (newState) => {
+              Object.assign(this.state, newState);
+            },
+          };
+        });
+      }
+    }
+
+## API
+
+.. js:function:: usePager(getPagerProps)
+
+    :param function getPagerProps: function that returns the pager props.
+
+.. _frontend/hooks/useposition:
+
+# usePosition
+
+## Location
+
+`@web/core/position_hook`
+
+## Description
+
+Helps positioning an HTMLElement (the `popper`) relatively to another
+HTMLElement (the `reference`). This hook ensures the positioning is updated when
+the window is resized/scrolled.
+
+```javascript
+
+    import { usePosition } from "@web/core/position_hook";
+    import { Component, xml } from "@odoo/owl";
+
+    class MyPopover extends Component {
+      static template = xml`
+        <div t-ref="popper">
+          I am positioned through a wonderful hook!
+        </div>
+      `;
+
+      setup() {
+        // Here, the reference is the target props, which is an HTMLElement
+        usePosition(this.props.target);
+      }
+    }
+
+> **important**:
+>    You should indicate your `popper` element using a [t-ref directive ](https://github.com/odoo/owl/blob/master/doc/reference/hooks.md#useref).
+
+## 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
+     - this is a [useRef reference ](https://github.com/odoo/owl/blob/master/doc/reference/hooks.md#useref) for the element that will get positioned.
+       Default is `"popper"`.
+   * - `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`
+     - Direction[-Variant]
+     - the desired position. It is a string composed of one `Direction` and one
+       `Variant` separated by a dash character.
+       `Direction` could be: `top`, `bottom`, `right`, `left`.
+       `Variant` could be: `start`, `middle`, `end`, `fit`.
+       The variant can be omitted (default variant is `middle`).
+       The `fit` variant means that the popper would have the exact same width or height,
+       depending on the chosen direction.
+       Examples of valid positions: `right-end`, `top-start`, `left-middle`,
+       `left`, `bottom-fit`. (default position: `bottom`)
+   * - `onPositioned`
+     - (el: HTMLElement, position: PositioningSolution) => void
+     - a callback that will be called everytime a positioning occurs
+       (e.g. on component mounted/patched, document scroll, window resize...).
+       Can be used i.e. for dynamic styling regarding the current position.
+       The `PositioningSolution` is an object having the following type:
+       `{ direction: Direction, variant: Variant, top: number, left: number }`.
+
+.. example::
+
+   ```javascript
+
+      import { Component, xml, useRef } from "@odoo/owl";
+      import { usePosition } from "@web/core/position_hook";
+
+      class DropMenu extends Component {
+        static template = xml`
+          <button t-ref="toggler">Toggle Menu</button>
+          <div t-ref="menu">
+            <t t-slot="default">
+              This is the menu default content.
+            </t>
+          </div>
+        `;
+
+        setup() {
+          const toggler = useRef("toggler");
+          usePosition(
+            () => toggler.el,
+            {
+              popper: "menu",
+              position: "right-start",
+              onPositioned: (el, { direction, variant }) => {
+                el.classList.add(`dm-${direction}`); // -> "dm-top" "dm-right" "dm-bottom" "dm-left"
+                el.style.backgroundColor = variant === "middle" ? "red" : "blue";
+              },
+            },
+          );
+        }
+      }
+
+.. _frontend/hooks/useSpellCheck:
+
+# useSpellCheck
+
+## Location
+
+`@web/core/utils/hooks`
+
+## Description
+
+Activate the spellcheck state to an input or textarea on focus by a `t-ref="spellcheck"` in
+the current component. This state is then removed on blur, as well as the red outline, which
+improves readability of the content.
+
+The hook can also be used on any HTML element with the `contenteditable` attribute. To disable
+spellcheck completely on elements that might be enabled by the hook, set explicitly the
+`spellcheck` attribute as `false` on the element.
+
+.. example::
+
+   In the following example, the spellcheck will be enabled on the first input, the textarea and
+   the div with `contenteditable="true"`.
+
+   ```javascript
+
+       import { useSpellCheck } from "@web/core/utils/hooks";
+
+       class Comp {
+         setup() {
+           this.simpleRef = useSpellCheck();
+           this.customRef = useSpellCheck({ refName: "custom" });
+           this.nodeRef = useSpellCheck({ refName: "container" });
+         }
+         static template = "Comp";
+       }
+
+   ```xml
+
+       <t t-name="Comp">
+         <input t-ref="spellcheck" type="text"/>
+         <textarea t-ref="custom"/>
+         <div t-ref="container">
+           <input type="text" spellcheck="false"/>
+           <div contenteditable="true"/>
+         </div>
+       </t>
+
+## API
+
+.. js:function:: useSpellCheck([options])
+
+    :param Options options: the spellcheck options (see table below)
+
+.. list-table::
+   :widths: 20 20 60
+   :header-rows: 1
+
+   * - Option
+     - Type
+     - Description
+   * - `refName`
+     - string
+     - this is a [useRef reference ]({OWL_PATH}/doc/reference/hooks.md#useref) for the element that will be
+       spellcheck enabled.

package/payload/skills/odoo18-docs/references/docs/developer/reference/frontend/javascript_modules.md

@@ -0,0 +1,361 @@
+---
+title: ""
+source_url: "https://docs.odoo.sbggai.top/developer/reference/frontend/javascript_modules.html"
+---
+
+.. _frontend/js_modules:
+# 
+# Javascript Modules
+
+Odoo supports three different kinds of javascript files:
+
+- :ref:`plain javascript files <frontend/modules/plain_js>` (no module system),
+- :ref:`native javascript module <frontend/modules/native_js>`.
+- :ref:`Odoo modules <frontend/modules/odoo_module>` (using a custom module system),
+
+As described in the :ref:`assets management page <reference/assets>`,
+all javascript files are bundled together and served to the browser.
+Note that native javascript files are processed by the Odoo server and transformed into Odoo custom modules.
+
+Let us briefly explain the purpose behind each kind of javascript file. Plain
+javascript files should be reserved only for external libraries and some small
+specific low level purposes. All new javascript files should be created in the
+native javascript module system. The custom module system is only useful for old,
+not yet converted files.
+
+.. _frontend/modules/plain_js:
+
+# Plain Javascript files
+
+Plain javascript files can contain arbitrary content. It is advised to use the
+*iife* :dfn:`immediately invoked function execution` style when writing such a file:
+
+```javascript
+
+  (function () {
+    // some code here
+    let a = 1;
+    console.log(a);
+  })();
+
+The advantages of such files is that we avoid leaking local variables to the
+global scope.
+
+Clearly, plain javascript files do not offer the benefits of a module system, so
+one needs to be careful about the order in the bundle (since the browser will
+execute them precisely in that order).
+
+> **note**:
+>   In Odoo, all external libraries are loaded as plain javascript files.
+
+.. _frontend/modules/native_js:
+
+# Native Javascript Modules
+
+Odoo javascript code uses the native javascript module system. This is simpler, and
+brings the benefits of a better developer experience with a better integration with the IDE.
+
+Let us consider the following module, located in :file:`web/static/src/file_a.js`:
+
+```javascript
+
+  import { someFunction } from "./file_b";
+
+  export function otherFunction(val) {
+      return someFunction(val + 3);
+  }
+
+There is a very important point to know: by default Odoo transpiles files under
+`/static/src` and `/static/tests` into :ref:`Odoo modules <frontend/modules/odoo_module>`.
+This file will then be transpiled into an Odoo module that looks like this:
+
+```javascript
+
+   odoo.define('@web/file_a', ['@web/file_b'], function (require) {
+   'use strict';
+   let __exports = {};
+
+   const { someFunction } = require("@web/file_b");
+
+   __exports.otherFunction = function otherFunction(val) {
+      return someFunction(val + 3);
+   };
+
+   return __exports;
+   )};
+
+So, as you can see, the transformation is basically adding `odoo.define` on top
+and updating the import/export statements. This is an opt-out system, it's possible
+to tell the transpiler to ignore the file.
+
+```javascript
+
+  /** @odoo-module ignore **/
+  (function () {
+    const sum = (a, b) => a + b;
+    console.log(sum(1, 2));
+  )();
+
+Note the comment in the first line: it describes that this file should be ignored.
+
+In other folders, files aren't transpiled by default, it is opt-in. Odoo will look at the
+first line of a JS file and check if it contains a comment with *@odoo-module* and without
+the tag *ignore*. If so, it will automatically be converted to an Odoo module.
+
+```javascript
+
+  /** @odoo-module **/
+  export function sum(a, b) {
+    return a + b;
+  }
+
+Another important point is that the transpiled module has an official name:
+*@web/file_a*. This is the actual name of the module. Every relative imports
+will be converted as well. Every file located in an Odoo addon
+:file:`some_addon/static/src/path/to/file.js` will be assigned a name prefixed by the
+addon name like this: *@some_addon/path/to/file*.
+
+Relative imports work, but only if the modules are in the same Odoo addon. So, imagine that we have
+the following file structure:
+
+::
+
+  addons/
+      web/
+          static/
+              src/
+                  file_a.js
+                  file_b.js
+      stock/
+          static/
+              src/
+                  file_c.js
+
+The file :file:`file_b` can import :file:`file_a` like this:
+
+```javascript
+
+  import {something} from `./file_a`;
+
+But :file:`file_c` need to use the full name:
+
+```javascript
+
+  import {something} from `@web/file_a`;
+
+## Aliased modules
+
+Because :ref:`Odoo modules <frontend/modules/odoo_module>` follow a different module naming pattern, a system exists to allow a smooth
+transition towards the new system. Currently, if a file is converted to a module (and therefore
+follow the new naming convention), other files not yet converted to ES6-like syntax in the project
+won't be able to require the module. Aliases are here to map old names with new ones by creating a
+small proxy function. The module can then be called by its new *and* old name.
+
+To add such alias, the comment tag on top of the file should look like this:
+
+```javascript
+
+  /** @odoo-module alias=web.someName**/
+  import { someFunction } from './file_b';
+
+  export default function otherFunction(val) {
+      return someFunction(val + 3);
+  }
+
+Then, the translated module will also create an alias with the requested name:
+
+```javascript
+
+  odoo.define(`web.someName`, ['@web/file_a'], function(require) {
+      return require('@web/file_a')[Symbol.for("default")];
+  });
+
+The default behaviour of aliases is to re-export the `default` value of the
+module they alias. This is because "classic" modules generally export a single
+value which would be used directly, roughly matching the semantics of default
+exports.
+However it is also possible to delegate more directly, and follow the exact
+behaviour of the aliased module:
+
+```javascript
+
+  /** @odoo-module alias=web.someName default=0**/
+  import { someFunction } from './file_b';
+
+  export function otherFunction(val) {
+      return someFunction(val + 3);
+  }
+
+In that case, this will define an alias with exactly the values exported by the
+original module:
+
+```javascript
+
+  odoo.define(`web.someName`, ["@web/file_a"], function(require) {
+      return require('@web/file_a');
+  });
+
+> **note**:
+>    Only one alias can be defined using this method. If you were to need another one to have, for
+   example, three names to call the same module, you would have to add a proxy manually.
+   This is not good practice and should be avoided unless there is no other options.
+
+## Limitations
+
+For performance reasons, Odoo does not use a full javascript
+parser to transform native modules. There are, therefore, a number of limitations including but not
+limited to:
+
+- an `import` or `export` keyword cannot be preceded by a non-space character,
+- a multiline comment or string cannot have a line starting by `import` or `export`
+
+  ```javascript
+
+    // supported
+    import X from "xxx";
+    export X;
+      export default X;
+        import X from "xxx";
+
+    /*
+     * import X ...
+     */
+
+    /*
+     * export X
+     */
+
+
+    // not supported
+
+    var a= 1;import X from "xxx";
+    /*
+      import X ...
+    */
+
+- when you export an object, it can't contain a comment
+
+  ```javascript
+
+      // supported
+      export {
+        a as b,
+        c,
+        d,
+      }
+
+      export {
+        a
+      } from "./file_a"
+
+
+      // not supported
+      export {
+        a as b, // this is a comment
+        c,
+        d,
+      }
+
+      export {
+        a /* this is a comment */
+      } from "./file_a"
+
+- Odoo needs a way to determine if a module is described by a path (like :file:`./views/form_view`)
+  or a name (like `web.FormView`). It has to use a heuristic to do just that: if there is a `/` in
+  the name, it is considered a path.  This means that Odoo does not really support module names with
+  a `/` anymore.
+
+As "classic" modules are not deprecated and there is currently no plan to remove them, you can and should keep using
+them if you encounter issues with, or are constrained by the limitations of, native modules. Both styles can coexist
+within the same Odoo addon.
+
+
+.. _frontend/modules/odoo_module:
+
+# Odoo Module System
+
+Odoo has defined a small module system (located in the file
+:file:`addons/web/static/src/js/boot.js`, which needs to be loaded first). The Odoo
+module system, inspired by AMD, works by defining the function `define`
+on the global odoo object. We then define each javascript module by calling that
+function.  In the Odoo framework, a module is a piece of code that will be executed
+as soon as possible.  It has a name and potentially some dependencies.  When its
+dependencies are loaded, a module will then be loaded as well.  The value of the
+module is then the return value of the function defining the module.
+
+As an example, it may look like this:
+
+```javascript
+
+    // in file a.js
+    odoo.define('module.A', [], function (require) {
+        "use strict";
+
+        var A = ...;
+
+        return A;
+    });
+
+    // in file b.js
+    odoo.define('module.B', ['module.A'], function (require) {
+        "use strict";
+
+        var A = require('module.A');
+
+        var B = ...; // something that involves A
+
+        return B;
+    });
+
+
+If some dependencies are missing/non ready, then the module will simply not be
+loaded.  There will be a warning in the console after a few seconds.
+
+Note that circular dependencies are not supported. It makes sense, but it means that one
+needs to be careful.
+
+## Defining a module
+
+The `odoo.define` method is given three arguments:
+
+- `moduleName`: the name of the javascript module.  It should be a unique string.
+  The convention is to have the name of the odoo addon followed by a specific
+  description. For example, `web.Widget` describes a module defined in the `web`
+  addon, which exports a `Widget` class (because the first letter is capitalized)
+
+  If the name is not unique, an exception will be thrown and displayed in the
+  console.
+
+- `dependencies`: It should be a list of strings, each corresponding to a
+  javascript module.  This describes the dependencies that are required to
+  be loaded before the module is executed.
+
+- finally, the last argument is a function which defines the module. Its return
+  value is the value of the module, which may be passed to other modules requiring
+  it.
+
+  ```javascript
+
+     odoo.define('module.Something', ['web.ajax'], function (require) {
+         "use strict";
+
+         var ajax = require('web.ajax');
+
+         // some code here
+         return something;
+     });
+
+If an error happens, it will be logged (in debug mode) in the console:
+
+* `Missing dependencies`:
+  These modules do not appear in the page. It is possible that the JavaScript
+  file is not in the page or that the module name is wrong
+* `Failed modules`:
+  A javascript error is detected
+* `Rejected modules`:
+  The module returns a rejected Promise. It (and its dependent modules) is not
+  loaded.
+* `Rejected linked modules`:
+  Modules who depend on a rejected module
+* `Non loaded modules`:
+  Modules who depend on a missing or a failed module