Added documentation and updated related examples with the new signatu…

…re usage

UPGRADE.md

@@ -118,12 +118,11 @@ Here's how to migrate the *Altering the Form Values before Submitting* example f
 import * as React from 'react';
 import { useCallback } from 'react';
 import { useForm } from 'react-final-form';
-import { SaveButton, Toolbar, useCreate, useRedirect, useNotify } from 'react-admin';
+import { SaveButton, Toolbar, useCreate, useRedirect } from 'react-admin';
 
 const SaveWithNoteButton = ({ handleSubmit, handleSubmitWithRedirect, ...props }) => {
     const [create] = useCreate('posts');
     const redirectTo = useRedirect();
-    const notify = useNotify();
     const { basePath, redirect } = props;
 
     const form = useForm();
@@ -171,9 +170,7 @@ const SaveWithNoteButton = props => {
                 },
                 {
                     onSuccess: ({ data: newRecord }) => {
-                        notify('ra.notification.created', 'info', {
-                            smart_count: 1,
-                        });
+                        notify('ra.notification.created', { messageArgs: { smart_count: 1 } });
                         redirectTo(redirect, basePath, newRecord.id, newRecord);
                     },
                 }

docs/Actions.md

@@ -641,16 +641,17 @@ const NotifyButton = () => {
 };
 ```
 
-The callback takes 5 arguments:
- - the message to display
- - the level of the notification (`info`, `success` or `warning` - the default is `info`)
- - an `options` object to pass to the `translate` function (because notification messages are translated if your admin has an `i18nProvider`). It is useful for inserting variables into the translation.
- - an `undoable` boolean. Set it to `true` if the notification should contain an "undo" button
- - a `duration` number. Set it to `0` if the notification should not be dismissible.
+The callback takes 6 arguments:
+- The message to display
+- The level of the notification (`info`, `success` or `warning` - the default is `info`)
+- An `options` object to pass to the `translate` function (because notification messages are translated if your admin has an `i18nProvider`). It is useful for inserting variables into the translation.
+- An `undoable` boolean. Set it to `true` if the notification should contain an "undo" button
+- A `duration` number. Set it to `0` if the notification should not be dismissible.
+- A `multiLine` boolean. Set it to `true` if the notification message should be shown in more than one line.
 
 Here are more examples of `useNotify` calls: 
 
-```jsx
+```js
 // notify a warning
 notify(`This is a warning`, 'warning');
 // pass translation arguments
@@ -659,6 +660,17 @@ notify('item.created', 'info', { resource: 'post' });
 notify('Element updated', 'info', undefined, true);
 ```
 
+**Tip**: The callback also allows a signature with only 2 arguments, the message to display and an object with the rest of the arguments
+
+```js
+// notify an undoable success message, with translation arguments
+notify('Element deleted', {
+    type: 'success',
+    undoable: true,
+    messageArgs: { resource: 'post' }
+});
+```
+
 **Tip**: When using `useNotify` as a side effect for an `undoable` Edit form, you MUST set the fourth argument to `true`, otherwise the "undo" button will not appear, and the actual update will never occur.
 
 ```jsx
@@ -669,7 +681,7 @@ const PostEdit = props => {
     const notify = useNotify();
 
     const onSuccess = () => {
-        notify(`Changes saved`, undefined, undefined, true);
+        notify('Changes saved`', { undoable: true });
     };
 
     return (
@@ -841,7 +853,7 @@ const ApproveButton = ({ record }) => {
 +           onSuccess: () => {
                 redirect('/comments');
 -               notify('Comment approved');
-+               notify('Comment approved', 'info', {}, true);
++               notify('Comment approved', { undoable: true });
             },
             onFailure: (error) => notify(`Error: ${error.message}`, 'warning'),
         }
@@ -870,7 +882,7 @@ const ApproveButton = ({ record }) => {
             mutationMode: 'undoable',
             onSuccess: () => {
                 redirect('/comments');
-                notify('Comment approved', 'info', {}, true);
+                notify('Comment approved', { undoable: true });
             },
             onFailure: (error) => notify(`Error: ${error.message}`, 'warning'),
         }
@@ -905,7 +917,7 @@ const ApproveButton = ({ record }) => {
             mutationMode: 'undoable',
             onSuccess: ({ data }) => {
                 redirect('/comments');
-                notify('Comment approved', 'info', {}, true);
+                notify('Comment approved', { undoable: true });
             },
             onFailure: (error) => notify(`Error: ${error.message}`, 'warning'),
         }
@@ -987,7 +999,7 @@ const ApproveButton = ({ record }) => {
     const options = {
         mutationMode: 'undoable',
         onSuccess: ({ data }) => {
-            notify('Comment approved', 'info', {}, true);
+            notify('Comment approved', { undoable: true });
             redirect('/comments');
         },
         onFailure: (error) => notify(`Error: ${error.message}`, 'warning'),

docs/CreateEdit.md

@@ -401,7 +401,7 @@ const PostEdit = props => {
     const redirect = useRedirect();
 
     const onSuccess = () => {
-        notify(`Changes saved`)
+        notify(`Changes saved`);
         redirect('/posts');
         refresh();
     };
@@ -423,13 +423,16 @@ The default `onSuccess` function is:
 ```jsx
 // for the <Create> component:
 () => {
-    notify('ra.notification.created', 'info', { smart_count: 1 });
+    notify('ra.notification.created', { messageArgs: { smart_count: 1 } });
     redirect('edit', basePath, data.id, data);
 }
 
 // for the <Edit> component: 
 () => {
-    notify('ra.notification.updated', 'info', { smart_count: 1 }, mutationMode === 'undoable');
+    notify('ra.notification.created', {
+        messageArgs: { smart_count: 1 },
+        undoable: mutationMode === 'undoable'
+    });
     redirect('list', basePath, data.id, data);
 }
 ```
@@ -448,7 +451,7 @@ const PostEdit = props => {
     const redirect = useRedirect();
 
   const onSuccess = ({ data }) => {
-        notify(`Changes to post "${data.title}" saved`)
+        notify(`Changes to post "${data.title}" saved`);
         redirect('/posts');
         refresh();
     };
@@ -483,7 +486,7 @@ const PostEdit = props => {
     const redirect = useRedirect();
 
     const onFailure = (error) => {
-        notify(`Could not edit post: ${error.message}`)
+        notify(`Could not edit post: ${error.message}`);
         redirect('/posts');
         refresh();
     };
@@ -2203,7 +2206,7 @@ const PostEdit = props => {
         if (error.code == 123) {
             notify('Could not save changes: concurrent edition in progress', 'warning');
         } else {
-            notify('ra.notification.http_error', 'warning')
+            notify('ra.notification.http_error', 'warning');
         }
         redirect('list', props.basePath);
     }

docs/List.md

@@ -489,7 +489,7 @@ const CustomResetViewsButton = ({ selectedIds }) => {
             onSuccess: () => {
                 refresh();
 -               notify('Posts updated');
-+               notify('Posts updated', 'info', '{}, true); // the last argument forces the display of 'undo' in the notification
++               notify('Posts updated', { undoable: true }); // the last argument forces the display of 'undo' in the notification
                 unselectAll('posts');
             },
             onFailure: error => notify('Error: posts not updated', 'warning'),