[IMP] tutorials/website_theme: Custom font, website settings, grid layout, mega-menu & page templates, custom gradient + update snippet addition

closes odoo/documentation#14303

X-original-commit: 64ede317ed
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>

content/developer/tutorials/website_theme/01_theming.rst

@@ -55,7 +55,8 @@ Based on the Airproof design, create your :file:`primary_variables.scss` file an
 following elements:
 
 - Headings font family : Space Grotesk
-- Content font family : Lato
+- Content font family : Lato. For this, use these `2 woff files
+  <{GITHUB_TUTO_PATH}/website_airproof/static/fonts>`_.
 - The color palette name and the 5 main colors that compose it: `#000000`, `#BBE1FA`, `#CEF8A1`,
   `#FFFFFF`, `#0B8EE6`
 - Header & Footer : Use one of the default templates for the moment, we will create a custom header
@@ -78,7 +79,8 @@ color palette includes your specified colors.
    throughout the creation of your website.
 
 .. note::
-   The font families are from `Google fonts <https://fonts.google.com/>`_.
+   For font families you can either use `Google fonts <https://fonts.google.com/>`_ (via URL) or add
+   your own :ref:`fonts <theming/module/variables/fonts/custom>`.
 
 .. spoiler:: Solutions
 
@@ -88,7 +90,10 @@ color palette includes your specified colors.
       the `primary_variables.scss
       <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/primary_variables.scss>`_ file from our
       example module.
