From b6bcc665377cc64ca18c68e0cfb6036583273b91 Mon Sep 17 00:00:00 2001 From: Carlos Valverde Date: Fri, 21 Feb 2025 17:09:10 +0000 Subject: [PATCH] [IMP] howto/website: update theming page This commit updates current theming page, by adding new anchor links to the sections and by adding updated information. Task-4316611 closes odoo/documentation#12275 X-original-commit: 16e1bad7db315a2010811a21a160554c7ecd89c0 Signed-off-by: Carlos Valverde (cvs) --- .../howtos/website_themes/theming.rst | 167 +++++++++++++++--- .../theming/theme-colors-airproof.png | Bin 331579 -> 79650 bytes .../website_themes/theming/versioning.png | Bin 0 -> 5119 bytes 3 files changed, 146 insertions(+), 21 deletions(-) create mode 100644 content/developer/howtos/website_themes/theming/versioning.png diff --git a/content/developer/howtos/website_themes/theming.rst b/content/developer/howtos/website_themes/theming.rst index 1e563356d..848e16270 100644 --- a/content/developer/howtos/website_themes/theming.rst +++ b/content/developer/howtos/website_themes/theming.rst @@ -10,6 +10,8 @@ theme module. In this chapter, you will discover how to: - Get the most out of Bootstrap variables. - Add custom styles and JavaScript. +.. _theming/module: + Theme module ============ @@ -19,6 +21,8 @@ theme, you are extending the default theme. Remember to add the directory containing your module to the `addons-path` command-line argument when running Odoo in your development environment. +.. _theming/module/naming: + Technical naming ---------------- @@ -33,6 +37,8 @@ The first step is to create a new directory. In this documentation, we will use **Airproof** (a fictional project) as an example. +.. _theming/module/structure: + File structure -------------- @@ -44,18 +50,17 @@ package its theme like a module. website_airproof ├── data ├── i18n - ├── lib ├── static │ ├── description │ ├── fonts - │ ├── image_shapes // Shapes for images + │ ├── lib │ ├── shapes // Shapes for background │ └── src │ ├── img │ │ ├── content // For those used in the pages of your website │ │ └── wbuilder // For those used in the builder │ ├── js - │ ├── scss + │ ├── scss // Theme specific styles │ └── snippets // custom snippets ├── views ├── __init__.py @@ -79,12 +84,17 @@ package its theme like a module. * - views - Custom views and templates (`*.xml`) +.. _theming/module/initialization: + Initialization -------------- An Odoo module is also a Python package with a :file:`__init__.py` file containing import instructions for various Python files in the module. This file can remain empty for now. + +.. _theming/module/declaration: + Declaration ----------- @@ -99,7 +109,7 @@ always required. It usually contains much more information. 'name': 'Airproof Theme', 'description': '...', 'category': 'Website/Theme', - 'version': '15.0.0', + 'version': '{BRANCH}.0', 'author': '...', 'license': '...', 'depends': ['website'], @@ -130,7 +140,8 @@ always required. It usually contains much more information. * - author - Name of the module author * - license - - Distribution license for the module + - By default, we use the `LGPL-3` license. More information in the :ref:`module manifest + ` page. * - depends - Odoo modules must be loaded before this one, either because this module uses features they create or because it alters resources they define @@ -140,8 +151,24 @@ always required. It usually contains much more information. - List of SCSS and JS files .. note:: - To create a website theme, you only need to install the Website app. If you need other apps - (Blogs, Events, eCommerce, ...), you can also add them. + - The file structure above is just a suggestion. We could add as many other folders as needed in + the project, such as `/controllers` to include controllers or `/views/backend` for backend + views, etc. + - To create a website theme, you only need to install the Website app. If you need other apps + (Blogs, Events, eCommerce, ...), you can also add them. + - Odoo version and major number are mandatory. However, patch number is optional. If you want + to specify the required version of Odoo to run your module, you should use a five arguments + structure, using the first two arguments to indicate the Odoo version. + + .. image:: theming/versioning.png + :alt: Module versioning + :width: 300 + +.. warning:: + Automated file inclusion using wildcard notations `(ex.: /myfolder/*.scss)` doesn't work in + Odoo SaaS databases. In this case, include each file manually in the manifest. + +.. _theming/options: Default options =============== @@ -164,6 +191,8 @@ First, try to construct your theme by using Odoo's default options. This ensures .. seealso:: :doc:`Odoo coding guidelines <../../../contributing/development/coding_guidelines>` +.. _theming/module/variables: + Odoo variables -------------- @@ -178,7 +207,7 @@ bundle. 'assets': { 'web._assets_primary_variables': [ - ('prepend', 'website_airproof/static/src/scss/primary_variables.scss'), + 'website_airproof/static/src/scss/primary_variables.scss', ], }, @@ -194,6 +223,8 @@ By reading the source code, variables related to options are easily noticeable. These variables can be overridden through the `$o-website-value-palettes` map, for example. +.. _theming/module/variables/global: + Global ~~~~~~ @@ -219,6 +250,8 @@ Global `Primary variables SCSS `_ +.. _theming/module/variables/fonts: + Fonts ~~~~~ @@ -257,6 +290,8 @@ the font selector. ), ); +.. _theming/module/variables/fonts/google: + Google fonts ************ @@ -275,6 +310,8 @@ Google fonts ), ); +.. _theming/module/variables/fonts/custom: + Custom fonts ************ @@ -295,8 +332,11 @@ Then, use the `@font-face` rule to allow you custom font(s) to be loaded on your :caption: ``/website_airproof/static/src/scss/font.scss`` @font-face { - font-family: ''; - ... + font-family: "My Custom Font", Helvetica, Helvetica Neue, Arial, sans-serif; + font-weight: 400; + font-style: normal; + src: url('/fonts/my-custom-font.woff') format('woff'), + url('/fonts/my-custom-font.woff2') format('woff2'); } .. code-block:: scss @@ -314,7 +354,9 @@ Then, use the `@font-face` rule to allow you custom font(s) to be loaded on your ); .. tip:: - It is recommended to use the .woff format for your fonts. + It is recommended to use the `.woff` and/or `.woff2` format for your fonts. + +.. _theming/module/variables/colors: Colors ~~~~~~ @@ -334,7 +376,7 @@ ensures it stays consistent. * - o-color-2 - Secondary * - o-color-3 - - Extra + - Extra (Light) * - o-color-4 - Whitish * - o-color-5 @@ -392,8 +434,8 @@ buttons, and secondary buttons. These colors can be customized later by the user :alt: Theme colors :width: 300 -The colors used in a color combination are accessible and can be overridden through the BS -`$colors map` using a specific prefix (`o-cc` for `color combination`). +The colors used in a color combination are accessible and can be overridden through +`$o-color-palettes` using a specific prefix (`o-cc` for `color combination`). .. code-block:: scss :caption: ``/website_airproof/static/src/scss/primary_variables.scss`` @@ -436,6 +478,30 @@ The colors used in a color combination are accessible and can be overridden thro The Website Builder automatically generates a page to view the color combinations of the theme color palette: http://localhost:8069/website/demo/color-combinations +.. _theming/module/variables/gradients: + +Gradients +~~~~~~~~~ + +You can also define gradients for the menu, header, footer and copyright bar, directly in your +`primary_variables.scss` file. + +**Declaration** + +.. code-block:: scss + :caption: ``/website_airproof/static/src/scss/primary_variables.scss`` + + $o-website-values-palettes: ( + ( + 'menu-gradient': linear-gradient(135deg, rgb(203, 94, 238) 0%, rgb(75, 225, 236) 100%), + 'header-boxed-gradient': [your-gradient], + 'footer-gradient': [your-gradient], + 'copyright-gradient': [your-gradient], + ), + ); + +.. _theming/module/bootstrap: + Bootstrap variables ------------------- @@ -484,14 +550,20 @@ values and *not* the :file:`primary_variables.scss` file. Don't override Bootstrap variables that depend on Odoo variables. Otherwise, you might break the possibility for the user to customize them using the Website Builder. + When an option is defined by a variable in `primary_variables.scss` and by a Boostrap variable, + you should always go for an override through the primary variables. Do it via + `bootsrap_overridden.scss` only if nothing exists in the primary variables. + .. seealso:: `Bootstrap overridden SCSS - <{GITHUB_PATH}/addons/website/static/src/scss/bootstrap_overridden.scss>`_ + <{GITHUB_PATH}/addons/web/static/lib/bootstrap/scss/_variables.scss>`_ .. admonition:: Demo page http://localhost:8069/website/demo/bootstrap +.. _theming/module/views: + Views ----- @@ -513,6 +585,23 @@ By reading the source code, templates related to options are easily found.