NextERP/documentation
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[IMP] developer: small rework of assets page (frontend)

Browse Source 
This commit applies some remarks by Antoine.

closes odoo/documentation#1327

Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
This commit is contained in:
Géry Debongnie 2021-11-19 13:06:44 +00:00
parent 1f84bab97d
commit 8c1003e363
1 changed files with 48 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
content/developer/reference/frontend/assets.rst
View File

@ -12,6 +12,41 @@ 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 may want them assets may be large, but are seldom needed: in that case we may want them
to be :ref:`loaded lazily (on demand) <frontend/assets/lazy_loading>`. to be :ref:`loaded lazily (on demand) <frontend/assets/lazy_loading>`.
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<frontend/js_modules>`.
All these files are then processed (native JS modules are transformed into odoo
modules), then minified (if not in `debug=assets` :ref:`mode <frontend/framework/assets_debug_mode>`)
and concatenated. The result is then saved as a file attachment. These file
attachments are usually loaded via a `<script>` tag in the `<head>` part of
the page (as a static file).
Style
Styling can be done with either `css` or `scss <https://sass-lang.com/>`_. Like
the javascript files, these files are processed (`scss` files are converted into
`css`), then minified (again, if not in `debug=assets` :ref:`mode <frontend/framework/assets_debug_mode>`)
and concatenated. The result is then saved as a file attachment. They are
then usually loaded via a `<link>` tag in the `<head>` part of the page (as
a static file).
Template
Templates (static `xml` files) are handled in a different way: they are simply
read from the file system whenever they are needed, and concatenated.
Whenever the browser loads odoo, it calls the `/web/webclient/qweb/` controller
to fetch the :ref:`templates <reference/qweb>`.
It is useful to know that in most cases, a browser only performs a request the
first time it loads a page. This is because each of these assets are
associated with a checksum, which is injected into the page source. The checksum
is then added to the url, which means that it is possible to safely set the cache
headers to a long period.
Bundles Bundles
======= =======
@ -63,43 +98,9 @@ know:
- `web.qunit_mobile_suite_tests`: mobile specific qunit testing code - `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` Operations
files) and templates (`xml` files). ----------
Code
Odoo supports :ref:`three different kinds of javascript files<frontend/js_modules>`.
All these files are then processed (native JS modules are transformed into odoo
modules), then minified (if not in `debug=assets` :ref:`mode <frontend/framework/assets_debug_mode>`)
and concatenated. The result is then saved as a file attachment. These file
attachments are usually loaded via a `<script>` tag in the `<head>` part of
the page (as a static file).
Style
Styling can be done with either `css` or `scss <https://sass-lang.com/>`_. Like
the javascript files, these files are processed (`scss` files are converted into
`css`), then minified (again, if not in `debug=assets` :ref:`mode <frontend/framework/assets_debug_mode>`)
and concatenated. The result is then saved as a file attachment. They are
then usually loaded via a `<link>` tag in the `<head>` part of the page (as
a static file).
Template
Templates (static `xml` files) are handled in a different way: they are simply
read from the file system whenever they are needed, and concatenated.
Whenever the browser loads odoo, it calls the `/web/webclient/qweb/` controller
to fetch the :ref:`templates <reference/qweb>`.
It is useful to know that in most cases, a browser only performs a request the
first time it loads a page. This is because each of these assets are
associated with a checksum, which is injected into the page source. The checksum
is then added to the url, which means that it is possible to safely set the cache
headers to a long period.
Operations on asset bundles
===========================
Typically, handling assets is simple: you just need to add some new files Typically, handling assets is simple: you just need to add some new files
to a frequently used bundle like `assets_common` or `assets_backend`. But there are other operations to a frequently used bundle like `assets_common` or `assets_backend`. But there are other operations
@ -111,7 +112,7 @@ in manifests higher up in the hierarchy or in ``ir.asset`` records with a lower
sequence. sequence.
`append` `append`
-------- ~~~~~~~~
This operation adds one or multiple file(s). Since it is the most common This operation adds one or multiple file(s). Since it is the most common
operation, it can be done by simply using the file name: operation, it can be done by simply using the file name:
@ -127,7 +128,7 @@ glob pattern at the end of the bundle. Obviously, the pattern may also be direct
a single file path. a single file path.
`prepend` `prepend`
--------- ~~~~~~~~~
Add one or multiple file(s) at the beginning of the bundle. Add one or multiple file(s) at the beginning of the bundle.
@ -142,7 +143,7 @@ syntax: `('prepend', <path>)`.
], ],
`before` `before`
-------- ~~~~~~~~
Add one or multiple file(s) before a specific file. Add one or multiple file(s) before a specific file.
@ -158,7 +159,7 @@ file. It is declared by replacing the normal path with a 3-element tuple
], ],
`after` `after`
------- ~~~~~~~
Add one or multiple file(s) after a specific file. Add one or multiple file(s) after a specific file.
@ -173,7 +174,7 @@ It is declared by replacing the normal path with a 3-element tuple
], ],
`include` `include`
--------- ~~~~~~~~~
Use nested bundles. Use nested bundles.
@ -189,7 +190,7 @@ specify the sub bundle as a pair `('include', <bundle>)` like this:
], ],
`remove` `remove`
-------- ~~~~~~~~
Remove one or multiple file(s). Remove one or multiple file(s).
@ -204,7 +205,7 @@ can be done using the `remove` directive by specifying a pair
], ],
`replace` `replace`
--------- ~~~~~~~~~
Replace an asset file with one or multiple file(s). Replace an asset file with one or multiple file(s).
@ -220,7 +221,7 @@ the `replace` directive, using a 3-element tuple `('replace', <target>, <path>)`
Loading order Loading order
============= -------------
The order in which assets are loaded is sometimes critical and must be deterministic, The order in which assets are loaded is sometimes critical and must be deterministic,
mostly for stylesheets priorities and setup scripts. Assets in Odoo are processed mostly for stylesheets priorities and setup scripts. Assets in Odoo are processed
@ -235,7 +236,7 @@ as follows:
#. All modules declaring assets for said bundle in their manifest apply their #. All modules declaring assets for said bundle in their manifest apply their
assets operations to this list. This is done following the order of modules dependencies assets operations to this list. This is done following the order of modules dependencies
(e.g. `web` assets is processed before 'website'). If a directive tries to add (e.g. `web` assets is processed before `website`). If a directive tries to add
a file already present in the list, nothing is done for that file. In other word, a file already present in the list, nothing is done for that file. In other word,
only the first occurrence of a file is kept in the list. only the first occurrence of a file is kept in the list.
@ -267,8 +268,8 @@ in the list before all the others included in the glob.
.. _frontend/assets/lazy_loading: .. _frontend/assets/lazy_loading:
Lazy loading assets Lazy loading
=================== ============
It is sometimes useful to load files and/or asset bundles dynamically, for It is sometimes useful to load files and/or asset bundles dynamically, for
example to only load a library once it is needed. To do that, the Odoo framework example to only load a library once it is needed. To do that, the Odoo framework