[IMP] developer: add doc for pager and usePager

closes odoo/documentation#1238

Signed-off-by: Michaël Mattiello <mcm@odoo.com>

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 <frontend/hooks/usebus>`
      - subscribe and unsubscribe to a bus
+   * - :ref:`usePager <frontend/hooks/usepager>`
+     - Display the pager of the control panel of a view.
    * - :ref:`usePosition <frontend/hooks/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 <frontend/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

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 <frontend/dropdown>`
      - full-featured dropdown
+   * - :ref:`Pager <frontend/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
       </t>
     </Dropdown>
   </t>
+
+.. _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 <frontend/hooks/usepager>` hook in order to manipulate the pager of the control panel.
+
+.. code-block:: xml
+
+  <Pager offset="0" limit="80" total="50" onUpdate="doSomething" />
+
+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).