[IMP] howto/website_themes: Building blocks page update

- Change the Github urls to the correct version of Odoo
- Adapt the way of creating a snippet template and how to add it to the builder
- Add explanation about how to make a custom snippet "inner content"

content/developer/howtos/website_themes/building_blocks.rst

@@ -5,12 +5,12 @@ Building blocks
 Building blocks, also known as snippets, are how users design and layout pages. They are important
 XML elements of your design.
 
-The building blocks are classified into four categories:
+The building blocks are classified into two types:
 
-#. **Structure blocks**: to give a basic structure to the website
-#. **Feature blocks**: to describe the features of a product or service
-#. **Dynamic Content blocks**: blocks that are animated or interact with the backend
-#. **Inner Content blocks**: blocks used inside other building blocks
+#. **Structure blocks**: visually used as "whole rows" and distributed into multiples categories
+   (:guilabel:`Intro`, :guilabel:`Columns`, :guilabel:`Content`, :guilabel:`Images`,
+   :guilabel:`People`, etc)
+#. **Inner Content blocks**: used inside other building blocks
 
 At the end of this chapter, you will be able to :ref:`create custom snippets
 <website_themes/building_blocks/custom>` and to add them into a dedicated category.
@@ -427,15 +427,21 @@ snippet (e.g., :file:`001.js`, :file:`002.scss`).
 Custom snippet
 ==============
 
-To create a custom snippet, create first the snippet template. Then, add it to the list and make it
-available via the Website Builder.
+Some more specific needs will require the creation of custom snippets. Here is how to create a
+custom snippet/
 
 .. _website_themes/building_blocks/custom/template:
 
 Template
 --------
 
-**Declaration**
+Create first the snippet template. Then, add it to the list and make it available via the Website
+Builder.
+
+1. Declaration
+~~~~~~~~~~~~~~
+
+First, create the template of the custom snippet:
 
 .. code-block:: xml
    :caption: ``/website_airproof/views/snippets/s_airproof_snippet.xml``
@@ -464,25 +470,63 @@ Template
    - Avoid using ID attribute within your `section` as several instances of a snippet may appear
      throughout the page (An ID attribute has to be unique on a page).
 
-Add your custom snippet to the list of standard snippets, so the user can drag and drop it on the
+Add the custom snippet to the list of standard snippets, so the user can drag and drop it on the
 page, directly from the edit panel.
 
+2. Group creation
+~~~~~~~~~~~~~~~~~
+
+Add a group at the top of the list (feel free to the put it where needed in this list).
+
 .. code-block:: xml
    :caption: ``/website_airproof/views/snippets/options.xml``
 
-   <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_theme_snippets_category" class="o_panel">
-                   <div class="o_panel_header">Theme</div>
-                   <div class="o_panel_body">
-                       <t t-snippet="website_airproof.s_airproof_snippet" t-thumbnail="/website_airproof/static/src/img/wbuilder/s_airproof_snippet.svg">
-                           <keywords>Snippet</keywords>
-                       </t>
-                   </div>
-               </div>
-           </t>
-       </xpath>
+   <template id="snippets" inherit_id="website.snippets" name="Airproof - Snippets">
+      <!-- Create the group -->
+      <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_group_thumbnail.svg"/>
+      </xpath>
+   </template>
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 20 80
+
+   * - Attribute
+     - Description
+   * - snippet-group
+     - ID of the group
+   * - t-snippet
+     - Inherited template ID
+   * - string
+     - Group name displayed to the users
+   * - t-thumbnail
+     - The path to the thumbnail of the group
+
+3. Snippet addition
+~~~~~~~~~~~~~~~~~~~
+
+Then add the custom snippet into the `<snippets id="snippet_structure">` which contains
+all existing ones on the same level. The Website Builder will split them automatically into
+categories by reading the `group` attribute on the `<t t-snippet="">`
+
+.. code-block:: xml
+   :caption: ``/website_airproof/views/snippets/options.xml``
+   :emphasize-lines: 7-12
+
+   <template id="snippets" inherit_id="website.snippets" name="Airproof - Snippets">
+      <!-- Create the group -->
+      <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_group_thumbnail.svg"/>
+      </xpath>
+
+      <!-- Add the custom snippet to the group -->
+      <xpath expr="//snippets[@id='snippet_structure']/*[1]" position="before">
+         <t t-snippet="website_airproof.s_airproof_snippet" string="Custom snippet" group="airproof">
+            <keywords>Snippet</keywords>
+         </t>
+      </xpath>
    </template>
 
 .. list-table::
@@ -493,12 +537,34 @@ page, directly from the edit panel.
    * - Attribute
      - Description
    * - t-snippet
-     - The template to use
-   * - t-thumbnail
-     - The path to the snippet thumbnail
+     - The snippet template to use
+   * - group
+     - The group in which the snippet is added.
    * - <keywords>
      - Keywords entered by the user in the search field in the Snippets panel
 
