From 91f97aff546c76f6314efaebde5505d672bdb0ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= Date: Sun, 31 Oct 2021 06:45:38 +0000 Subject: [PATCH] [IMP] developer: add Dropdown documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit joint work with Bruno (boi) closes odoo/documentation#1247 Signed-off-by: Géry Debongnie (ged) --- content/developer/reference/frontend.rst | 3 +- .../reference/frontend/generic_components.rst | 47 -- .../developer/reference/frontend/hooks.rst | 79 ++++ .../frontend/owl_component_system.rst | 106 ----- .../reference/frontend/owl_components.rst | 438 ++++++++++++++++++ redirects.txt | 5 +- 6 files changed, 522 insertions(+), 156 deletions(-) delete mode 100644 content/developer/reference/frontend/generic_components.rst delete mode 100644 content/developer/reference/frontend/owl_component_system.rst create mode 100644 content/developer/reference/frontend/owl_components.rst diff --git a/content/developer/reference/frontend.rst b/content/developer/reference/frontend.rst index 23ce1806b..1a707e59d 100644 --- a/content/developer/reference/frontend.rst +++ b/content/developer/reference/frontend.rst @@ -10,10 +10,9 @@ Frontend frontend/framework_overview frontend/assets frontend/javascript_modules - frontend/owl_component_system + frontend/owl_components frontend/registries frontend/services - frontend/generic_components frontend/hooks frontend/javascript_cheatsheet frontend/javascript_reference diff --git a/content/developer/reference/frontend/generic_components.rst b/content/developer/reference/frontend/generic_components.rst deleted file mode 100644 index 9d08a8cc8..000000000 --- a/content/developer/reference/frontend/generic_components.rst +++ /dev/null @@ -1,47 +0,0 @@ -================== -Generic Components -================== - -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. - -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 - - diff --git a/content/developer/reference/frontend/hooks.rst b/content/developer/reference/frontend/hooks.rst index c43235a09..05761d196 100644 --- a/content/developer/reference/frontend/hooks.rst +++ b/content/developer/reference/frontend/hooks.rst @@ -12,6 +12,19 @@ Using these hooks, it is possible to build many customized hooks that help solve a specific problem, or make some common tasks easier. The rest of this page documents the list of hooks provided by the Odoo web framework. +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Name + - Short Description + * - :ref:`useBus ` + - subscribe and unsubscribe to a bus + * - :ref:`usePosition ` + - position an element relative to a target + +.. _frontend/hooks/usebus: + useBus ====== @@ -47,3 +60,69 @@ API :param string eventName: the name of the event that we want to listen to :param function callback: listener callback +.. _frontend/hooks/useposition: + +usePosition +=========== + +Location +-------- + +`@web/core/position/position_hook` + +Description +----------- + +Helps positioning a component (or a specific HTMLElement) relatively to a target +HTMLElement. This hook ensures the positioning is updated when the window is +resized/scrolled. + +.. code-block:: javascript + + import { usePosition } from "@web/core/position/position_hook"; + + class MyPopover { + setup() { + // Here, the target is an HTMLElement + usePosition(this.props.target); + } + } + MyPopover.template = owl.tags.xml`
I am positioned through a wonderful hook!
` + +API +--- + +.. js:function:: usePosition(reference[, options]) + + :param reference: the target HTMLElement to be positioned from + :type reference: HTMLElement or ()=>HTMLElement + :param Options options: the positioning options (see table below) + +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 + + * - Option + - Type + - Description + * - `popper` + - string | undefined + - this is the element that will get positioned. You can provide here a + `useRef reference `_. + If not provided, `this.el` is used (default: `undefined`). + * - `container` + - HTMLElement + - the container from which the popper is expected not to overflow. If + overflowing occurs, other popper positions are tried until a not + overflowing one is found. (default: the `` node) + * - `margin` + - number + - added margin between popper and reference elements (default: `0`) + * - `position` + - string + - the desired position. It is a string composed of one direction and one + variant separated by a dash character. Valid directions are: `top`, + `bottom`, `right`, `left`. Valid variants are: `start`, + `middle`, `end`. The variant can be omitted (default variant is + `middle`). Examples of valid positions: `right-end`, `top-start`, + `left-middle`, `left`. (default position: `bottom`) diff --git a/content/developer/reference/frontend/owl_component_system.rst b/content/developer/reference/frontend/owl_component_system.rst deleted file mode 100644 index 7cee853b7..000000000 --- a/content/developer/reference/frontend/owl_component_system.rst +++ /dev/null @@ -1,106 +0,0 @@ - -==================== -Owl Component System -==================== - -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 in Odoo -============================ - -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 `_ diff --git a/content/developer/reference/frontend/owl_components.rst b/content/developer/reference/frontend/owl_components.rst new file mode 100644 index 000000000..deb6d5ab8 --- /dev/null +++ b/content/developer/reference/frontend/owl_components.rst @@ -0,0 +1,438 @@ + +============== +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 `_ + +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/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/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 `
` having a +` + +
+ Menu Item 1 + Menu Item 2 +
+
+ +To properly use a `` component, you need to populate two +`OWL slots `_ : + + +- `toggler` slot: it contains the *toggler* elements of your dropdown and is + rendered inside the dropdown `button` (unless the `toggler` prop is set to `parent`), +- `default` slot: it contains the *elements* of the dropdown menu itself and is + rendered inside the ``
``. Although it is not mandatory, there is usually at least one + `DropdownItem` inside the `menu` slot. + + +When several dropdowns share the same parent element in the DOM, then they are +considered part of a group, and will notify each other about their state changes. +This means that when one of these dropdowns is open, the others will automatically +open themselves on mouse hover, without the need for a click. + + +Example: Direct Siblings Dropdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When one dropdown toggler is clicked (**File** , **Edit** or **About**), the +others will open themselves on hover. + +.. code-block:: xml + +
+ + File + Open + New Document + New Spreadsheet + + + Edit + Undo + Redo + Search + + + About + Help + Check update + +
+ +Example: Multi-level Dropdown (with `t-call`) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example shows how one could make a `File` dropdown menu, with submenus for +the `New` and `Save as...` sub elements. + +.. code-block:: xml + + + + File + Open + + Save + + + + + + + New + Document + Spreadsheet + + + + + + Save as... + CSV + PDF + + + +Example: Multi-level Dropdown (nested) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: xml + + + File + Open + + New + Document + Spreadsheet + + Save + + Save as... + CSV + PDF + + + +Example: Recursive Multi-level Dropdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this example, we recursively call a template to display a tree-like structure. + +.. code-block:: xml + + +
+ + + + +
+ + + + + + + + + + + + + + + + + + + + + diff --git a/redirects.txt b/redirects.txt index d0851d69f..0eac6d023 100644 --- a/redirects.txt +++ b/redirects.txt @@ -312,4 +312,7 @@ developer/reference/javascript/javascript_reference.rst developer/refer developer/reference/javascript/mobile.rst developer/reference/frontend/mobile.rst developer/reference/javascript/qweb.rst developer/reference/frontend/qweb.rst -developer/reference/backend/assets.rst developer/reference/frontend/assets.rst \ No newline at end of file +developer/reference/backend/assets.rst developer/reference/frontend/assets.rst + +developer/reference/frontend/owl_component_system.rst developer/reference/frontend/owl_components.rst +developer/reference/frontend/generic_components.rst developer/reference/frontend/owl_components.rst \ No newline at end of file