From 4082906776ce58b9ac69f8254842865b903cb89d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= Date: Tue, 2 Nov 2021 20:07:34 +0000 Subject: [PATCH] [IMP] developer: reorder and improve notification service closes odoo/documentation#1265 Signed-off-by: Victor Feyens (vfe) --- .../developer/reference/frontend/services.rst | 214 ++++++++++-------- 1 file changed, 119 insertions(+), 95 deletions(-) diff --git a/content/developer/reference/frontend/services.rst b/content/developer/reference/frontend/services.rst index 7686d6906..de49788b0 100644 --- a/content/developer/reference/frontend/services.rst +++ b/content/developer/reference/frontend/services.rst @@ -118,6 +118,8 @@ Reference List - Short Description * - :ref:`cookie ` - read or modify cookies + * - :ref:`notification ` + - display notifications * - :ref:`rpc ` - send requests to the server * - :ref:`title ` @@ -163,6 +165,120 @@ API Deletes the cookie `name`. +.. _services/notification: + +Notification service +-------------------- + +Overview +~~~~~~~~ + +* Technical name: `notification` +* Dependencies: None + +The `notification` service allows to display notifications on the screen. + +.. code-block:: javascript + + const notificationService = useService("notification"); + notificationService.add("I'm a very simple notification"); + +API +~~~ + +.. js:function:: add(message[, options]) + + :param string message: the notification message to display + :param object options: the options of the notification + :returns: a function to close the notification + + Shows a notification. + + The options are defined by: + + .. list-table:: + :widths: 15 30 55 + :header-rows: 1 + + * - Name + - Type + - Description + * - `title` + - string + - Add a title to the notification + * - `type` + - `warning` | `danger` | `success` | `info` + - Changes the background color according to the type + * - `sticky` + - boolean + - Whether or not the notification should stay until dismissed + * - `className` + - string + - additional css class that will be added to the notification + * - `onClose` + - function + - callback to be executed when the notification closes + * - `buttons` + - button[] (see below) + - list of button to display in the notification + + The buttons are defined by: + + .. list-table:: + :widths: 15 30 55 + :header-rows: 1 + + * - Name + - Type + - Description + * - `name` + - string + - The button text + * - `onClick` + - function + - callback to execute when the button is clicked + * - `primary` + - boolean + - whether the button should be styled as a primary button + +Examples +~~~~~~~~ + +A notification for when a sale deal is made with a button to go some kind of commission page. + +.. code-block:: javascript + + // in setup + this.notificationService = useService("notification"); + this.actionService = useService("actionService"); + + // later + this.notificationService.add("You closed a deal!", { + title: "Congrats", + type: "success", + buttons: [ + { + name: "See your Commission", + onClick: () => { + this.actionService.doAction("commission_action"); + }, + }, + ], + }); + +.. image:: images/notification_service.png + :width: 600 px + :alt: Example of notification + :align: center + +A notification that closes after a second: + +.. code-block:: javascript + + const notificationService = useService("notification"); + const close = notificationService.add("I will be quickly closed"); + setTimeout(close, 1000); + .. _services/rpc: RPC service @@ -256,8 +372,9 @@ When a rpc fails, then: If it is a network error, then the error description is simply an object ``{type: 'network'}``. - When a network error occurs, a notification is displayed and the server is regularly - contacted until it responds. The notification is closed as soon as the server responds. + When a network error occurs, a :ref:`notification ` is + displayed and the server is regularly contacted until it responds. The + notification is closed as soon as the server responds. .. _services/title: @@ -425,96 +542,3 @@ API .. code-block:: js const isInSalesGroup = await userService.hasGroup("sale.group_sales") - -Notification service --------------------- - -Overview -~~~~~~~~ - -* Technical name: `notification` -* Dependencies: None - -The `notification` service allows to display notifications on the screen. - -.. code-block:: javascript - - const notificationService = useService("notification"); - notificationService.add("I'm a very simple notification"); - -API -~~~ - -.. js:function:: add(message[, options]) - - :param string message: the notification message to display - :param object options: the options of the notification - :returns: a function to close the notification - - Shows a notification. - -The options are defined by: - -.. code-block:: ts - - @typedef {Object} NotificationOptions - @property {string} [title] - // Add a title to the notification - @property {"warning" | "danger" | "success" | "info"} [type] - // Change the background color - @property {boolean} [sticky=false] - // Whether or not the notification shouldn't be dismissed - @property {string} [className] - // Add a class name of the notification for css targetting - @property {function(): void} [onClose] - // Provide a callback to be executed when the notification closes - @property {NotificationButton[]} [buttons] - // Add buttons to the notifications. - - @typedef {Object} NotificationButton - @property {string} name - // The button text - @property {function(): void} onClick - // The callback to execute when the button is clicked - @property {string} [icon] - // A font-awesome string to add an icon - @property {boolean} [primary=false] - // Wheter the button has the primary button style - -Examples -~~~~~~~~ - -A notification for when a sale deal is made with a button to go some kind of commission page. - -.. code-block:: javascript - - // in setup - this.notificationService = useService("notification"); - this.actionService = useService("actionService"); - - // later - this.notificationService.add("You closed a deal!", { - title: "Congrats", - type: "success", - buttons: [ - { - name: "See your Commission", - onClick: () => { - this.actionService.doAction("commission_action"); - }, - }, - ], - }); - -.. image:: images/notification_service.png - :width: 600 px - :alt: Example of notification - :align: center - -A notification that closes after a second: - -.. code-block:: javascript - - const notificationService = useService("notification"); - const close = notificationService.add("I will be quickly closed"); - setTimeout(close, 1000);