diff --git a/content/developer/reference/frontend/owl_components.rst b/content/developer/reference/frontend/owl_components.rst index 865215cf6..47c78fc76 100644 --- a/content/developer/reference/frontend/owl_components.rst +++ b/content/developer/reference/frontend/owl_components.rst @@ -420,271 +420,277 @@ Location Description ~~~~~~~~~~~ -Dropdowns are surprisingly complicated components. They need to provide many -features such as: +The Dropdown lets you show a menu with a list of items when a toggle is +clicked on. They can be combined with DropdownItems to invoke callbacks +and close the menu when items are selected. + +Dropdowns are surprisingly complicated components, the list of features they +provide is as follow: - Toggle the item list on click -- Direct siblings dropdowns: when one is open, toggle others on hover - Close on outside click +- Call a function when items are selected - Optionally close the item list when an item is selected -- Call a function when the item is selected -- Support sub dropdowns, up to any level - SIY: style it yourself +- Support sub dropdowns, up to any level - 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 -
-
+- Direct siblings dropdowns: when one is open, toggle others on hover 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) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- `default` slot: it contains the *toggle* elements of your dropdown. By default, click events will + be attached to this element to open and close the dropdown. +- `content` slot: it contains the *elements* of the dropdown menu itself and is rendered inside a popover. + Although it is not mandatory, you can put some `DropdownItem` inside this slot, the dropdown will + automatically close when these items are selected. .. code-block:: xml - File - Open - - New - Document - Spreadsheet - - Save - - Save as... - CSV - PDF - + + + + + + Menu Item 1 + Menu Item 2 + -Example: Recursive Multi-level Dropdown -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Dropdown Props +~~~~~~~~~~~~~~ -In this example, we recursively call a template to display a tree-like structure. +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 -.. code-block:: xml + * - Name + - Type + - Description + * - `menuClass` + - `String` + - Optional classname added to the dropdown's menu + * - `disabled` + - `Boolean` + - Optional, if true, disables the dropdown so the user is not able to open it anymore. (default: `false`) + * - `items` + - `Array` + - Optional list of items to be displayed as DropdownItems inside the dropdown's menu + * - `position` + - `String` + - Optionally defines the desired menu opening position. RTL direction is automatically applied. Should be a valid :ref:`usePosition ` hook position. (default: `bottom-start`) + * - `beforeOpen` + - `Function` + - Optional function called just before opening. May be asynchronous. + * - `onOpened` + - `Function` + - Optional function called just after opening. + * - `onStateChanged` + - `Function` + - Optional function called after opening or closing (gives a boolean as single argument that represents whether the dropdown is open or not). + * - `state` + - `Object` + - Optional object with `open()`, `close()` and `isOpen` properties to manually control when the dropdown opens and closes. + * - `manual` + - `Boolean` + - Optional, when true, the Dropdown component will not add click event listeners to the toggler. This allows for more control as when to open the dropdown. (This should be used in tandem with the `state` prop) + * - `navigationOptions` + - `Boolean` + - Optionally overrides the navigation options of the dropdown, (see `web/core/navigation/navigation`). + * - `holdOnHover` + - `Boolean` + - Optional, if true, keeps the Dropdown's menu at the same position while the mouse is hovering it, creating a better UX when the menu's content changes. + * - `menuRef` + - `Function` + - Optional, allows to get a ref of the dropdown's menu, (expects a function returned from `useChildRef`) - -
- - - - -
- +DropdownItem Props +~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 + + * - Name + - Type + - Description + * - `class` + - `String` or `Object` + - Optional value added to the root span classname (supports both strings and `OWL classname object notation `_). + * - `onSelected` + - `Function` + - Optional function called when the dropdown item is selected. + * - `closingMode` + - `"none"` | `"closest"` | `"all"` + - Optional, controls which parent dropdown should close when the item is selected: + `none`: the dropdown will not close, `closest`: the direct parent will close, `all`: every nested parent dropdown will close (default: `all`) + * - `attrs` + - `Object` + - Optional object representing attributes that are added to the root element. ``. (If `href` is set, the element will automatically become an `a` element). + +.. important:: + When writing custom css for you components, do not forget that the menu elements are not next to the toggle + but inside the overlay container, at the bottom of the document. Thus, use the `menuClass` and `class` props to more + easily write your selectors. (This DOM magic let us avoid lots of z-index issues.) + + +Nested Dropdown +~~~~~~~~~~~~~~~ + +Dropdown can be nested, to do this simply put new Dropdown components inside other dropdown's content slot. When the parent +dropdown is open, child dropdowns will open automatically on hover. + +By default, selecting a DropdownItem will close the whole Dropdown tree. + +.. example:: + + This example shows how one could make a nested File dropdown menu, with submenus for the New sub elements. + + .. code-block:: xml - - - + + + Save + Open - - - + + + + Document + Spreadsheet - - - - - - - + - + + In the example bellow, we recursively call a template to display a tree-like structure. + + .. code-block:: xml + + +
+ + + + +
+ + + + + + + + + + + + + + + + + + + + + +Controlled Dropdown +~~~~~~~~~~~~~~~~~~~ + +If needed, you can also open or close the dropdown using code. To do this you must use the `useDropdownState` hook along +with the `state` prop. `useDropdownState` returns an object that has an `open` and a `close` method (as well as an `isOpen` getter). +Give the object to the `state` prop of the dropdown you want to control and calling the respective functions should now open and +close your dropdown. + +You can also set `manual` to `true` if you don't want the default click handlers to be added on the toggle. + +.. example:: + + The following example shows a dropdown that opens automatically when mounted and only has a 50% chance + of closing when clicking on the button inside. + + .. code-block:: javascript + + import { Component, onMounted } from "@odoo/owl"; + import { Dropdown } from "@web/core/dropdown/dropdown"; + import { DropdownItem } from "@web/core/dropdown/dropdown_item"; + import { useDropdownState } from "@web/core/dropdown/dropdown_hooks"; + + class MyComponent extends Component { + + static components = { Dropdown, DropdownItem }; + static template = xml` + +
My Dropdown
+ + +