+Inner content snippet
+~~~~~~~~~~~~~~~~~~~~~
+
+To make a custom snippet appearing in the :guilabel:`Inner content` list, add it to the `snippet_content`
+instead:
+
+.. code-block:: xml
+   :caption: ``/website_airproof/views/snippets/options.xml``
+
+   <template id="snippets" inherit_id="website.snippets" name="Airproof - Snippets">
+      <!-- Add the custom snippet to the group -->
+      <xpath expr="//snippets[@id='snippet_content']/*[1]" position="before">
+         <t t-snippet="website_airproof.s_airproof_snippet" string="Custom snippet" t-thumbnail="/website_airproof/static/src/img/wbuilder/s_airproof_snippet.svg" />
+      </xpath>
+   </template>
+
+.. important::
+   - Don't forget to add a `t-thumbnail` and remove the `group` attribute as this kind of building
+     blocks is directly available in the right options panel of the Website Builder.
+   - Don't forget to :ref:`add the snippet to the list of all available "Inner content" snippets
+     <website_themes/building_blocks/custom/options/inner_content>`.
+
 .. _website_themes/building_blocks/custom/options:
 
 Options
@@ -508,7 +574,7 @@ Options allow users to edit a snippet's appearance/behavior using the Website Bu
 snippet options easily and automatically add them to the Website Builder.
 
 .. seealso::
-   `Standard snippet options <https://github.com/odoo/odoo/blob/ccb78f7af2a4413836a969ff8009dc3df6c2df33/addons/website/views/snippets/snippets.xml>`_
+   `Standard snippet options <https://github.com/odoo/odoo/blob/247f28fdec788c7eb7c4288db29b931c73a23757/addons/website/views/snippets/snippets.xml>`_
 
 .. _website_themes/building_blocks/custom/options/template:
 
@@ -552,6 +618,8 @@ Then insert the different available options:
       </xpath>
    </template>
 
+.. _website_themes/building_blocks/custom/options/inner_content:
+
 **Inner content**
 
 Make a custom snippet "inner content" (droppable in an other building block) by extending the
@@ -570,7 +638,7 @@ inner content building blocks:
 
 .. seealso::
 
-   `Standard "inner content" snippets declaration on Odoo's GitHub repository <https://github.com/odoo/odoo/blob/f922f09b83c68dff36c064d20709a6e6ba4541dc/addons/website/views/snippets/snippets.xml#L720>`_
+   `Standard "inner content" snippets declaration on Odoo's GitHub repository <https://github.com/odoo/odoo/blob/cc05d9d50ac668eaa26363e1127f914897a4b125/addons/website/views/snippets/snippets.xml#L988>`_
 
 .. _website_themes/building_blocks/custom/options/binding:
 
@@ -949,9 +1017,9 @@ There are also built-in methods directly linked to events the Website Builder li
 
 .. seealso::
    - `Web Editor - JavaScript methods related to snippet options on GitHub
-     <https://github.com/odoo/odoo/blob/380c9153b5fa9a0ea6d7ae485ef52a16ae999eda/addons/web_editor/static/src/js/editor/snippets.options.js#L3247>`_
-   - `XML templates of the different snippets
-     <https://github.com/odoo/odoo/blob/ccb78f7af2a4413836a969ff8009dc3df6c2df33/addons/website/views/snippets/snippets.xml>`_
+     <https://github.com/odoo/odoo/blob/cc05d9d50ac668eaa26363e1127f914897a4b125/addons/web_editor/static/src/js/editor/snippets.options.js#L3512>`_
+   - `XML templates of the different standard snippets
+     <https://github.com/odoo/odoo/blob/cc05d9d50ac668eaa26363e1127f914897a4b125/addons/website/views/snippets/snippets.xml>`_
 
 .. _website_themes/building_blocks/custom/options/methods/custom:
 

content/developer/howtos/website_themes/theming.rst

