diff --git a/content/developer/howtos/website_themes/shapes.rst b/content/developer/howtos/website_themes/shapes.rst index 6db3b13e61..4ebddceef2 100644 --- a/content/developer/howtos/website_themes/shapes.rst +++ b/content/developer/howtos/website_themes/shapes.rst @@ -2,32 +2,33 @@ Shapes ====== -Shapes are handy if you want to add personality to your website. +Shapes are handy if you want to add personality to your website. In this chapter, you will learn +how to add standard and custom background/image shapes. -In this chapter, you will learn how to add standard and custom background and image shapes. +They are SVG files that you can add as a decorative background in your different +sections or directly on your images. Each shape has one or several customizable colors, and some of +them are animated. + +.. warning:: + Odoo's default shapes use the `Odoo default colors palette `_ + map as reference. This way, colors will be automatically adapted to a new + :ref:`palette ` everytime it changes: + + .. code-block:: scss + + default_palette = { + '1': '#3AADAA', + '2': '#7C6576', + '3': '#F6F6F6', + '4': '#FFFFFF', + '5': '#383E45', + } .. _website_themes/shapes/bg: Background shapes ================= -Background shapes are SVG files that you can add as a decorative background in your different -sections. Each shape has one or several customizable colors, and some of them are animated. - -.. warning:: - Odoo's default shapes use the Odoo default colors palette map as reference. This way, colors - will be automatically adapted to a new palette everytime it changes: - - .. code-block:: scss - - default_palette = { - '1': '#3AADAA', - '2': '#7C6576', - '3': '#F6F6F6', - '4': '#FFFFFF', - '5': '#383E45', - } - .. _website_themes/shapes/bg/standard: Standard @@ -35,15 +36,18 @@ Standard A large selection of default background shapes is available. -**Use** +.. _website_themes/shapes/bg/standard/usage: + +Usage +~~~~~ .. code-block:: xml
-
-
- -
+
+
+ +
`data-oe-shape-data` is a JSON object containing information about your shape like the location @@ -55,10 +59,10 @@ this: .. code-block:: xml
-
-
- -
+
+
+ +
.. _website_themes/shapes/bg/standard/colors: @@ -81,20 +85,20 @@ First, we can use a shape like this: .. code-block:: xml - - - - - - - - - - - - - - + + + + + + + + + + + + + + Here, we use `#383E45` and `#FFFFFF` which corresponds to the 5th and 4th colors in the Odoo's default color palette. @@ -154,10 +158,10 @@ keeping the original. .. code-block:: xml
-
-
- -
+
+
+ +
.. _website_themes/shapes/bg/custom: @@ -173,20 +177,13 @@ Firstly, you need to create an SVG file for your shape. :caption: ``/website_airproof/static/shapes/hexagons/01.svg`` - + -Make sure to use colors from the default Odoo palette for your shape (as explained :ref:`above `). +.. important:: + Make sure to use colors from the default Odoo palette for your shape + (as explained :ref:`above `). -.. code-block:: scss - - default_palette = { - '1': '#3AADAA', - '2': '#7C6576', - '3': '#F6F6F6', - '4': '#FFFFFF', - '5': '#383E45', - } .. _website_themes/shapes/bg/custom/attachment: Attachment @@ -198,10 +195,10 @@ Declare your shape file. :caption: ``/website_airproof/data/shapes.xml`` - 01.svg - - /html_editor/shape/illustration/hexagons/01.svg - + 01.svg + + /html_editor/shape/illustration/hexagons/01.svg + .. list-table:: @@ -274,36 +271,36 @@ Lastly, add your shape to the list of shapes available on the Website Builder by `background_shape_groups_providers` resource. .. code-block:: javascript - :caption: ``/website_airproof/static/src/builder/airproof_background_shapes.js`` + :caption: ``/website_airproof/static/src/builder/background_shapes_option_plugin.js`` import { Plugin } from "@html_editor/plugin"; import { _t } from "@web/core/l10n/translation"; import { registry } from "@web/core/registry"; - export class AirproofBackgroundShapesPlugin extends Plugin { - static id = "airproofBackgroundShapes"; - resources = { - background_shape_groups_providers: () => ({ - airproof: { - label: _t("Airproof"), - subgroups: { - airproof: { - label: _t("Airproof"), - shapes: { - "illustration/airproof/01": { - selectLabel: _t("Airproof 01"), - }, - }, - }, - }, + export class AirproofBackgroundShapesOptionPlugin extends Plugin { + static id = "airproofBackgroundShapesOption"; + resources = { + background_shape_groups_providers: () => ({ + airproof: { + label: _t("Airproof"), + subgroups: { + airproof: { + label: _t("Airproof"), + shapes: { + "website_airproof/waves/01": { + selectLabel: _t("Airproof 01"), + }, + }, + }, }, - }), - }; + }, + }), + }; } registry.category("website-plugins").add( - AirproofBackgroundShapesPlugin.id, - AirproofBackgroundShapesPlugin + AirproofBackgroundShapesOptionPlugin.id, + AirproofBackgroundShapesOptionPlugin ); .. note:: @@ -318,11 +315,484 @@ In your XML pages, you can use your shape in the same way as the others. .. code-block:: xml -
-
-
- -
-
+
+
+
+ +
+
-You can also redefine colors using the `data-oe-shape-data attribute`, but this is optional. +You can also redefine colors using the `data-oe-shape-data` attribute, but this is optional. + +.. _website_themes/shapes/img: + +Image shapes +============ + +Image shapes are SVG files you can add as a clipping mask on your images. Some shapes have +customizable colors, and some are animated. + +.. _website_themes/shapes/img/standard: + +Standard +-------- + +A large selection of default image shapes is available. + +.. _website_themes/shapes/img/standard/use: + +Usage +~~~~~ + +A shape can only be applied on an image that has been previously declared in an `ir.attachment` +record as the Website Builder needs to re-process the image. To summarize, the system injects the +original image into a SVG file containing both the image and the shape. + +.. code-block:: xml + + ... + +Once the shape applied, the `img` includes different data attributes allowing the Website Builder +to re-process the image if it is edited again: + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 20 80 + + * - Attribute + - Description + * - data-shape + - Location of the shape + * - data-shape-colors + - Colors (5 max) applied to the shape (each value, even if empty, are separated by a semicolon) + * - data-mimetype + - Mimetype of the shaped image + * - data-mimetype-before-conversion + - Mimetype of the original image + * - data-original-src + - Path to the original image file + * - data-file-name + - Name of the file which is created after a shape modification (Always use `.svg` extension as + the image shape is applied into an SVG file containing the shape and the original image). + * - data-original-id + - Identifier of the original `ir.attachment` (related to the uploaded image) + * - data-attachment-id + - Identifier of the `ir.attachment` related to the shaped image. + +**Call the shape** + +Insert a shaped image requires to call the processed attachment, not just the original image. +When a shape is manually applied with the Website Builder: + +#. The original record is processed and the `src` attribute is updated with a `base64` image. +#. Once the page is saved, the base64 image is moved into the final SVG (specified in `data-file-name`). +#. Finally, the `src` attribute is updated with the following path structure: + `/web/image/-/.svg` + +But here are 2 issues: + +#. Convert the final image into `base64` format is not that easy (as this is not really *human readable*). +#. The `checksum` computation of the final `ir.attachment` uses an algorithm. + +In a way or another, an external tool would be required but the `html_editor` module provides a +controller with a useful route that can mix an image shape and an image file: + +.. code-block:: python + :emphasize-lines: 3 + + @http.route([ + '/web_editor/image_shape///', + '/html_editor/image_shape///'], + type='http', auth="public", website=True) + +.. seealso:: + `HTML Editor - Image shape route `_ + +Focus on `/html_editor` path, which is the "new name" for the old Web Editor used +up to Odoo 18, and replace the placeholders with real data: + +.. code-block:: xml + :emphasize-lines: 2 + + ... + +.. important:: + Keep in mind that as long as the image is not saved manually with the Website Builder, it is not + stored in the database as a record, **it is generated in real time for each visitor displaying + the page**. So it can have an impact on the loading performances of the website. + +.. _website_themes/shapes/img/standard/colors: + +Colors +~~~~~~ + +The image shapes can include up to 5 colors. As the SVG file contains colors related to the Odoo +default colors palette, the system is able to map the colors existing in the file and match the ones +called in the `data-shape-colors` attribute of the image. + +.. code-block:: xml + :emphasize-lines: 6 + + ... + +In the example above, the color `#0B8EE6` is applied as the first color of the palette. Considering +the first color in the default palette is `#3AADAA`, the Website Builder replaces `#3AADAA` by +`#0B8EE6`. + +.. image:: shapes/image-shape-colors-example.jpg + :alt: Color edition + +.. _website_themes/shapes/img/standard/transform: + +Transformations & Stretch +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some shapes can be adjusted with transformations (Flip, rotate): + +.. image:: shapes/img-shape-slanted-transform.png + :alt: Transformations and stretch options + +.. code-block:: xml + :emphasize-lines: 6-8 + + ... + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 20 80 + + * - Attribute + - Description + * - data-shape-flip + - Flips the shape along the x-axis(`x`), y-axis(`y`) or both(`xy`). + * - data-shape-rotate + - Rotates the shape by 90 degrees (`90`, `180`, `270`). + * - data-aspect-ratio + - Stretch the shape to the image ratio: `1/1` (by default, the image fills the shape) or `0/0` + (:guilabel:`Stretch` option is enabled and the shape fits the image aspect ratio) + +.. _website_themes/shapes/img/standard/animation: + +Animation +~~~~~~~~~ + +Some shapes are animated and their velocity can be adjusted: + +.. image:: shapes/img-shape-speed.png + :alt: Speed option for animated image shapes + +.. code-block:: xml + :emphasize-lines: 6 + + ... + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 20 80 + + * - Attribute + - Description + * - data-shape-animation-speed + - Animation velocity (Range from `-2` to `2` with steps of `0.1`) + +.. _website_themes/shapes/img/custom: + +Custom +------ + +The creation of a custom image shape is quite simple and relies on 2 steps: +#. Create an SVG file with a specific structure +#. Add the custom shape to the list + +.. _website_themes/shapes/img/custom/svg: + +Create the SVG +~~~~~~~~~~~~~~ + +Firstly, create an SVG file for your image shape. + +.. code-block:: xml + :caption: ``/website_airproof/static/image_shapes/duo/01.svg`` + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The SVG file can be created in any vector editing software but requires some adaptations to work +properly with the Website Builder. Let's break down the example above. + +**Main SVG** + +The Image Shape is wrapped into a single main SVG object with explicit `width` and `height` attributes +in pixels: + +.. code-block:: xml + :emphasize-lines: 4-5 + + + ... + + +**Mask** + +The mask is defined into a `` tag in order to be reusable (even if it's not). It's compound +by 2 elements : a `clip-path` and a vector (a `path` in our shape).At this step, what's set into +`defs` does not appear. + +.. code-block:: xml + + + + + + + + + + +**Additional decorations** + +If the shape contains any other decorative element, they are set into the main SVG but outside the +`defs` + +.. code-block:: xml + + + + + +.. tip:: + The main SVG has `width` and `height` attributes expressed in pixels (800 in this example) but + the viewBox is always normalized to values between 0 and 1. As the SVG is a scalable format, it + ensures the image to be sharp no matter its rendered size. + +This decoration has a `fill` color that can be edited with the Website Builder: + +.. image:: shapes/img-shape-colors.png + :alt: Color edition + +.. important:: + + Do not forget to use a color coming from the Odoo default colors palette to make it editable by + the Website Builder (as explained :ref:`above `). + +**Preview** + +Then render the mask in a "preview" by using a reference to the `ìd` set before (`filterPath`): + +.. code-block:: xml + + + + + +**Image** + +Finally, add an `image` tag with a `clip-path` reference. It will receive your future image (in +`base64` format). + +.. code-block:: xml + + + + + + +.. tip:: + Feel free to `run this tool <{GITHUB_PATH}/addons/html_builder/static/image_shapes/convert-to-percentages.html>`_ + in your browser to convert your source SVG file into an image shape compatible file. + +.. _website_themes/shapes/img/custom/option: + +Add it to the list +~~~~~~~~~~~~~~~~~~ + +Finally, add the custom shape to the list: + +.. code-block:: javascript + :caption: ``/website_airproof/static/src/website_builder/image_shapes_option_plugin.js`` + + import { Plugin } from "@html_editor/plugin"; + import { _t } from "@web/core/l10n/translation"; + import { registry } from "@web/core/registry"; + export class AirproofImageShapesOptionPlugin extends Plugin { + static id = "airproofImageShapesOption"; + resources = { + image_shape_groups_providers: () => ({ + airproof: { + label: _t("Airproof"), + subgroups: { + airproof_duo: { + label: _t("Duo"), + shapes: { + "website_airproof/duo/01": { + selectLabel: _t("Airproof 01"), + transform: true, + togglableRatio: true, + }, + }, + }, + }, + }, + }), + }; + } + + registry.category("website-plugins").add( + AirproofImageShapesOptionPlugin.id, + AirproofImageShapesOptionPlugin + ); + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 20 80 + + * - Property + - Description + * - selectLabel + - Name of the shape displayed in the list + * - transform + - Show/hide the transformation option (vertical and horizontal mirror, left and right rotation). + * - togglableRatio + - Show/hide the stretch option. + * - animated + - Indicates if the shape contains some animations + * - imgSize + - Set the image ratio used for :guilabel:`Devices` (example: `0.46:1`) + +.. figure:: shapes/img-shape-transform-ratio.png + :alt: Transform and Stretch options + + Transform and Stretch options + +.. _website_themes/shapes/img/custom/use: + +Use it into your pages +~~~~~~~~~~~~~~~~~~~~~~ + +Custom image shapes can be now applied on images, for example, in your static pages: + +.. code-block:: xml + + ... diff --git a/content/developer/howtos/website_themes/shapes/image-shape-colors-example.jpg b/content/developer/howtos/website_themes/shapes/image-shape-colors-example.jpg new file mode 100644 index 0000000000..adc4cd66b1 Binary files /dev/null and b/content/developer/howtos/website_themes/shapes/image-shape-colors-example.jpg differ diff --git a/content/developer/howtos/website_themes/shapes/img-shape-colors.png b/content/developer/howtos/website_themes/shapes/img-shape-colors.png new file mode 100644 index 0000000000..aba5684241 Binary files /dev/null and b/content/developer/howtos/website_themes/shapes/img-shape-colors.png differ diff --git a/content/developer/howtos/website_themes/shapes/img-shape-slanted-transform.png b/content/developer/howtos/website_themes/shapes/img-shape-slanted-transform.png new file mode 100644 index 0000000000..468ac3bb19 Binary files /dev/null and b/content/developer/howtos/website_themes/shapes/img-shape-slanted-transform.png differ diff --git a/content/developer/howtos/website_themes/shapes/img-shape-speed.png b/content/developer/howtos/website_themes/shapes/img-shape-speed.png new file mode 100644 index 0000000000..e3a4257b0f Binary files /dev/null and b/content/developer/howtos/website_themes/shapes/img-shape-speed.png differ diff --git a/content/developer/howtos/website_themes/shapes/img-shape-transform-ratio.png b/content/developer/howtos/website_themes/shapes/img-shape-transform-ratio.png new file mode 100644 index 0000000000..c660183266 Binary files /dev/null and b/content/developer/howtos/website_themes/shapes/img-shape-transform-ratio.png differ