diff --git a/content/developer/howtos.rst b/content/developer/howtos.rst index 66847299a..a25ab7d3d 100644 --- a/content/developer/howtos.rst +++ b/content/developer/howtos.rst @@ -13,6 +13,7 @@ How-to guides howtos/javascript_view howtos/javascript_client_action howtos/standalone_owl_application + howtos/frontend_owl_components howtos/web_services howtos/company howtos/create_reports @@ -50,6 +51,11 @@ How-to guides Learn how to create a public-facing Owl application outside of the web client using a controller and the Odoo JavaScript framework. + .. card:: Use Owl components on the portal and website + :target: howtos/frontend_owl_components + + Learn how to use Owl components on the portal and website. + .. card:: Web services :target: howtos/web_services diff --git a/content/developer/howtos/frontend_owl_components.rst b/content/developer/howtos/frontend_owl_components.rst new file mode 100644 index 000000000..add8cbebb --- /dev/null +++ b/content/developer/howtos/frontend_owl_components.rst @@ -0,0 +1,187 @@ +============================================ +Use Owl components on the portal and website +============================================ + +In this article, you will learn how you can leverage Owl components on the portal +and website. + +Overview +======== + +To use Owl components on the website or portal, you will need to do a few things: + +- Create your Owl component and register it in the `public_components` registry +- Add that component to the `web.assets_frontend` bundle +- Add an `` tag to a website or portal page to use the component + +1. Creating the Owl component +============================= + +To keep things simple, let's start with a very straightforward component that just renders +"Hello, World!". This will let us know at a glance if our setup is working. + +First, create the template in :file:`/your_module/static/src/portal_component/your_component.xml`. + +.. code-block:: xml + + + + + Hello, World! + + + +Then create the JavaScript file for that component in :file:`/your_module/static/src/portal_component/your_component.js`, +and add it to the `public_components` registry: + +.. code-block:: js + + /** @odoo-module */ + import { Component } from "@odoo/owl"; + import { registry } from "@web/core/registry" + + export class YourComponent extends Component { + static template = "your_module.YourComponent"; + static props = {}; + } + + registry.category("public_components").add("your_module.YourComponent", YourComponent); + + +.. seealso:: + :ref:`Owl components reference`. + + +2. Adding your component to the `web.assets_frontend` bundle +============================================================ + +The `web.assets_frontend` bundle is the assets bundle that is used by the portal and +website, you'll want to add your component's code to that bundle so that the public +components service can find your component and mount it. In your module's manifest, +in the assets section, add an entry for `web.assets_frontend` and add your component's +files: + +.. code-block:: py + + { + # ... + 'assets': { + 'web.assets_frontend': [ + 'your_module/static/src/portal_component/**/*', + ], + } + } + +.. seealso:: + :ref:`Module manifest reference`. + +3. Adding an `` tag to a page +============================================ + +Now we need add an `` tag that will serve as the target for the component +to be mounted. For the sake of this example, we'll add it directly to the portal's +home page with an xpath in :file:`/your_module/views/templates.xml`. + +.. code-block:: xml + + + + + + +Don't forget to add this file to the data section of your assets bundle: + +.. code-block:: py + + { + # ... + 'data': { + 'views/templates.xml', + } + } + +And that's it! If you open the home page of the portal you should see the message +"Hello, World!" at the top of the page. + +Points of caution +================= + +Owl components are rendered entirely in JavaScript by the browser. This can cause +some issues: + +- Layout shift +- Poorer indexing by search engines + +For these reasons, you should only use Owl components on the portal and website for +specific use cases described below. + +Layout shift +------------ + +When a page initially renders content, and that content subsequently moves ("shifts") +within the page, this is referred to as a layout shift. When using Owl components in +the portal or website, all of the HTML that surrounds the Owl component is rendered +by the server and is the first thing that will be displayed to the user. When JavaScript +starts running, Owl will mount your component, which will likely cause the surrounding +elements to move around on the page. This can cause poor user experience: the user sees +an element on the page that was initially rendered and with which they want to interact, +so they move their cursor or finger above that element. Just as they're about to click, +the Owl component is mounted, and the element they want to interact with is moved. +They click and interact with the Owl app instead. + +This can be a frustrating experience, so you should be careful when designing your +page that the Owl component will not move elements around. This can be achieved in +various ways, e.g. by positioning it below all other existing elements, not having +other interactive elements around, or reserving a fixed space for the Owl component +using CSS. + + +.. seealso:: + `Cumulative Layout Shift on web.dev `_ + + +Poorer indexing by search engines +--------------------------------- + +When search engines build their index of the content of the web, they use web crawlers +to find pages and analyze their content to show these pages in their +search results. While modern search engines are generally capable of executing JavaScript +code and should generally be able to view and index content rendered in JavaScript, +they may not index the content as fast and penalize the page in search results. + +Because most search engines do not reveal the exact way that they crawl and index +web pages, it's not always easy to know the extent of the impact that client-side rendering +can have on your search engine scores. While it's unlikely to make or break your SEO +strategy, you should still only use Owl components when they are adding real value +over server-side rendering. + +When to use Owl components on the portal and website +==================================================== + +As explained in the previous sections, using Owl component can slightly degrade user +experience if you're not careful and may also hinder your SEO. So when should you +choose to use Owl components in these places? Here are some general guidelines. + +When you don't care about SEO +----------------------------- + +If a page cannot be indexed by search engines because it's not available to the public, +e.g. anything in the user portal, SEO performance is not a concern, as web crawlers +cannot access these pages anyway. There are also some things that you do not want or +care about indexing, e.g. if you want to have a page where the user can choose a date +and time for an appointment, you probably don't want search engines to index the dates +on which an appointment is possible at a specific moment in time. + +When you need strong interactivity +---------------------------------- + +The decision to use Owl is a trade-off between the previously mentioned disadvantages +and the effort that Owl saves you by making it easy to build richly interactive user +experiences. The main reason to use Owl is when you want to build an interface that +can react in real time to user inputs without requiring the page to reload. If you +mainly want to show static content to the user, you probably shouldn't use an Owl +component.