From 892433ac24c578305d5637f9053ca371fc6ad10b Mon Sep 17 00:00:00 2001
From: fzaninotto <fzaninotto@gmail.com>
Date: Tue, 2 Feb 2021 18:21:00 +0100
Subject: [PATCH 1/2] [Doc] Fix onSuccess callback signature for optimistic and
 undoable queries

Closes #5819
---
 docs/Actions.md    |  7 ++++---
 docs/CreateEdit.md | 37 ++++++++++++++++++++++++++++++++-----
 2 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/docs/Actions.md b/docs/Actions.md
index e6e4cc70947..fe19fd7b7fc 100644
--- a/docs/Actions.md
+++ b/docs/Actions.md
@@ -515,7 +515,8 @@ const ApproveButton = ({ record }) => {
         },
         {
 +           mutationMode: 'undoable',
-            onSuccess: ({ data }) => {
+-           onSuccess: ({ data }) => {
++           onSuccess: () => {
                 redirect('/comments');
 -               notify('Comment approved');
 +               notify('Comment approved', 'info', {}, true);
@@ -527,7 +528,7 @@ const ApproveButton = ({ record }) => {
 };
 ```
 
-As you can see in this example, you need to tweak the notification for undoable calls: passing `true` as fourth parameter of `notify` displays the 'Undo' button in the notification.
+As you can see in this example, you need to tweak the notification for undoable calls: passing `true` as fourth parameter of `notify` displays the 'Undo' button in the notification. Also, as side effects are executed immediately, they can't rely on the response beins passed to onSuccess.
 
 You can pass the `mutationMode` option parameter to specialized hooks, too. They all accept an optional last argument with side effects.
 
@@ -545,7 +546,7 @@ const ApproveButton = ({ record }) => {
         record,
         {
             mutationMode: 'undoable',
-            onSuccess: ({ data }) => {
+            onSuccess: () => {
                 redirect('/comments');
                 notify('Comment approved', 'info', {}, true);
             },
diff --git a/docs/CreateEdit.md b/docs/CreateEdit.md
index bd95b7ba3fb..bef6d04e067 100644
--- a/docs/CreateEdit.md
+++ b/docs/CreateEdit.md
@@ -396,8 +396,8 @@ const PostEdit = props => {
     const refresh = useRefresh();
     const redirect = useRedirect();
 
-    const onSuccess = ({ data }) => {
-        notify(`Changes to post "${data.title}" saved`)
+    const onSuccess = () => {
+        notify(`Changes saved`)
         redirect('/posts');
         refresh();
     };
@@ -412,19 +412,19 @@ const PostEdit = props => {
 }
 ```
 
-The `onSuccess` function receives the response from the dataProvider call (`dataProvider.create()` or `dataProvider.update()`), which is the created/edited record (see [the dataProvider documentation for details](./DataProviders.md#response-format))
+By default, the `<Edit>` view runs updates in `mutationMode="undoable"`, which means that it calls the `onSuccess` side effects immediately, even before the `dataProvider` is called.
 
 The default `onSuccess` function is:
 
 ```jsx
 // for the <Create> component:
-({ data }) => {
+() => {
     notify('ra.notification.created', 'info', { smart_count: 1 });
     redirect('edit', basePath, data.id, data);
 }
 
 // for the <Edit> component: 
-({ data }) => {
+() => {
     notify('ra.notification.updated', 'info', { smart_count: 1 }, mutationMode === 'undoable');
     redirect('list', basePath, data.id, data);
 }
@@ -432,6 +432,33 @@ The default `onSuccess` function is:
 
 To learn more about built-in side effect hooks like `useNotify`, `useRedirect` and `useRefresh`, check the [Querying the API documentation](./Actions.md#handling-side-effects-in-usedataprovider).
 
+**Tip**: When you use `mutationMode="pessimistic"`, the `onSuccess` function receives the response from the dataProvider call (`dataProvider.create()` or `dataProvider.update()`), which is the created/edited record (see [the dataProvider documentation for details](./DataProviders.md#response-format)). You can use that response in the success side effects: 
+
+```jsx
+import * as React from 'react';
+import { useNotify, useRefresh, useRedirect, Edit, SimpleForm } from 'react-admin';
+
+const PostEdit = props => {
+    const notify = useNotify();
+    const refresh = useRefresh();
+    const redirect = useRedirect();
+
+  const onSuccess = ({ data }) => {
+        notify(`Changes to post "${data.title}" saved`)
+        redirect('/posts');
+        refresh();
+    };
+
+    return (
+        <Edit onSuccess={onSuccess} mutationMode="pessimistic" {...props}>
+            <SimpleForm>
+                ...
+            </SimpleForm>
+        </Edit>
+    );
+}
+```
+
 **Tip**: When you set the `onSuccess` prop, the `successMessage` prop is ignored.
 
 **Tip**: If you want to have different success side effects based on the button clicked by the user (e.g. if the creation form displays two submit buttons, one to "save and redirect to the list", and another to "save and display an empty form"), you can set the `onSuccess` prop on the `<SaveButton>` component, too.

From 1af20ab7a6c1532e7b92cc7654cd0efed397be7d Mon Sep 17 00:00:00 2001
From: fzaninotto <fzaninotto@gmail.com>
Date: Tue, 2 Feb 2021 18:41:44 +0100
Subject: [PATCH 2/2] Fix typo

---
 docs/Actions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/Actions.md b/docs/Actions.md
index fe19fd7b7fc..28845b4aff3 100644
--- a/docs/Actions.md
+++ b/docs/Actions.md
@@ -528,7 +528,7 @@ const ApproveButton = ({ record }) => {
 };
 ```
 
-As you can see in this example, you need to tweak the notification for undoable calls: passing `true` as fourth parameter of `notify` displays the 'Undo' button in the notification. Also, as side effects are executed immediately, they can't rely on the response beins passed to onSuccess.
+As you can see in this example, you need to tweak the notification for undoable calls: passing `true` as fourth parameter of `notify` displays the 'Undo' button in the notification. Also, as side effects are executed immediately, they can't rely on the response being passed to onSuccess.
 
 You can pass the `mutationMode` option parameter to specialized hooks, too. They all accept an optional last argument with side effects.