-   #. Declare your file in the :file:`__manifest__.py` as indicated in the documentation.
+   #. Load your custom font in a `font.scss
+      <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/font.scss>`_ file.
+   #. Declare the 2 files you just created in :file:`__manifest__.py` as indicated in the
+      documentation.
    #. Install your module via your script. In our example, it looks like this:
 
    .. code-block:: xml
@@ -114,6 +119,7 @@ Based on the Airproof design, define the following elements:
   - h4 : 1.75rem
   - h5 : 1.5rem
   - h6 : 1.25rem
+  - Display 1 : 6.25rem (Who will be useful for the main title of your homepage)
 
 - Inputs border radius : 10px
 - Inputs border color : black

content/developer/tutorials/website_theme/02_build_website.rst

@@ -23,12 +23,12 @@ as content in the page.
 .. spoiler:: Solutions
 
    .. code-block:: python
-         :caption: ``/website_airproof/__manifest__.py``
+      :caption: ``/website_airproof/__manifest__.py``
 
-         'data': [
-            # Pages
-            'data/pages/home.xml',
-         ]
+      'data': [
+         # Pages
+         'data/pages/home.xml',
+      ]
 
    .. code-block:: xml
       :caption: ``/website_airproof/data/pages/home.xml``
@@ -107,18 +107,21 @@ Based on the Airproof design, add the following elements to the homepage :
   - For this section, you don't want the future user to be able to edit it via the Website Builder.
   - Put an opacity filter on the background image of the 3 boxes.
 
-- Create another section containing the title and icons.
+- Create another section containing a title and icons using the grid system.
 
 You can use these `images <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content>`_ and `icons
 <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content/icons>`_.
 
 .. seealso::
-   See reference documentation on how to :ref:`write standard snippets
-   <website_themes/building_blocks/layout>`.
+   See reference documentation on how to :ref:`write standard building blocks
+   <website_themes/building_blocks/layout>` and how to use the
+   :ref:`grid layout <website_themes/building_blocks/layout/grid>`.
 
-.. image:: 02_build_website/building-blocks.png
-   :alt: Airproof building blocks.
-   :scale: 75%
+.. image:: 02_build_website/building-block-column.png
+   :alt: Airproof building block column layout.
+
+.. image:: 02_build_website/building-block-grid.png
+   :alt: Airproof building block grid layout.
 
 .. tip::
    To determine the code needed to create your building blocks :
@@ -143,6 +146,9 @@ For now, the client is fine with the default header but has requested some navig
 
 The client has requested the following changes:
 
+- Add the `Airproof logo
+  <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content/branding/airproof-logo.svg>`_. At the
+  same time, set the name and favicon of the website.
 - Remove the link to the homepage and the shop.
 - Add a link to the future “About us” page.
 - Replace the default blog item with a dropdown to display the different blogs: “Our latest news”
@@ -150,6 +156,7 @@ The client has requested the following changes:
 - Add a mega-menu “Waterproof drones” to display the different products.
 
 .. seealso::
+   - See how to set up the :ref:`website settings <theming/module/website>` (including the logo).
    - You can find the original mega-menu templates code in Odoo :
      `odoo/addons/website/views/snippets/s_mega_menu_**.xml
      <{GITHUB_PATH}/addons/website/views/snippets>`_
@@ -164,7 +171,28 @@ The client has requested the following changes:
    - Create the different products via the backend. You can use these `product pictures
      <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content>`_.
 
+.. note::
+   - If you want to make the logo available in the Media dialog, you have to add the record image.
+   - It could be interesting to put a :ref:`noupdate <website_themes/pages/theme_pages/noupdate>` on
+     the navigation so that the changes made later by your client won’t be overwritten if you have
+     to update the module.
+
 .. spoiler:: Solutions
 
-   Find the solution in our Airproof example on `menu.xml
-   <{GITHUB_TUTO_PATH}/website_airproof/data/menu.xml>`_.
+   To complete this exercise, you need to:
+
+   #. Add the logo and favicon in the right folder.
+   #. Put the website records in a :file:`website.xml` file:
+
+      .. code-block:: xml
+         :caption: ``/website_airproof/data/website.xml``
+
+         <record id="website.default_website" model="website">
+            <field name="name">Airproof</field>
+            <field name="logo" type="base64" file="website_airproof/static/src/img/content/branding/airproof-logo.svg"/>
+            <field name="favicon" type="base64" file="website_airproof/static/description/airproof-favicon.png" />
+         </record>
+
+   #. Declare your :file:`website.xml` file in :file:`__manifest__.py`.
+   #. Create your menu as in the `menu.xml <{GITHUB_TUTO_PATH}/website_airproof/data/menu.xml>`_
+      from our Airproof example.

content/developer/tutorials/website_theme/03_customisation_part1.rst

@@ -69,25 +69,27 @@ Create a custom header
 With variables, presets, and custom SCSS in place, it's time to refine the layout and add key
 cross-page elements, starting with the header.
 
-Based on the Airproof design, create a custom header with the following elements:
+#. Based on the Airproof design, create a custom header with the following elements:
 
-- A centered logo. Ensure to declare the logo so that it appears automatically in the header.
-- A custom shopping cart icon.
-- A login/user as a button.
-- Navigation text to 14px.
+   - A custom shopping cart icon.
+   - A login/user as a button.
+   - Navigation text to 14px.
 
-You can find the `logo
-<{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content/branding/airproof-logo.svg>`_,
-`cart icon <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content/icons/shopping.svg>`_ and
-`template illustration
-<{GITHUB_TUTO_PATH}/website_airproof/static/src/img/wbuilder/template-header-opt.svg>`_.
+   You can find the `cart icon
+   <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content/icons/shopping.svg>`_ and `template
+   illustration <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/wbuilder/template-header-opt.svg>`_.
+
+#. In order for the client to find the mega menu you previously created for him, turn it into a
+   template that can be found through the website builder.
+#. Place your new header over the content of your homepage.
 
 .. seealso::
    See reference documentation on how to:
 
    - create :ref:`custom headers <website_themes/layout/header/custom>`,
    - do a :ref:`website_themes/layout/xpath`,
-   - declare a :ref:`website_themes/media/images/use/logo`.
+   - create a :ref:`mega menu template <website_themes/navigation/mega_menu/custom>`,
+   - create a :ref:`header overlay <website_themes/pages/theme_pages/header_overlay>`.
 
 .. image:: 03_customisation_part1/header.png
 
@@ -106,11 +108,16 @@ You can find the `logo
      variables` and :file:`primary variables` (font, colors, size...). You can use them to help you
      with this exercise.
 
+.. note::
+   Ensure that you properly call every template in your header (like the shopping cart, language
+   selector, call to action, etc.), so everything will remain editable via the website builder and
+   all options will be available.
+
 .. spoiler:: Solutions
 
    Find the solution in our Airproof example for:
 
-   - the xml structure and to add the template to the options list on
+   - the xml structure and how to add the header and mega menu template to the options list on
      `website_template.xml <{GITHUB_TUTO_PATH}/website_airproof/views/website_templates.xml>`_.
    - disable the default header:
 
@@ -122,16 +129,6 @@ You can find the `logo
            <field name="active" eval="False"/>
         </record>
 
-   - record the logo:
-
-     .. code-block:: xml
-        :caption: ``/website_airproof/data/images.xml``
-
-        <!-- Set as the logo of the website -->
-        <record id="website.default_website" model="website">
-           <field name="logo" type="base64" file="website_airproof/static/src/img/content/branding/airproof-logo.svg"/>
-        </record>
-
    - declare your :file:`website_templates.xml` file along with all the new ones in your
      :file:`manifest`.
    - disable the options you don’t want in your header via the `presets
@@ -144,6 +141,15 @@ You can find the `logo
      `$navbar-light-color`, `$navbar-light-hover-color`, `$navbar-padding-y`...
    - add some `scss <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/layout/header.scss>`_
      rules.
+   - to place the header over the content, add the right field to the home page:
+
+     .. code-block:: xml
+        :caption: ``/website_airproof/data/pages/home.xml``
+        :emphasize-lines: 3
+
+        <!-- Home -->
+        <record id="page_home" model="website.page">
+           <field name="header_overlay" eval="True"/>
 
 .. _tutorials/website_theme/customisation_part1/custom_footer:
 
@@ -178,6 +184,7 @@ You will find the `icons here <{GITHUB_TUTO_PATH}/website_airproof/static/src/im
 
      .. code-block:: python
          :caption: ``/website_airproof/__manifest__.py``
+         :emphasize-lines: 2
 
          'depends': ['website_sale', 'website_sale_wishlist', 'website_blog',
          'website_mass_mailing'],
@@ -215,8 +222,8 @@ can freely drag & drop onto different pages.
 Based on the Airproof design, create a custom carousel snippet to showcase drones. Then, add it as
 cover section on your homepage.
 
-#. Create the snippet template and add it to the list of building blocks available in the website
-   builder. Here you will find the `images
+#. Create the snippet template. Then, add it to the list of building blocks available in the website
+   builder. Place it in its own category. Here you will find the `images
    <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/snippets/s_airproof_caroussel>`_ and
    `snippet illustration
    <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/wbuilder/s-airproof-snippet.svg>`_.
@@ -227,8 +234,10 @@ cover section on your homepage.
 
    .. image:: 03_customisation_part1/custom-building-block.png
 
-#. Add an option in the Website Builder to allow users to choose between a blue or green bubble
-   shadow.
+#. Add two options in the Website Builder for the bubbles:
+
+   - Allow users to choose only between a blue or green shadow.
+   - Offer a range of possible margins between the bubbles.
 
    .. seealso::
       See reference documentation on how to add :ref:`snippet options
@@ -264,18 +273,14 @@ cover section on your homepage.
 
            <!-- Add custom snippets to the builder -->
            <template id="snippets" inherit_id="website.snippets" name="Airproof - Custom Snippets">
-              <xpath expr="//*[@id='default_snippets']" position="before">
-                 <t id="x_theme_snippets">
-                    <div id="x_airproof_snippets" class="o_panel">
-                       <div class="o_panel_header">Airproof</div>
-                       <div class="o_panel_body">
-                          <!-- Carousel snippet -->
-                          <t t-snippet="website_airproof.s_airproof_carousel"
-                          t-thumbnail="/website_airproof/static/src/img/wbuilder/s-airproof-snippet.svg">
-                             <keywords>Carousel block</keywords>
-                          </t>
-                       </div>
-                    </div>
+              <xpath expr="//snippets[@id='snippet_groups']/*[1]" position="before">
+                 <t snippet-group="airproof" t-snippet="website.s_snippet_group" string="Airproof"
+                 t-thumbnail="/website_airproof/static/src/img/wbuilder/s-airproof-snippet.svg"/>
+              </xpath>
+              <xpath expr="//snippets[@id='snippet_structure']/*[1]" position="before">
+                 <t t-snippet="website_airproof.s_airproof_carousel" string="Custom snippet"
+                 group="airproof">
+                   <keywords>Carousel block</keywords>
                  </t>
               </xpath>
            </template>
@@ -289,14 +294,20 @@ cover section on your homepage.
          <template id="snippet_options" inherit_id="website.snippet_options" name="Airproof -
          Snippets Options">
             <xpath expr="." position="inside">
-               <!-- *** Carousel snippet : blue or green bubble *** -->
                <div data-selector=".x_bubble_item">
+                  <!-- Bubble shadow color -->
                   <we-button-group string="Bubble shadow">
                      <we-button data-select-class="x_bubble1">Blue</we-button>
                      <we-button data-select-class="x_bubble2">Green</we-button>
                   </we-button-group>
+                  <!-- Bubble spacing -->
+                  <we-range string="Bubble Spacing" data-select-class="mb-1|mb-2|mb-3|mb-4|mb-5"/>
                </div>
             </xpath>
+            <xpath expr="//div[@data-js='Box'][@data-selector='section .row > div']" position="attributes">
+               <!-- Disable standard shadow & borders for bubbles -->
+               <attribute name="t-attf-data-exclude" add=".x_bubble_item" separator=", "/>
+            </xpath>
          </template>
 
       Additionally, the SCSS related to the bubbles in the `s_airproof_carousel/000.scss

content/developer/tutorials/website_theme/04_customisation_part2.rst

@@ -62,41 +62,75 @@ that can be animated and customized with different colors.
 
    .. code-block:: xml
       :caption: ``/website_airproof/data/pages/home.xml``
+      :emphasize-lines: 4-7
 
       <!-- Text-image block & Background shape -->
       <section class="s_text_image o_cc o_cc3 o_colored_level pt120 pb96"
-      data-snippet="s_image_text" data-name="Image - Text" style="background-color: rgb(41, 128,
-      187);" data-oe-shape-data="{'shape': 'illustration/airproof/waves', 'colors': {'c1': '#BBE1FA'},
-      'flip': ['x']}">
+      data-snippet="s_image_text" data-name="Image - Text" style="background-color: rgb(41, 128, 187);"
+      data-oe-shape-data="{'shape': 'illustration/airproof/waves', 'colors': {'c1': '#BBE1FA'}, 'flip': ['x']}">
          <div class="o_we_shape o_illustration_airproof_waves o_we_flip_x" style="background-image:
          url('/web_editor/shape/illustration%2Fairproof%2Fwaves.svg?c2=%23BBE1FA');
          background-position: 100% 100%;"/>
          [...]
       </section>
 
