diff --git a/content/developer/howtos/website_themes/building_blocks.rst b/content/developer/howtos/website_themes/building_blocks.rst index 255fbfff0..cc3b09d17 100644 --- a/content/developer/howtos/website_themes/building_blocks.rst +++ b/content/developer/howtos/website_themes/building_blocks.rst @@ -12,7 +12,10 @@ The building blocks are classified into four categories: #. **Dynamic Content blocks**: blocks that are animated or interact with the backend #. **Inner Content blocks**: blocks used inside other building blocks -In this chapter, you will learn how to create custom building blocks and options. +At the end of this chapter, you will be able to :ref:`create custom snippets +` and to add them into a dedicated category. + +.. _website_themes/building_blocks/file_structure: File structure ============== @@ -21,32 +24,37 @@ The layout's file structure is the following. :: - views - ├── snippets - │ └── options.xml - │ └── s_snippet_name.xml + views + ├── snippets + │ └── options.xml + │ └── s_snippet_name.xml The styles' file structure is the following. :: - static - ├── src - │ └── snippets - │ └── options.scss - │ └── s_snippet_name - │ └── 000.js - │ └── 000.scss - │ └── 000.xml - │ └── option.js + static + ├── src + │ └── snippets + │ └── s_snippet_name + │ └── 000.js + │ └── 000.scss + │ └── 000.xml + │ └── options.js .. seealso:: `XML templates of the different snippets - <{GITHUB_PATH}/addons/website/views/snippets/snippets.xml>`_ + `_ .. admonition:: Demo page - http://localhost:8069/website/demo/snippets + Demo data have to be installed to access this page: + + :: + + https://your-database.com/website/demo/snippets + +.. _website_themes/building_blocks/layout: Layout ====== @@ -54,6 +62,8 @@ Layout Snippets are editable by the user using the Website Builder. Some Bootstrap classes are important as **they trigger some Website Builder options**. +.. _website_themes/building_blocks/layout/wrapper: + Wrapper ------- @@ -74,8 +84,6 @@ For inner content snippets, any other HTML tag can be used. -.. todo:: Missing description in table ... - .. list-table:: :header-rows: 1 :stub-columns: 1 @@ -101,8 +109,30 @@ drop based on the template's name. Avoid adding a `section` tag inside another `section` tag: this will trigger twice the Website Builder's options. You can use inner content snippets instead. -Columns -------- +.. tip:: + To write the content of a static page with standard snippets, there are two possible approaches: + + - **Pre-build the custom static pages with the Website Builder:** Drag & drop snippets, then + copy/paste the code into your file and clean it up. + + | **OR** + + - **Code everything directly:** But beware of compatibility with the Website Builder. It + requires certain classes, names, id, data, etc. to work properly. A good practice is to seek + out the snippets code created in standard code in the Odoo source files. Pay attention that + the Website Builder sometimes adds classes to the snippets after dropped in the page. + +.. _website_themes/building_blocks/layout/elements: + +Elements +-------- + +There is a list of "features" we can enable/disable by using specific CSS classes. + +.. _website_themes/building_blocks/layout/elements/sizing: + +Sizing +~~~~~~ Any large Bootstrap columns directly descending from a `.row` element (respecting Bootstrap structure) will be triggered by the Website Builder to make them resizable. @@ -111,23 +141,16 @@ structure) will be triggered by the Website Builder to make them resizable. .row > .col-lg-* -Add padding on columns and sections. +Add padding on columns and `
`. .. code-block:: xml class="pt80 pb80" -Add a background based on the color palette for columns and sections. +.. note:: -.. code-block:: xml - - class="o_cc o_cc*" - -Make an element not editable. - -.. code-block:: xml - -
+ `pb*` and `pt*` are the Odoo classes used to control the handlers. Their values are + increased by **multiples of 8**, till a **max of 256** (0, 8, 16, 24, 32, 40, 48, ...). Enable the columns selector. @@ -135,47 +158,47 @@ Enable the columns selector.
-Disable the columns option. +Disable the columns amount option. .. code-block:: xml
-Disable the size option of all child columns. +Disable the size option for all child columns. .. code-block:: xml
-Disable the size option for one column. +Disable the size option for one specific column. .. code-block:: xml
+.. _website_themes/building_blocks/layout/elements/colors: + +Colors +~~~~~~ + +Add a background based on the color palette for columns and `
`. + +.. code-block:: xml + + class="o_cc o_cc*" + Disable the background color option for all columns. .. code-block:: xml
-Disable the background color option of one column. +Disable the background color option of one specific column. .. code-block:: xml
-Add parallax effect. - -.. code-block:: xml - -
- -
- -
-
- Add a black color filter with an opacity of 50%. .. code-block:: xml @@ -220,28 +243,114 @@ Add a custom gradient filter.
-Styles -====== +.. _website_themes/building_blocks/layout/elements/features: -Compatibility system --------------------- +Features +~~~~~~~~ -When a snippet has a `data-vcss` or `data-vjs` attribute, it means it is an updated version, not the -original one. +Make an element not editable. .. code-block:: xml -
+
+ +Make an element not removable. + +.. code-block:: xml + +
+ +Add a background image and have it centered. + +.. code-block:: xml + +
+ +Add parallax effect. + +.. code-block:: xml + +
+ +
+ +
+
+ +.. todo:: Update the ref below after the Media section has been created (howto/website_themes/media_videos). + +.. note:: + + A video background can be set on a section. Refer to the ":doc:`media`" chapter of this documentation. + +.. _website_themes/building_blocks/layout/grid: + +Grid layout +----------- + +Grid Layout is a powerful and flexible layout system in CSS that enables users to design complex +building block layouts with ease. + +Enable the Grid Layout by adding the `o_grid_mode` class on the `row`. The number of rows in your +grid is defined in the `data-row-count` attribute. The grid always contains 12 columns. + +**Use** + +.. code-block:: xml + +
+ +
+ +Add items in the grid with the `o_grid_item` class. If the grid item contains an image, use the +`o_grid_item_image` class. + +.. code-block:: xml + :emphasize-lines: 2,3,4,5,6 + +
+
+ +
+
+ ... +
+
+ +The dimensions and position of a grid item are defined by the grid-area that can be explicitly set +in the `style` attribute along with the z-index. + +The `g-height-*` and `g-col-lg-*` classes are generated by the Website Builder for editing purposes. + +.. _website_themes/building_blocks/compatibility: + +Compatibility system +==================== + +When a snippet has a `data-vcss`, `data-vjs` and/or `data-vxml` attribute, it means it is an updated + version, not the original one. + +.. code-block:: xml + +
-The `data-vcss` and `data-js` attributes indicate to the system which file version to load for that +These data attributes indicate to the system which file version to load for that snippet (e.g., :file:`001.js`, :file:`002.scss`). -Custom -====== +.. _website_themes/building_blocks/custom: -Create the snippet's content. +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. + +.. _website_themes/building_blocks/custom/template: + +Template +-------- **Declaration** @@ -261,21 +370,24 @@ Create the snippet's content. .. warning:: `data-name` and `data-snippet` attributes have to be specified when a snippet is declared on a - theme page. + theme page. Otherwise, the snippet won't be recognised by the Website Builder and issues might + occur whenever a database upgrade is done. Additionally, remember that the name attribute is + shown as the name of your custom snippet in the :guilabel:`Blocks` section of the options panel. .. tip:: - Use Bootstrap native classes as much as possible. - Prefix all your custom classes. - Use underscore lowercase notation to name classes, e.g., `.x_nav`, `.x_nav_item`. - - Avoid using ID tag. + - 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 default snippets, so the user can drag and drop it on the +Add your custom snippet to the list of standard snippets, so the user can drag and drop it on the page, directly from the edit panel. .. code-block:: xml :caption: ``/website_airproof/views/snippets/options.xml`` -