@@ -158,7 +158,8 @@ always required. It usually contains much more information.
       (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.
+      structure, using the first two arguments to indicate your current Odoo version (for
+      instance, `{BRANCH}`).
 
    .. image:: theming/versioning.png
       :alt: Module versioning
@@ -562,6 +563,167 @@ values and *not* the :file:`primary_variables.scss` file.
 
    http://localhost:8069/website/demo/bootstrap
 
+.. _theming/module/bootstrap/fonts:
+
+Font sizes
+~~~~~~~~~~
+
+Odoo has CSS font size classes to separate style (font sizes) and semantic (tag and styles in
+general). Both logic can be combined to be more flexible.
+
+.. seealso::
+   `Bootstrap documentation about display headings
+   <https://getbootstrap.com/docs/5.1/content/typography/#display-headings>`_
+
+.. _theming/module/bootstrap/fonts/text:
+
+Text style
+**********
+
+Odoo's Website Builder allows to select a style for your text. Some are just tag related like the
+`Header` with no extra CSS class. Other combine tag and style directly applied on them like the
+`Header 1 Display`.
+
+.. image:: theming/header.png
+   :alt: Header styles
+   :width: 300
+
+.. code-block:: xml
+
+   <!-- h1 with display heading sizes -->
+   <h1 class="display-1">Heading 1 with Display Heading 1 size</h1>
+   <h1 class="display-2">Heading 1 with Display Heading 2 size</h1>
+   <h1 class="display-3">Heading 1 with Display Heading 3 size</h1>
+   <h1 class="display-4">Heading 1 with Display Heading 4 size</h1>
+
+   <!-- Lead text - named "Light" in the dropdown -->
+   <p class="lead">A text typically used as an introduction.</p>
+
+   <!-- Small text -->
+   <p class="o_small">Body text with a smaller size.</p>
+
+.. _theming/module/bootstrap/fonts/sizing:
+
+Sizing classes
+**************
+
+The sizing classes are added on a freshly created `span` tag inside the targeted element (See
+examples below).
+
+.. image:: theming/sizing.png
+   :alt: Sizing classes
+   :width: 300
+
+.. _theming/module/bootstrap/fonts/sizing/headings-and-body:
+
+Heading and body text
+^^^^^^^^^^^^^^^^^^^^^
+
+Assuming these classes can be applied on any text element, take `h2` as an example below:
+
+.. code-block:: xml
+
+   <!-- h2 sized like an h1 -->
+   <h2><span class="h1-fs">Heading</span></h2>
+
+   <!-- h2 sized with other heading sizes -->
+   <h2><span class="h2-fs">Heading</span></h2>
+   <h2><span class="h3-fs">Heading</span></h2>
+   <h2><span class="h4-fs">Heading</span></h2>
+   <h2><span class="h5-fs">Heading</span></h2>
+   <h2><span class="h6-fs">Heading</span></h2>
+
+   <!-- h2 sized like a normal paragraph (base size, 16px by default) -->
+   <h2><span class="base-fs">Heading</span></h2>
+
+   <!-- h2 sized like a small text (14px by default) -->
+   <h2><span class="o_small-fs">Heading</span></h2>
+
+.. _theming/module/bootstrap/fonts/sizing/display:
+
+Display headings
+^^^^^^^^^^^^^^^^
+
+If larger titles are needed, Odoo uses Bootstrap's Display Headings classes, from `display-1` to `6`.
+
+.. code-block:: xml
+
+   <h2><span class="display-1-fs">Heading</span></h2>
+   <h2><span class="display-2-fs">Heading</span></h2>
+   <h2><span class="display-3-fs">Heading</span></h2>
+   <h2><span class="display-4-fs">Heading</span></h2>
+
+.. note::
+   The Website Builder allows the user to configure only sizes from `Display 1` to `Display 4`. You
+   can set the other sizes (`5` and `6`) to use them in your code but the user won't be able to
+   modify them directly within the Website Builder interface.
+
+.. _theming/module/website:
+
+Website settings
+----------------
+
+Global options related to the website can be set through the website record by following the
+structure below.
+
+**Declaration**
+
+.. code-block:: xml
+   :caption: ``/website_airproof/data/website.xml``
+
+   <?xml version="1.0" encoding="utf-8"?>
+   <odoo noupdate="1">
+      <record id="website.default_website" model="website">
+         <field name="name">Airproof</field>
+         <field name="logo" type="base64" file="website_airproof/static/src/img/content/logo_pred.png"/>
+         <field name="favicon" type="base64" file="website_airproof/static/description/favicon.png" />
+         <field name="shop_ppg">18</field>
+         <field name="shop_ppr">3</field>
+         <field name="cookies_bar" eval="True" />
+         <field name="contact_us_button_url">/contact-us</field>
+         <field name="social_facebook">https://www.facebook.com/Airproof</field>
+         <field name="social_instagram">https://www.instagram.com/airproof</field>
+         <field name="social_linkedin">https://www.linkedin.com/company/airproof</field>
+         <field name="social_youtube">https://www.youtube.com/c/airproof</field>
+      </record>
+   </odoo>
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 20 80
+
+   * - Field
+     - Description
+   * - name
+     - Name of the website (displayed in the browser)
+   * - logo
+     - Path to the logo (previously created into a record)
+   * - favicon
+     - Path to the favicon (previously created into a record)
+   * - shop_ppg
+     - Number of products shown per page in the e-commerce
+   * - shop_ppr
+     - Number of products shown per rows (in a page) in the e-commerce
+   * - cookies_bar
+     - Enable/disable the cookies bar
+   * - contact_us_button_url
+     - URL of the `Contact us` page (For instance, used in the standard header templates).
+   * - social_facebook
+     - URL of a Facebook profile
+   * - social_instagram
+     - URL of a Instagram profile
+   * - social_linkedin
+     - URL of a LinkedIn company profile
+   * - social_youtube
+     - URL of a YouTube channel
+
+.. note::
+
+   `website.default_website` is the default reference whenever you work with only one website. If
+   there are several websites in your database, this record will refer to the default site (the
+   first one).
+
 .. _theming/module/views:
 
 Views