-.. _tutorials/website_theme/customisation_part2/background_gradient:
+.. _tutorials/website_theme/customisation_part2/custom_gradient:
 
-Add a background gradient
-=========================
+Create a custom gradient
+========================
 
-Apply a custom background gradient to your ”*Latest products*” block, transitioning from blue
-`rgb(11, 142, 230)` to dark blue `rgb(41, 128, 187)`.
+Next, let's add gradients to backgrounds. To enhance the page's dynamism, apply a gradient from blue
+`rgb(11, 142, 230)` to dark blue `rgb(41, 128, 187)` to your ”*Latest products*” block. But before
+that, add the gradient to the website builder so that the client can easily reuse it.
 
 .. seealso::
-   See reference documentation on how to use :doc:`/developer/howtos/website_themes/gradients`.
+   See reference documentation on how to apply :doc:`gradients
+   </developer/howtos/website_themes/gradients>` and how to create :ref:`custom gradients
+   <website_themes/gradients/custom>`.
 
 .. spoiler:: Solutions
 
-   .. code-block:: xml
-      :caption: ``/website_airproof/data/pages/home.xml``
+   #. Create and declare a :file:`gradients.xml` file and add the custom gradient.
 
-      <!-- Latest products section -->
-      <section class="s_parallax o_colored_level o_cc o_cc5 s_parallax_no_overflow_hidden pt40 pb32"
-      data-scroll-background-ratio="0" data-snippet="s_parallax" data-name="Parallax"
-      style="background-image: linear-gradient(0deg, rgb(41, 128, 187) 0%, rgb(11, 142, 230) 100%)
-      !important;">
-         [...]
-      </section>
+      .. code-block:: python
+         :caption: ``/website_airproof/__manifest__.py``
+
+         'data': [
+            # Gradients
+           'data/gradients.xml',
+         ]
+
+      .. code-block:: xml
+         :caption: ``/website_airproof/data/gradients.xml``
+
+         <record id="colorpicker" model="ir.ui.view">
+           <field name="key">website_airproof.colorpicker</field>
+           <field name="name">Custom Gradients</field>
+           <field name="type">qweb</field>
+           <field name="inherit_id" ref="web_editor.colorpicker"/>
+           <field name="arch" type="xml">
+               <xpath expr="//div[@data-name='predefined_gradients']/t[@t-set='gradients']" position="after">
+                   <t t-set="gradients" t-value="gradients + ['linear-gradient(0deg, rgb(41, 128, 187) 0%,
+                   rgb(11, 142, 230) 100%)']"/>
+               </xpath>
+           </field>
+         </record>
+
+   #. Apply it to the ”*Latest products*” section.
+
+      .. code-block:: xml
+         :caption: ``/website_airproof/data/pages/home.xml``
+         :emphasize-lines: 7
+
+         <!-- Latest products section -->
+         <section data-snippet="s_dynamic_snippet_products" class="s_dynamic_snippet_products s_dynamic
+         s_dynamic_empty pt32 pb32 o_colored_level s_product_product_airproof o_dynamic_snippet_empty o_cc o_cc5"
+         data-custom-template-data="{}" data-name="Produits" data-product-category-id="all"
+         data-show-variants="" data-number-of-records="16" data-filter-id="3" data-carousel-interval="5000"
+         data-template-key="website_airproof.dynamic_filter_template_product_product_airproof"
+         style="background-image: linear-gradient(0deg, rgb(41, 128, 187) 0%, rgb(11, 142, 230) 100%) !important;">
+            [...]
+         </section>
 
 .. _tutorials/website_theme/customisation_part2/animations:
 
