diff --git a/content/developer/reference/frontend/hooks.rst b/content/developer/reference/frontend/hooks.rst index 05761d196..24e43245c 100644 --- a/content/developer/reference/frontend/hooks.rst +++ b/content/developer/reference/frontend/hooks.rst @@ -20,6 +20,8 @@ documents the list of hooks provided by the Odoo web framework. - Short Description * - :ref:`useBus ` - subscribe and unsubscribe to a bus + * - :ref:`usePager ` + - Display the pager of the control panel of a view. * - :ref:`usePosition ` - position an element relative to a target @@ -60,6 +62,52 @@ API :param string eventName: the name of the event that we want to listen to :param function callback: listener callback +.. _frontend/hooks/usepager: + +usePager +======== + +Location +-------- + +`@web/search/pager_hook` + +Description +----------- + +Display the :ref:`Pager ` of the control panel of a view. This hooks correctly sets `env.config` to provide the props to the pager. + +.. code-block:: javascript + + import { usePager } from "@web/search/pager_hook"; + + class CustomView { + setup() { + const state = owl.hooks.useState({ + offset: 0, + limit: 80, + total: 50, + }); + usePager(() => { + return { + offset: this.state.offset, + limit: this.state.limit, + total: this.state.total, + onUpdate: (newState) => { + Object.assign(this.state, newState); + }, + }; + }); + } + } + +API +--- + +.. js:function:: usePager(getPagerProps) + + :param function getPagerProps: function that returns the pager props. + .. _frontend/hooks/useposition: usePosition diff --git a/content/developer/reference/frontend/owl_components.rst b/content/developer/reference/frontend/owl_components.rst index b4b488706..11850f8d6 100644 --- a/content/developer/reference/frontend/owl_components.rst +++ b/content/developer/reference/frontend/owl_components.rst @@ -153,6 +153,8 @@ checkboxes or datepickers. This page explains how to use these generic component - a simple checkbox component with a label next to it * - :ref:`Dropdown ` - full-featured dropdown + * - :ref:`Pager ` + - a small component to handle pagination .. _frontend/checkbox: @@ -466,3 +468,54 @@ In this example, we recursively call a template to display a tree-like structure + +.. _frontend/pager: + +Pager +----- + +Location +~~~~~~~~ + +`@web/core/pager/pager` + +Description +~~~~~~~~~~~ + +The Pager is a small component to handle pagination. A page is defined by an `offset` and a `limit` (the size of the page). It displays the current page and the `total` number of elements, for instance, "9-12 / 20". In the previous example, `offset` is 8, `limit` is 4 and `total` is 20. It has two buttons ("Previous" and "Next") to navigate between pages. + +.. note:: + The pager can be used anywhere but its main use is in the control panel. See the :ref:`usePager ` hook in order to manipulate the pager of the control panel. + +.. code-block:: xml + + + +Props +~~~~~ + +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 + + * - Name + - Type + - Description + * - `offset` + - `number` + - Index of the first element of the page. It starts with 0 but the pager displays `offset + 1`. + * - `limit` + - `number` + - Size of the page. The sum of `offset` and `limit` corresponds to the index of the last element of the page. + * - `total` + - `number` + - Total number of elements the page can reach. + * - `onUpdate` + - `function` + - Function that is called when page is modified by the pager. This function can be async, the pager cannot be edited while this function is executing. + * - `isEditable` + - `boolean` + - Allows to click on the current page to edit it (`true` by default). + * - `withAccessKey` + - `boolean` + - Binds access key `p` on the previous page button and `n` on the next page one (`true` by default).