odoo-docs/content/developer/tutorials/website_theme/03_customisation_part1.rst

=================================
Chapter 3 - Customisation, Part I
=================================

.. _tutorials/website_theme/customisation_part1/custom_scss:

Add custom SCSS
===============

You've adjusted Odoo and Bootstrap variables and set presets, yet you still notice disparities
between your website and the client's design. The only solution is to incorporate custom SCSS.

In :file:`theme.scss`, reproduce the following design elements:

- Add a **green underline** on active nav items.
- Modify the **arrow** for collapsible nav items.
- Modify the **slider's arrows** by adding a green background and changing their design.

You will find the various `media here
<{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content/icons>`_.

.. seealso::
   See reference documentation on how to :ref:`add your SCSS rules <theming/assets/styles>`.

.. image:: 03_customisation_part1/menu.png
   :scale: 50%

.. image:: 03_customisation_part1/slider.png

.. note::
   | It's always preferable to include all your SCSS rules in `#wrapwrap`. This ID is applied to the
     div that groups the :guilabel:`header`, :guilabel:`footer`, and :guilabel:`main` content of all
     your pages.
   | So you will be sure that your rules will only have an impact on the website parts.

.. spoiler:: Solutions

   Find the solution in our Airproof example on `header.scss
   <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/layout/header.scss>`_
   and `caroussel.scss
   <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/snippets/caroussel.scss>`_.

.. _tutorials/website_theme/customisation_part1/custom_js:

Add custom JS
=============

Now, let's add a mouse follower to the website. This interactive element will enhance the browsing
experience, making it more engaging and visually appealing.

.. image:: 03_customisation_part1/mouse-follower.gif

Use your JavaScript skills to implement this.

.. seealso::
   See reference documentation on how to :ref:`add Javascript code <theming/assets/interactivity>`.

.. spoiler:: Solutions

   Find the solution in our Airproof example on `mouse_follower.js
   <{GITHUB_TUTO_PATH}/website_airproof/static/src/js/mouse_follower.js>`_ and `mouse_follower.scss
   <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/components/mouse_follower.scss>`_.

.. _tutorials/website_theme/customisation_part1/custom_header:

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:

   - A custom shopping cart icon.
   - A login/user as a button.
   - Navigation text to 14px.

   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`,
   - 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

.. tip::
   - Base yourself on the code of existing header templates that you can find in
     `odoo/addons/website/views/website_templates.xml
     <{GITHUB_PATH}/addons/website/views/website_templates.xml>`_.
   - A good practise should be to create different files to manage your custom views and templates.
     For example, everything concerning the general layout (header, footer...) in
     :file:`website_templates.xml`, everything related to blog in :file:`website_blog_templates.xml`,
     to event in :file:`website_event_templates.xml`, etc.
   - | To modify the cart icon, you can use an `XPath`.
     | Since this is linked to eCommerce, place it in a new file called
       :file:`website_sale_templates.xml`.
   - Don't forget to continue making as many modifications as you can through the :file:`Bootstrap
     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 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:

     .. code-block:: xml
        :caption: ``/website_airproof/data/presets.xml``

        <!-- Disable default header -->
        <record id="website.template_header_default" model="ir.ui.view">
           <field name="active" eval="False"/>
        </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
     <{GITHUB_TUTO_PATH}/website_airproof/data/presets.xml>`_.
   - make the use of `primaries
     <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/primary_variables.scss>`_ like
     `header-template`, `navbar-font`, `header-font-size`...
   - use `bootstrap_overridden
     <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/bootstrap_overridden.scss>`_ like
     `$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:

Create a custom footer
======================

The client is delighted with the new header, as it aligns perfectly with the provided design. Now,
he wants a matching custom footer.

Based on the Airproof design, create a custom footer with the following elements:

- A section for newsletter subscription.
- A section for the copyright and social media.

You will find the `icons here <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content/icons>`_.

.. seealso::
   See reference documentation on how to create a :ref:`custom footer
   <website_themes/layout/footer/custom>` and adapt the :ref:`website_themes/layout/copyright`.

.. image:: 03_customisation_part1/footer.png

.. tip::
   - You can enable or disable the copyright section via the presets.
   - For the newsletter section to work, you need to install the `website_mass_mailing` application.

.. spoiler:: Solutions

   To complete this exercise, you need to:

   - add `mass mailing` to your depends:

     .. code-block:: python
         :caption: ``/website_airproof/__manifest__.py``
         :emphasize-lines: 2

         'depends': ['website_sale', 'website_sale_wishlist', 'website_blog',
         'website_mass_mailing'],

   - find the xml structure and add the template to the options list on
     `website_template.xml <{GITHUB_TUTO_PATH}/website_airproof/views/website_templates.xml>`_.
   - disable the default footer and enable the copyright:

     .. code-block:: xml
        :caption: ``/website_airproof/data/presets.xml``

        <!-- Disable Default Footer -->
        <record id="website.footer_custom" model="ir.ui.view">
           <field name="active" eval="False"/>
        </record>
        <!-- Enable Copyright -->
        <record id="website.footer_no_copyright" model="ir.ui.view">
           <field name="active" eval="False"/>
        </record>

   - make the use of `primaries
     <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/primary_variables.scss>`_ like
     `footer-template`, `footer`, `o-cc4-link`...
   - add a little scss rule for the `newsletter
     <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/snippets/newsletter.scss>`_ section.