@@ -190,3 +224,49 @@ new page link to the menu. The client has the following requests for their conta
 
    Find the solution in our Airproof example on `contact.xml
    <{GITHUB_TUTO_PATH}/website_airproof/data/pages/contact.xml>`_.
+
+.. _tutorials/website_theme/customisation_part2/page_template:
+
+Create a page template
+======================
+
+You don't have the time to create all the service pages for the client. No worries! Create a
+template page that the client can use to build their own service pages.
+
+This page should be composed as follows:
+
+- a :guilabel:`Parallax` building block,
+- a :guilabel:`Key benefits` building block with the title replaced by "*Discover our service*",
+- a :guilabel:`Call to action` building block,
+- your custom carousel snippet.
+
+.. seealso::
+   See reference documentation on how to create :ref:`page templates
+   <website_themes/pages/theme_pages/page_templates>`.
+
+.. image:: 04_customisation_part2/page-template.png
+   :scale: 75%
+
+.. spoiler:: Solutions
+
+   #. Create your :file:`new_page_template_templates.xml` file and discover its content in our
+      `Airproof example <{GITHUB_TUTO_PATH}/website_airproof/views/new_page_template_templates.xml>`_.
+   #. Don't forget to declare your file in the :file:`__manifest__.py` file and define what the
+      template page contains.
+
+      .. code-block:: python
+         :caption: ``/website_airproof/__manifest__.py``
+
+         'data': [
+            # ...
+            'views/new_page_template_templates.xml',
+         ],
+         'assets': {
+            # ...
+         },
+         'new_page_templates': {
+            'airproof': {
+               'services': ['s_parallax', 's_airproof_key_benefits_h2', 's_call_to_action',
+               's_airproof_carousel']
+            }
+         },

