khanh.pndc/odoo-docs
1
0
Fork 0
mirror of https://github.com/odoo/documentation.git synced 2025-12-12 07:29:27 +07:00
Code Issues Packages Projects Releases Wiki Activity

[IMP] scss: update, improve preexisting content

Browse Source 
Add a new content focused on SCSS and user-interface.

- SCSS coding guidelines: regroup information already available (eg [1])
  or based on "oral tradition".
  The aim is not to establish new rules, ~99% of the current codebase
  is already compliant.

- SCSS inheritance: explain how SCSS assets management works in odoo.
  For example, people still find confusing that overrides are defined
  *before* the variable to customize.

- SCSS optimization tips: suggestions to lean SCSS code. Based on SCSS
  optimization task's know-how [2].

- CSS variables: explain how this feature is commonly used in odoo to
  adapt layout & design without raw CSS overrides.

- UI Icons: Add link to fontAwesome4 library . Replace the picture of
  odoo icons with the actual font (90kb image VS 15Kb font)

[1] https://github.com/odoo/odoo/wiki/SCSS-coding-guidelines
[2] https://www.odoo.com/web#id=2704984&menu_id=4720&cids=1&model=project.task&view_type=form

task-3090800

closes odoo/documentation#3327

X-original-commit: 2ca32b40bc
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
This commit is contained in:
stefanorigano (SRI)
2022-10-27 08:19:25 +00:00
committed by Antoine Vandevenne (anv)
parent 8a30786495
commit 9571a32131
17 changed files with 1094 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
content/developer/reference/user_interface/icons.rst Normal file
View File

@@ -0,0 +1,114 @@
:hide-page-toc:
========
UI icons
========
Odoo's user interface mostly relies on `FontAwesome4 icons <https://fontawesome.com/v4/icons/>`_.
To cover FontAwesome's lack of iconography for specific functionalities, we designed our own
icon-font. These icons can be rendered using the main `oi` class in conjunction with the specific
icon class.
.. example::
.. code-block:: html
<i class="oi oi-odoo"/>
.. raw:: html
<section class="row">
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-apps h1 p-4"></i>
<code>oi-apps</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-group h1 p-4"></i>
<code>oi-group</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-launch h1 p-4"></i>
<code>oi-launch</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-odoo h1 p-4"></i>
<code>oi-odoo</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-panel-right h1 p-4"></i>
<code>oi-panel-right</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-search h1 p-4"></i>
<code>oi-search</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-settings-adjust h1 p-4"></i>
<code>oi-settings-adjust</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-studio h1 p-4"></i>
<code>oi-studio</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-view-cohort h1 p-4"></i>
<code>oi-view-cohort</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-view-kanban h1 p-4"></i>
<code>oi-view-kanban</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-view-list h1 p-4"></i>
<code>oi-view-list</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-view-pivot h1 p-4"></i>
<code>oi-view-pivot</code>
</div>
</div>
<div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
<div class="card text-center">
<i class="oi oi-voip h1 p-4"></i>
<code>oi-voip</code>
</div>
</div>
</section>

106
content/developer/reference/user_interface/scss_inheritance.rst Normal file
View File

@@ -0,0 +1,106 @@
================
SCSS inheritance
================
Overview
========
Managing SCSS assets in Odoo is not as straightforward as it is in some other environments, but it's
highly efficient.
Modularity is key. The inheritance scheme described further allows Odoo to:
- customize the Bootstrap CSS framework;
- handle two different webclient designs (Community and Enterprise);
- handle backend and frontend bundles separately (including the user's website design);
- contextually load only necessary assets;
- handle multiple color-schemes (e.g.: dark-mode);
SCSS's `!default` directive
===========================
"Direct variables’ overrides" are technically possible in SCSS but may lead to inconsistent results
in complex environments like Odoo.
.. example::
.. code-block:: scss
:caption: :file:`library.scss`
$foo: red;
.. code-block:: scss
:caption: :file:`customization_layer.scss`
$foo: blue; // -> Don't!
Indeed, since the compilation process acts across different interdependent bundles, re-assigning
a variable in the "wrong spot" may lead to unexpected cascading results.
SCSS provides several techniques to overcome these issues
(e.g.: `shadowing <https://sass-lang.com/documentation/variables#shadowing>`_), but the most
critical procedure in Odoo is the use of the `!default` flag.
When using the `!default` flag, the compiler assigns a value **only** if that variable is not yet
defined.
As a result of this technique, the priority in which variables are assigned matches the assets'
loading order.
.. example::
.. code-block:: scss
:caption: :file:`customization_layer.scss`
$foo: red !default;
.. code-block:: scss
:caption: :file:`library.scss`
$foo: blue !default; // -> Already defined, line ignored.
$bar: black !default; // -> Not defined yet, value assigned.
.. code-block::
:caption: :file:`component.scss`
.component {
color: $foo; // -> 'color: red;'
background: $bar; // -> 'background: black;'
}
.. seealso::
`!default` flag on the `SASS Documentation
<https://sass-lang.com/documentation/variables#default-values>`_
Odoo's SCSS inheritance system
==============================
The following diagram conceptually illustrates the compilation order in which the CSS and SCSS
variables are defined.
.. code-block:: text
↓ [Compilation starts]
⏐
↓ web.dark_mode_variables
⏐ ├─ Primary Variables
⏐ └─ Components Variables
⏐
↓ web._assets_primary_variables
⏐ ├─ Primary Variables (enterprise)
⏐ ├─ Components Variables (enterprise)
⏐ ├─ Primary Variables (community)
⏐ └─ Components Variables (community)
⏐
↓ web._assets_bootstrap
⏐
↓ web.assets_backend
⏐ ├─ ...
⏐ ├─ CSS variables definition
⏐ └─ CSS variables contextual adaptations
⏐
● [Visual result on screen]
.. important::
This diagram is incomplete and does not match the current bundles' organization. Read more on
:ref:`asset bundles <reference/assets_bundle>`.