diff --git a/content/developer/reference/frontend/assets.rst b/content/developer/reference/frontend/assets.rst index 62a0c08d8..918bef785 100644 --- a/content/developer/reference/frontend/assets.rst +++ b/content/developer/reference/frontend/assets.rst @@ -9,18 +9,22 @@ Managing assets in Odoo is not as straightforward as it is in some other apps. One of the reasons is that we have a variety of situations where some, but not all of the assets are required. For example, the needs of the web client, the point of sale app, the website or even the mobile application are different. Also, some -assets may be large, but are seldom needed. In that case, we sometimes want them -to be loaded lazily. +assets may be large, but are seldom needed: in that case we may want them +to be :ref:`loaded lazily (on demand) `. -The main idea is that we define a set of **bundles** in the module manifest. A -bundle is here defined as a **list of file paths** (xml, javascript, css, scss). -Files are declared using `glob `_ syntax, meaning that you can declare several asset -files using a single line. Each matching file found will be appended to the -`` of the page, at most once, in the order the glob patterns are given. +Bundles +======= -As mentioned, the bundles are declared in each module's :file:`__manifest__.py`, under -a dedicated `assets` key which contains a dictionary. The dictionary will map -**bundles** (keys) to the list of **files** they contain (values). It looks like this: +Odoo assets are grouped by *bundles*. Each bundle (a *list of file paths* +of specific types: `xml`, `js`, `css` or `scss`) is listed in the +:ref:`module manifest `. Files can be declared using +`glob `_ syntax, meaning that +you can declare several asset files using a single line. + +The bundles are defined in each module's :file:`__manifest__.py`, +with a dedicated `assets` key which contains a dictionary. The dictionary maps +bundle names (keys) to the list of files they contain (values). It looks +like this: .. code-block:: py @@ -38,197 +42,217 @@ a dedicated `assets` key which contains a dictionary. The dictionary will map ], }, - -The files in a bundle can then be inserted into a template by using the `t-call-assets` -directive: - -.. code-block:: xml - - - - -Here is what happens when a template is rendered by the server with these directives: - -- all the scss files described in the bundle are compiled into css files. A file - named :file:`file.scss` will be compiled in a file named :file:`file.scss.css`. - -- if we are in `debug=assets` mode - - - the `t-call-assets` directive with the `t-js` attribute set to false will - be replaced by a list of stylesheet tags pointing to the css files - - - the `t-call-assets` directive with the `t-css` attribute set to false will - link to the non minified bundle file (which uses sourcemaps) - -- if we are not in `debug=assets` mode - - - the css files will be concatenated and minified, then a stylesheet tag is - generated - - - the js files are concatenated and minified, then a script tag is generated - -.. note:: - Assets files are cached, so in theory, a browser should only load them once. - -Main bundles ------------- -When the Odoo server is started, it checks the timestamp of each file in a bundle -and, if necessary, create/recreate the corresponding bundles. - -Here are some important bundles that most developers will need to know: +Here is a list of some important bundles that most odoo developers will need to +know: - `web.assets_common`: this bundle contains most assets which are common to the - web client, the website, and also the point of sale. This is supposed to contain + web client, the website and also the point of sale. This is supposed to contain lower level building blocks for the odoo framework. Note that it contains the :file:`boot.js` file, which defines the odoo module system. - `web.assets_backend`: this bundle contains the code specific to the web client - (notably the web client/action manager/views) and all static XML templates used - in the backend environment + (notably the web client/action manager/views) - `web.assets_frontend`: this bundle is about all that is specific to the public - website: ecommerce, forum, blog, event management, ... + website: ecommerce, portal, forum, blog, ... + +- `web.assets_qweb`: all static XML templates used in the backend environment + and in the point of sale. + +- `web.qunit_suite_tests`: all javascript qunit testing code (tests, helpers, mocks) + +- `web.qunit_mobile_suite_tests`: mobile specific qunit testing code + +Asset types +=========== + +There are three different asset types: code (`js` files), style (`css` or `scss` +files) and templates (`xml` files). + +Code + Odoo supports :ref:`three different kinds of javascript files`. + All these files are then processed (native JS modules are transformed into odoo + modules), then minified (if not in `debug=assets` :ref:`mode `) + and concatenated. The result is then saved as a file attachment. These file + attachments are usually loaded via a `