[RFR] Convert DataProvider to Object

docs/Admin.md

@@ -49,22 +49,20 @@ Here are all the props accepted by the component:
 
 ## `dataProvider`
 
-The only required prop, it must be a function returning a promise, with the following signature:
+The only required prop, it must be an object with the following methods returning a promise:
 
 ```jsx
-/**
- * Query a data provider and return a promise for a response
- *
- * @example
- * dataProvider(GET_ONE, 'posts', { id: 123 })
- *  => new Promise(resolve => resolve({ id: 123, title: "hello, world" }))
- *
- * @param {string} type Request type, e.g GET_LIST
- * @param {string} resource Resource name, e.g. "posts"
- * @param {Object} payload Request parameters. Depends on the action type
- * @returns {Promise} the Promise for a response
- */
-const dataProvider = (type, resource, params) => new Promise();
+const dataProvider = {
+    getList:    (resource, params) => Promise,
+    getOne:     (resource, params) => Promise,
+    getMany:    (resource, params) => Promise,
+    getManyReference: (resource, params) => Promise,
+    create:     (resource, params) => Promise,
+    update:     (resource, params) => Promise,
+    updateMany: (resource, params) => Promise,
+    delete:     (resource, params) => Promise,
+    deleteMany: (resource, params) => Promise,
+}
 ```
 
 The `dataProvider` is also the ideal place to add custom HTTP headers, authentication, etc. The [Data Providers Chapter](./DataProviders.md) of the documentation lists available data providers, and explains how to build your own.

docs/CreateEdit.md

@@ -945,3 +945,108 @@ export const UserEdit = ({ permissions, ...props }) =>
     </Edit>;
 ```
 {% endraw %}
+
+## Altering the Form Values before Submitting
+
+Sometimes, you may want your custom action to alter the form values before actually sending them to the `dataProvider`.
+For those cases, you should know that every buttons inside a form [Toolbar](/CreateEdit.md#toolbar) receive two props:
+
+- `handleSubmit` which calls the default form save method
+- `handleSubmitWithRedirect` which calls the default form save method but allows to specify a custom redirection
+
+Knowing this, there are two ways to alter the form values before submit:
+
+1. Using react-final-form API to send change events
+
+```jsx
+import React, { useCallback } from 'react';
+import { useForm } from 'react-final-form';
+import { SaveButton, Toolbar, useCreate, useRedirect, useNotify } from 'react-admin';
+
+const SaveWithNoteButton = ({ handleSubmitWithRedirect, ...props }) => {
+    const [create] = useCreate('posts');
+    const redirectTo = useRedirect();
+    const notify = useNotify();
+    const { basePath, redirect } = props;
+
+    const form = useForm();
+
+    const handleClick = useCallback(() => {
+        form.change('average_note', 10);
+
+        handleSubmitWithRedirect('edit');
+    }, [form]);
+
+    return <SaveButton {...props} handleSubmitWithRedirect={handleClick} />;
+};
+```
+
+2. Using react-admin hooks to run custom mutations
+
+For instance, in the `simple` example:
+
+```jsx
+import React, { useCallback } from 'react';
+import { useFormState } from 'react-final-form';
+import { SaveButton, Toolbar, useCreate, useRedirect, useNotify } from 'react-admin';
+
+const SaveWithNoteButton = props => {
+    const [create] = useCreate('posts');
+    const redirectTo = useRedirect();
+    const notify = useNotify();
+    const { basePath, redirect } = props;
+
+    const formState = useFormState();
+    const handleClick = useCallback(() => {
+        if (!formState.valid) {
+            return;
+        }
+
+        create(
+            {
+                data: { ...formState.values, average_note: 10 },
+            },
+            {
+                onSuccess: ({ data: newRecord }) => {
+                    notify('ra.notification.created', 'info', {
+                        smart_count: 1,
+                    });
+                    redirectTo(redirect, basePath, newRecord.id, newRecord);
+                },
+            }
+        );
+    }, [
+        formState.valid,
+        formState.values,
+        create,
+        notify,
+        redirectTo,
+        redirect,
+        basePath,
+    ]);
+
+    return <SaveButton {...props} handleSubmitWithRedirect={handleClick} />;
+};
+```
+
+This button can be used in the `PostCreateToolbar` component:
+
+```jsx
+const PostCreateToolbar = props => (
+    <Toolbar {...props}>
+        <SaveButton
+            label="post.action.save_and_show"
+            redirect="show"
+            submitOnEnter={true}
+        />
+        <SaveWithNoteButton
+            label="post.action.save_with_average_note"
+            redirect="show"
+            submitOnEnter={false}
+            variant="text"
+        />
+    </Toolbar>
+);
+```
+
+**Note**: This technique will not trigger a form validation pass.