content/developer/tutorials/website_theme/05_dynamic_templates.rst

@@ -21,11 +21,12 @@ using `XPath`. Following the Airproof design, let's begin by modifying the shop
 #. Apply all changes in your :file:`website_sale_templates.xml` file. Start by:
 
    - Add a banner.
-   - Adapt the layout of the e-commerce category filtering on the left.
+   - Adapt the filtering on the left.
    - Remove the search bar (you can remove it from both the shop and the product pages at the same
      time).
    - Move the breadcrumb.
    - Hide the list or grid view option.
+   - Display only 3 products per row.
    - Create the appropriate design and information for the product cards.
 
 .. image:: 05_dynamic_templates/airproof-shop-page.png
@@ -41,7 +42,8 @@ using `XPath`. Following the Airproof design, let's begin by modifying the shop
 .. spoiler:: Solutions
 
    Find the solution in our Airproof example on `presets.xml
-   <{GITHUB_TUTO_PATH}/website_airproof/data/presets.xml>`_, `website_sale_templates.xml
+   <{GITHUB_TUTO_PATH}/website_airproof/data/presets.xml>`_, `website.xml
+   <{GITHUB_TUTO_PATH}/website_airproof/data/website.xml>`_, `website_sale_templates.xml
    <{GITHUB_TUTO_PATH}/website_airproof/views/website_sale_templates.xml>`_ part *shop page*, and
    `shop.scss <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/pages/shop.scss>`_.
 
@@ -54,11 +56,13 @@ The client is thrilled with the shop modifications. Next, let's apply our design
 pages. Based on the Airproof design below, adapt a few elements including:
 
 - Remove the search bar (if not done with the previous exercise).
+- Move the breadcrumb.
 - Remove the quantity selector, Terms and Conditions, and share icons.
 - Update the :guilabel:`Add to cart` button icon.
-- Insert a title above the product specifications (this section appears only when the product
-  has one variant per attribute).
-- Design the appropriate layout for the carousel.
+- Enable the accordion "*More information*".
+- Insert the product specifications (section that only appears when the product has just one variant
+  per attribute) into the accordion containing the "*more information*" section.
+- Design the appropriate layout for the product images carousel.
 - Add a title and apply the previously created product template to the `Alternative products`
   section (ensure alternative products are assigned on the product in the backend for this section
   to appear).