.. _frontend/components: ============== Owl Components ============== The Odoo Javascript framework uses a custom component framework called Owl. It is a declarative component system, loosely inspired by Vue and React. Components are defined using :doc:`QWeb templates `, enriched with some Owl specific directives. The official `Owl documentation `_ contains a complete reference and a tutorial. .. important:: Although the code can be found in the `web` module, it is maintained from a separate GitHub repository. Any modification to Owl should therefore be made through a pull request on https://github.com/odoo/owl. .. note:: Currently, all Odoo versions (starting in version 14) share the same Owl version. Using Owl components ==================== The `Owl documentation`_ already documents in detail the Owl framework, so this page will only provide Odoo specific information. But first, let us see how we can make a simple component in Odoo. .. code-block:: javascript const { useState } = owl.hooks; const { xml } = owl.tags; class MyComponent extends Component { setup() { this.state = useState({ value: 1 }); } increment() { this.state.value++; } } MyComponent.template = xml `

`; This example shows that Owl is available as a library in the global namespace as ``owl``: it can simply be used like most libraries in Odoo. Note that we defined here the template as a static property, but without using the `static` keyword, which is not available in some browsers (Odoo javascript code should be Ecmascript 2019 compliant). We define here the template in the javascript code, with the help of the ``xml`` helper. However, it is only useful to get started. In practice, templates in Odoo should be defined in an xml file, so they can be translated. In that case, the component should only define the template name. In practice, most components should define 2 or 3 files, located at the same place: a javascript file (``my_component.js``), a template file (``my_component.xml``) and optionally a scss (or css) file (``my_component.scss``). These files should then be added to some assets bundle. The web framework will take care of loading the javascript/css files, and loading the templates into Owl. Here is how the component above should be defined: .. code-block:: javascript const { useState } = owl.hooks; class MyComponent extends Component { ... } MyComponent.template = 'myaddon.MyComponent'; And the template is now located in the corresponding xml file: .. code-block:: xml

Odoo code is not yet completely made in Owl, so it needs a way to tell the difference between Owl templates (new code) and old templates (for components). To do that in a backward-compatible way, all new templates should be defined with the ``owl`` attribute set to 1. .. note:: Do not forget to set ``owl="1"`` in your Owl templates! .. note:: Template names should follow the convention `addon_name.ComponentName`. .. seealso:: - `Owl Repository `_ .. _frontend/owl/best_practices: Best practices ============== First of all, components are classes, so they have a constructor. But constructors are special methods in javascript that are not overridable in any way. Since this is an occasionally useful pattern in Odoo, we need to make sure that no component in Odoo directly uses the constructor method. Instead, components should use the `setup` method: .. code-block:: javascript // correct: class MyComponent extends Component { setup() { // initialize component here } } // incorrect. Do not do that! class IncorrectComponent extends Component { constructor(parent, props) { // initialize component here } } Another good practice is to use a consistent convention for template names: `addon_name.ComponentName`. This prevents name collision between odoo addons. Reference List ============== The Odoo web client is built with `Owl `_ components. To make it easier, the Odoo javascript framework provides a suite of generic components that can be reused in some common situations, such as dropdowns, checkboxes or datepickers. This page explains how to use these generic components. .. list-table:: :widths: 30 70 :header-rows: 1 * - Technical Name - Short Description * - :ref:`CheckBox ` - a simple checkbox component with a label next to it * - :ref:`Dropdown ` - full-featured dropdown .. _frontend/owl/checkbox: CheckBox -------- Location ~~~~~~~~ `@web/core/checkbox/checkbox` Description ~~~~~~~~~~~ This is a simple checkbox component with a label next to it. The checkbox is linked to the label: the checkbox is toggled whenever the label is clicked. .. code-block:: xml Some Text Props ~~~~~ .. list-table:: :widths: 20 20 60 :header-rows: 1 * - Name - Type - Description * - `value` - `boolean` - if true, the checkbox is checked, otherwise it is unchecked * - `disabled` - `boolean` - if true, the checkbox is disabled, otherwise it is enabled .. _frontend/owl/dropdown: Dropdown -------- Location ~~~~~~~~ `@web/core/dropdown/dropdown` and `@web/core/dropdown/dropdown_item` Description ~~~~~~~~~~~ Dropdowns are surprisingly complicated components. They need to provide many features such as: - Toggle the item list on click - Direct siblings dropdowns: when one is open, toggle others on hover - Close on outside click - Optionally close the item list when an item is selected - Emit an event to inform which list item is clicked - Support sub dropdowns, up to any level - SIY: style it yourself - Configurable hotkey to open/close a dropdown or select a dropdown item - Keyboard navigation (arrows, tab, shift+tab, home, end, enter and escape) - Reposition itself whenever the page scrolls or is resized - Smartly chose the direction it should open (right-to-left direction is automatically handled). To solve these issues once and for all, the Odoo framework provides a set of two components: a `Dropdown` component (the actual dropdown), and `DropdownItem`, for each element in the item list. .. code-block:: xml Click me to toggle the dropdown menu ! Menu Item 1 Menu Item 2 Props ~~~~~ A `` component is simply a `