From 973d5800d2f30e2d3919292ac3406a3fb903f43f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C3=ABl=20Mattiello?= Date: Mon, 5 Feb 2024 09:33:08 +0100 Subject: [PATCH] [IMP] web: update javascript odoo modules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit adapts the javascript modules section with the last update https://github.com/odoo/odoo/pull/142858 and some outdated features. closes odoo/documentation#7640 Signed-off-by: Michaël Mattiello (mcm) --- .../howtos/javascript_client_action.rst | 2 - content/developer/howtos/javascript_field.rst | 4 - content/developer/howtos/javascript_view.rst | 10 -- .../howtos/standalone_owl_application.rst | 2 - .../howtos/website_themes/theming.rst | 10 -- .../developer/reference/backend/testing.rst | 1 - .../reference/frontend/javascript_modules.rst | 122 +++++++----------- .../developer/reference/frontend/services.rst | 2 - .../01_owl_components.rst | 4 - .../02_create_gallery_view.rst | 2 - 10 files changed, 47 insertions(+), 112 deletions(-) diff --git a/content/developer/howtos/javascript_client_action.rst b/content/developer/howtos/javascript_client_action.rst index bbc3238d4..8ae72eacb 100644 --- a/content/developer/howtos/javascript_client_action.rst +++ b/content/developer/howtos/javascript_client_action.rst @@ -25,8 +25,6 @@ framework and use services, core components, hooks,... .. code-block:: js :caption: :file:`my_client_action.js` - /** @odoo-module **/ - import { registry } from "@web/core/registry"; import { Component } from "@odoo/owl"; diff --git a/content/developer/howtos/javascript_field.rst b/content/developer/howtos/javascript_field.rst index 211c4a876..70df6edc3 100644 --- a/content/developer/howtos/javascript_field.rst +++ b/content/developer/howtos/javascript_field.rst @@ -14,8 +14,6 @@ displaying "Late!" in red whenever the checkbox is checked. .. code-block:: javascript :caption: :file:`late_order_boolean_field.js` - /** @odoo-module */ - import { registry } from "@web/core/registry"; import { BooleanField } from "@web/views/fields/boolean/boolean_field"; import { Component, xml } from "@odoo/owl"; @@ -63,8 +61,6 @@ Assume that we want to create a field that displays a simple text in red. .. code-block:: js :caption: :file:`my_text_field.js` - /** @odoo-module */ - import { standardFieldProps } from "@web/views/fields/standard_field_props"; import { Component, xml } from "@odoo/owl"; import { registry } from "@web/core/registry"; diff --git a/content/developer/howtos/javascript_view.rst b/content/developer/howtos/javascript_view.rst index f596211d5..faa784af9 100644 --- a/content/developer/howtos/javascript_view.rst +++ b/content/developer/howtos/javascript_view.rst @@ -14,8 +14,6 @@ can be done in a few steps: .. code-block:: js :caption: :file:`custom_kanban_controller.js` - /** @odoo-module */ - import { KanbanController } from "@web/views/kanban/kanban_controller"; import { kanbanView } from "@web/views/kanban/kanban_view"; import { registry } from "@web/core/registry"; @@ -82,8 +80,6 @@ Creating a new view is an advanced topic. This guide highlight only the essentia .. code-block:: js :caption: :file:`beautiful_controller.js` - /** @odoo-module */ - import { Layout } from "@web/search/layout"; import { useService } from "@web/core/utils/hooks"; import { Component, onWillStart, useState} from "@odoo/owl"; @@ -161,8 +157,6 @@ Creating a new view is an advanced topic. This guide highlight only the essentia .. code-block:: js :caption: :file:`beautiful_model.js` - /** @odoo-module */ - import { KeepLast } from "@web/core/utils/concurrency"; export class BeautifulModel { @@ -199,8 +193,6 @@ Creating a new view is an advanced topic. This guide highlight only the essentia .. code-block:: js :caption: :file:`beautiful_arch_parser.js` - /** @odoo-module */ - import { XMLParser } from "@web/core/utils/xml"; export class BeautifulArchParser extends XMLParser { @@ -219,8 +211,6 @@ Creating a new view is an advanced topic. This guide highlight only the essentia .. code-block:: js :caption: :file:`beautiful_view.js` - /** @odoo-module */ - import { registry } from "@web/core/registry"; import { BeautifulController } from "./beautiful_controller"; import { BeautifulArchParser } from "./beautiful_arch_parser"; diff --git a/content/developer/howtos/standalone_owl_application.rst b/content/developer/howtos/standalone_owl_application.rst index 8eb0f5b51..807b41fe2 100644 --- a/content/developer/howtos/standalone_owl_application.rst +++ b/content/developer/howtos/standalone_owl_application.rst @@ -37,7 +37,6 @@ Then create the JavaScript file for that component in :file:`/your_module/static .. code-block:: js - /** @odoo-module */ import { Component } from "@odoo/owl"; export class Root extends Component { @@ -50,7 +49,6 @@ file. Create the JavaScript file that will mount the app in :file:`/your_module/ .. code-block:: js - /** @odoo-module */ import { whenReady } from "@odoo/owl"; import { mountComponent } from "@web/env"; import { Root } from "./root"; diff --git a/content/developer/howtos/website_themes/theming.rst b/content/developer/howtos/website_themes/theming.rst index 1e563356d..af144d760 100644 --- a/content/developer/howtos/website_themes/theming.rst +++ b/content/developer/howtos/website_themes/theming.rst @@ -591,16 +591,6 @@ Odoo supports three different kinds of JavaScript files: Most new Odoo JavaScript codes should use the native JavaScript module system. It's simpler and brings the benefit of a better developer experience with better integration with the IDE. -.. important:: - Odoo needs to know which files should be translated into :ref:`Odoo modules - ` and which files should not. It's an opt-in system: Odoo looks at the first - line of a JavaScript file and checks if it contains the string `@odoo-module`. If so, - it will automatically be converted to an Odoo module. - -.. code-block:: javascript - - /** @odoo-module **/ - **Declaration** .. code-block:: python diff --git a/content/developer/reference/backend/testing.rst b/content/developer/reference/backend/testing.rst index 9fdd30c6e..20434a67d 100644 --- a/content/developer/reference/backend/testing.rst +++ b/content/developer/reference/backend/testing.rst @@ -585,7 +585,6 @@ Javascript .. code-block:: javascript - /** @odoo-module **/ import tour from 'web_tour.tour'; tour.register('rental_product_configurator_tour', { url: '/web', // Here, you can specify any other starting url diff --git a/content/developer/reference/frontend/javascript_modules.rst b/content/developer/reference/frontend/javascript_modules.rst index 194f46134..c4b2741d1 100644 --- a/content/developer/reference/frontend/javascript_modules.rst +++ b/content/developer/reference/frontend/javascript_modules.rst @@ -51,50 +51,64 @@ execute them precisely in that order). Native Javascript Modules ========================= -Most new Odoo javascript code should use the native javascript module system. This -is simpler, and brings the benefits of a better developer experience with a better -integration with the IDE. +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. -There is a very important point to know: Odoo needs to know which files -should be translated into :ref:`Odoo modules ` and which -files should not be translated. This is an opt-in system: Odoo will look at the -first line of a JS file and check if it contains the string *@odoo-module*. If so, it will -automatically be converted to an Odoo module. - -For example, let us consider the following module, located in :file:`web/static/src/file_a.js`: +Let us consider the following module, located in :file:`web/static/src/file_a.js`: .. code-block:: javascript - /** @odoo-module **/ - import { someFunction } from './file_b'; + import { someFunction } from "./file_b"; export function otherFunction(val) { return someFunction(val + 3); } -Note the comment in the first line: it describes that this file should be converted. -Any file without this comment will be kept as-is (which will most likely be an -error). This file will then be translated into an Odoo module that look like this: +There is a very important point to know: by default Odoo transpiles files under +`/static/src` and `/static/tests` into :ref:`Odoo modules `. +This file will then be transpiled into an Odoo module that looks like this: .. code-block:: javascript - odoo.define('@web/file_a', function (require) { + 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 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. +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. -Another important point is that the translated module has an official name: +.. code-block:: 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. + +.. code-block:: 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 @@ -120,16 +134,13 @@ The file :file:`file_b` can import :file:`file_a` like this: .. code-block:: javascript - /** @odoo-module **/ - import {something} from `./file_a` + import {something} from `./file_a`; But :file:`file_c` need to use the full name: .. code-block:: javascript - /** @odoo-module **/ - import {something} from `@web/file_a` - + import {something} from `@web/file_a`; Aliased modules --------------- @@ -155,7 +166,7 @@ Then, the translated module will also create an alias with the requested name: .. code-block:: javascript - odoo.define(`web.someName`, function(require) { + odoo.define(`web.someName`, ['@web/file_a'], function(require) { return require('@web/file_a')[Symbol.for("default")]; }); @@ -180,7 +191,7 @@ original module: .. code-block:: javascript - odoo.define(`web.someName`, function(require) { + odoo.define(`web.someName`, ["@web/file_a"], function(require) { return require('@web/file_a'); }); @@ -279,7 +290,7 @@ As an example, it may look like this: .. code-block:: javascript // in file a.js - odoo.define('module.A', function (require) { + odoo.define('module.A', [], function (require) { "use strict"; var A = ...; @@ -288,7 +299,7 @@ As an example, it may look like this: }); // in file b.js - odoo.define('module.B', function (require) { + odoo.define('module.B', ['module.A'], function (require) { "use strict"; var A = require('module.A'); @@ -298,20 +309,6 @@ As an example, it may look like this: return B; }); -An alternative way to define a module is to give explicitly a list of dependencies -in the second argument. - -.. code-block:: javascript - - odoo.define('module.Something', ['module.A', 'module.B'], function (require) { - "use strict"; - - var A = require('module.A'); - var B = require('module.B'); - - // some code - }); - 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. @@ -332,12 +329,13 @@ The `odoo.define` method is given three arguments: If the name is not unique, an exception will be thrown and displayed in the console. -- `dependencies`: the second argument is optional. If given, 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. If - the dependencies are not explicitly given here, then the module system will - extract them from the function by calling toString on it, then using a regexp - to find all the `require` statements. +- `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. .. code-block:: javascript @@ -350,11 +348,6 @@ The `odoo.define` method is given three arguments: return something; }); -- 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. Note that there is a small exception for asynchronous modules, see the - next section. - If an error happens, it will be logged (in debug mode) in the console: * `Missing dependencies`: @@ -369,24 +362,3 @@ If an error happens, it will be logged (in debug mode) in the console: Modules who depend on a rejected module * `Non loaded modules`: Modules who depend on a missing or a failed module - -Asynchronous modules --------------------- - -It can happen that a module needs to perform some work before it is ready. For -example, it could do an rpc to load some data. In that case, the module can -simply return a promise. The module system will simply -wait for the promise to complete before registering the module. - -.. code-block:: javascript - - odoo.define('module.Something', function (require) { - "use strict"; - - var ajax = require('web.ajax'); - - return ajax.rpc(...).then(function (result) { - // some code here - return something; - }); - }); diff --git a/content/developer/reference/frontend/services.rst b/content/developer/reference/frontend/services.rst index 80988d736..ea33ee84a 100644 --- a/content/developer/reference/frontend/services.rst +++ b/content/developer/reference/frontend/services.rst @@ -312,8 +312,6 @@ Let's say we want to add an effect that add a sepia look at the page. .. code-block:: javascript - /** @odoo-module **/ - import { registry } from "@web/core/registry"; const { Component, tags } = owl; diff --git a/content/developer/tutorials/discover_js_framework/01_owl_components.rst b/content/developer/tutorials/discover_js_framework/01_owl_components.rst index 827f07ce0..58b522af0 100644 --- a/content/developer/tutorials/discover_js_framework/01_owl_components.rst +++ b/content/developer/tutorials/discover_js_framework/01_owl_components.rst @@ -120,10 +120,6 @@ see how to create a `sub-component <{OWL_PATH}/doc/reference/component.md#sub-co as the component. For example, if we have a `TodoList` component, its code should be in `todo_list.js`, `todo_list.xml` and if necessary, `todo_list.scss` -.. important:: - Don't forget :code:`/** @odoo-module **/` in your JavaScript files. More information on this can - be found :ref:`here `. - .. _tutorials/discover_js_framework/simple_card: 3. A simple `Card` component diff --git a/content/developer/tutorials/master_odoo_web_framework/02_create_gallery_view.rst b/content/developer/tutorials/master_odoo_web_framework/02_create_gallery_view.rst index 9f38f31ab..c33b84c91 100644 --- a/content/developer/tutorials/master_odoo_web_framework/02_create_gallery_view.rst +++ b/content/developer/tutorials/master_odoo_web_framework/02_create_gallery_view.rst @@ -209,8 +209,6 @@ is hardcoded in the controller. .. code-block:: js - /** @odoo-module */ - import { registry } from '@web/core/registry'; import { galleryView } from '@awesome_gallery/gallery_view'; import { GalleryRenderer } from '@awesome_gallery/gallery_renderer';