.. _tutorials/website_theme/customisation_part1/custom_building_blocks:

Create your custom building blocks
==================================

To allow your client to further customize his website, create tailor-made building blocks that he
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. 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>`_.

   .. seealso::
      See reference documentation on how to create a :ref:`custom building blocks
      <website_themes/building_blocks/custom>`.

   .. image:: 03_customisation_part1/custom-building-block.png

#. 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
      <website_themes/building_blocks/custom/options>`.

   .. image:: 03_customisation_part1/custom-building-block-option.png
      :scale: 75%

#. Add the snippet on your homepage.

.. tip::
   Don't forget to always properly declare your new files in your :file:`__manifest__.py` and follow
   the good :ref:`folder structure <theming/module/structure>` seen previously.

.. spoiler:: Solutions

   To complete this exercise, you need to:

   #. Create your template.

      - You can find all the necessary information in `s_airproof_carousel.xml
        <{GITHUB_TUTO_PATH}/website_airproof/views/snippets/s_airproof_carousel.xml>`_ file and
        `s_airproof_carousel/000.scss
        <{GITHUB_TUTO_PATH}/website_airproof/static/src/snippets/s_airproof_carousel/000.scss>`_
        file from our example module.
      - Record your images in `images.xml <{GITHUB_TUTO_PATH}/website_airproof/data/images.xml>`_.
      - Declare your files in the `__manifest__.py
        <{GITHUB_TUTO_PATH}/website_airproof/__manifest__.py>`_.
      - Add it to the list of building blocks. In our example, it looks like this:

        .. code-block:: xml
           :caption: ``/website_airproof/views/snippets/options.xml``

           <!-- Add custom snippets to the builder -->
           <template id="snippets" inherit_id="website.snippets" name="Airproof - Custom Snippets">
              <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>

   #. Add the option to the Website Builder. In our example, it looks like this:

      .. code-block:: xml
         :caption: ``/website_airproof/views/snippets/s_airproof_carousel.xml``

         <!-- Add options to snippets -->
         <template id="snippet_options" inherit_id="website.snippet_options" name="Airproof -
         Snippets Options">
            <xpath expr="." position="inside">
               <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
      <{GITHUB_TUTO_PATH}/website_airproof/static/src/snippets/s_airproof_carousel/000.scss>`_ file.

   #. Add your snippet to the homepage. You can find all the necessary information in the `home.xml
      <{GITHUB_TUTO_PATH}/website_airproof/data/pages/home.xml>`_ file from our example module.

.. _tutorials/website_theme/customisation_part1/custom_dynamic_template:

Create a new dynamic snippets template
======================================

| Dynamic snippets are useful building blocks. These allow you to fetch information from the backend
  and display it on the website according to certain filters.
| There are already several layout templates for displaying dynamic snippets. However, none of the
  existing templates fully match your client's needs.

Based on the Airproof design, create a custom template that you will apply to a product dynamic
snippet on the homepage.

#. First, create a custom template that will be added to the list of dynamic products templates. It
   has to include the following elements:

   - Add a :guilabel:`Discover more` link.
   - Add a hover effect on cards.
   - Move the navigation arrows.

   You will find the `icons here <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content/icons>`_.

   .. seealso::
      See reference documentation on how to :ref:`create a template for dynamic snippets
      <website_themes/building_blocks/custom/dynamic>`.

   .. image:: 03_customisation_part1/custom-template.png

   .. tip::
      You can verify in the Website Builder that your template appears in the list of available
      templates for the product dynamic snippet.

#. Then, add a product dynamic snippet with the template you just created to the homepage.

   .. seealso::
      See reference documentation on how to :ref:`call a template
      <website_themes/building_blocks/custom/dynamic/call>`.

.. spoiler:: Solutions

   To complete this exercise, you need to:

   #. Create your snippet template. You can find all the necessary information in the
      `options.xml <{GITHUB_TUTO_PATH}/website_airproof/views/snippets/options.xml>`_
      file and `caroussel.scss
      <{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/snippets/caroussel.scss>`_ file from our
      example module.

   #. Apply the template to a product dynamic snippet on the homepage. You can find all the
      necessary information in the `home.xml
      <{GITHUB_TUTO_PATH}/website_airproof/data/pages/home.xml>`_ file from our example module.