update docs for 5.6.1

Author: slax57

CreateDialog.md

@@ -210,35 +210,31 @@ Unlike the `<Create>` components, with Dialog components the title will be displ
 Here is an example:
 
 ```tsx
-import React from 'react';
 import {
     List,
+    ListActions,
     Datagrid,
     SimpleForm,
     TextInput,
     DateInput,
     required,
 } from 'react-admin';
-import {
-    CreateDialog,
-} from '@react-admin/ra-form-layout';
+import { CreateDialog } from '@react-admin/ra-form-layout';
 
 const CustomerList = () => (
     <>
-        <List hasCreate>
+        <List actions={<ListActions hasCreate />}>
             <Datagrid>
                 ...
-                <ShowButton />
             </Datagrid>
         </List>
-        <ShowDialog title={<CustomerShowTitle />}>
-            <SimpleShowLayout>
-                <TextField source="id" />
-                <TextField source="first_name" />
-                <TextField source="last_name" />
-                <DateField source="date_of_birth" label="born" />
-            </SimpleShowLayout>
-        </ShowDialog>
+        <CreateDialog title="Create a new customer">
+            <SimpleForm>
+                <TextInput source="first_name" validate={required()} />
+                <TextInput source="last_name" validate={required()} />
+                <DateInput source="date_of_birth" />
+            </SimpleForm>
+        </CreateDialog>
     </>
 );
 ```
@@ -464,9 +460,7 @@ const EmployerEdit = () => (
 
 ## Warn When There Are Unsaved Changes
 
-If you'd like to trigger a warning when the user tries to close the dialog with unsaved changes, there are two cases to consider.
-
-In that case, you can leverage the [warnWhenUnsavedChanges](./Form.md#warnwhenunsavedchanges) feature provided by React Admin forms.
+If you'd like to trigger a warning when the user tries to close the dialog with unsaved changes, you can leverage the [warnWhenUnsavedChanges](./Form.md#warnwhenunsavedchanges) feature provided by React Admin forms.
 
 Add the `warnWhenUnsavedChanges` prop to your Form like so:
 

CreateInDialogButton.md

@@ -293,9 +293,7 @@ You can also hide the title by passing `null`:
 
 ## Warn When There Are Unsaved Changes
 
-If you'd like to trigger a warning when the user tries to close the dialog with unsaved changes, there are two cases to consider.
-
-In that case, using the `warnWhenUnsavedChanges` prop directly on the form won't work, because this feature relies on the router's location, but both components do not use routing.
+If you'd like to trigger a warning when the user tries to close the dialog with unsaved changes, using the `warnWhenUnsavedChanges` prop directly on the form won't work, because this feature relies on the router's location, but both components do not use routing.
 
 Instead, you can use the `<WarnWhenUnsavedChangesInDialog>` component provided by `ra-form-layout`.
 

DataFetchingGuide.md

@@ -414,7 +414,7 @@ Once your data provider has enabled realtime features, you can use these hooks a
 - [`useLockOnCall`](./useLockOnCall.md)
 - [`useGetListLive`](./useGetListLive.md)
 - [`useGetOneLive`](./useGetOneLive.md)
-- [`<ListLive>`](./ListLive.md)
+- [`<ListLiveUpdate>`](./ListLiveUpdate.md)
 - [`<EditLive>`](./EditLive.md)
 - [`<ShowLive>`](./ShowLive.md)
 - [`<MenuLive>`](./MenuLive.md)

DataProviderLive.md

@@ -61,7 +61,7 @@ Once your data provider has enabled realtime features, you can use these hooks a
 - [`useLockOnCall`](./useLockOnCall.md)
 - [`useGetListLive`](./useGetListLive.md)
 - [`useGetOneLive`](./useGetOneLive.md)
-- [`<ListLive>`](./ListLive.md)
+- [`<ListLiveUpdate>`](./ListLiveUpdate.md)
 - [`<EditLive>`](./EditLive.md)
 - [`<ShowLive>`](./ShowLive.md)
 - [`<MenuLive>`](./MenuLive.md)

DatagridAG.md

@@ -2851,7 +2851,7 @@ const CarList = () => {
 
 ### Access Control
 
-`<DatagridAG>` has built-in [access control](./Permissions.me#access-control). If the `authProvider` implements the `canAccess` method, users will only be allowed to edit rows of, say, resource `'cars'` if `canAccess({ action: 'edit', resource: 'cars' })` returns `true`.
+`<DatagridAGClient>` has built-in [access control](./Permissions.me#access-control). If the `authProvider` implements the `canAccess` method, users will only be allowed to edit rows of, say, resource `'cars'` if `canAccess({ action: 'edit', resource: 'cars' })` returns `true`.
 
 **Note:** the access control check can only be done at the resource level and not at the record level.
 

EditDialog.md

@@ -236,8 +236,9 @@ const MyEditDialog = () => (
 
 ## `title`
 
-Unlike the `<Create>` components, with Dialog components the title will be displayed in the `<Dialog>`, not in the `<AppBar>`.
-If you pass a custom title component, it will render in the same `RecordContext` as the dialog's child component. That means you can display non-editable details of the current `record` in the title component.
+Unlike the `<Edit>` components, with Dialog components the title will be displayed in the `<Dialog>`, not in the `<AppBar>`.
+If you pass a custom title component, it will render in the same `RecordContext` as the dialog's child component.
+That means you can display non-editable details of the current `record` in the title component.
 Here is an example:
 
 ```tsx
@@ -501,9 +502,7 @@ const EmployerEdit = () => (
 
 ## Warn When There Are Unsaved Changes
 
-If you'd like to trigger a warning when the user tries to close the dialog with unsaved changes, there are two cases to consider.
-
-In that case, you can leverage the [warnWhenUnsavedChanges](./Form.md#warnwhenunsavedchanges) feature provided by React Admin forms.
+If you'd like to trigger a warning when the user tries to close the dialog with unsaved changes, you can leverage the [warnWhenUnsavedChanges](./Form.md#warnwhenunsavedchanges) feature provided by React Admin forms.
 
 Add the `warnWhenUnsavedChanges` prop to your Form like so:
 

EditInDialogButton.md

@@ -302,7 +302,8 @@ const EditButton = () => (
 ## `title`
 
 Unlike the `<Edit>` components, with Dialog components the title will be displayed in the `<Dialog>`, not in the `<AppBar>`.
-Still, for `<EditInDialogButton>`, if you pass a custom title component, it will render in the same `RecordContext` as the dialog's child component. That means you can display non-editable details of the current `record` in the title component.
+If you pass a custom title component, it will render in the same `RecordContext` as the dialog's child component.
+That means you can display non-editable details of the current `record` in the title component.
 Here is an example:
 
 ```tsx
@@ -383,9 +384,7 @@ const EmployerEdit = () => (
 
 ## Warn When There Are Unsaved Changes
 
-If you'd like to trigger a warning when the user tries to close the dialog with unsaved changes, there are two cases to consider.
-
-In that case, using the `warnWhenUnsavedChanges` prop directly on the form won't work, because this feature relies on the router's location, but both components do not use routing.
+If you'd like to trigger a warning when the user tries to close the dialog with unsaved changes, using the `warnWhenUnsavedChanges` prop directly on the form won't work, because this feature relies on the router's location, but both components do not use routing.
 
 Instead, you can use the `<WarnWhenUnsavedChangesInDialog>` component provided by `ra-form-layout`.
 

Features.md

@@ -1164,28 +1164,27 @@ Check the following low-level hooks for more details:
 
 React-admin provides **live updates** via specialized hooks and components. This means that when a user edits a resource, the other users working on the same resource see the changes in real time whether they are in a list, a show view, or an edit view.
 
-For instance, replace `<List>` with `<ListLive>` to have a list refreshing automatically when an element is added, updated, or deleted:
+For instance, include a `<ListLiveUpdate>` within a `<List>` to have a list refreshing automatically when an element is added, updated, or deleted:
 
 ```diff
 import {
--   List,
+    List,
     Datagrid,
     TextField,
     NumberField,
     Datefield,
 } from 'react-admin';
-+import { ListLive } from '@react-admin/ra-realtime';
++import { ListLiveUpdate } from '@react-admin/ra-realtime';
 
 const PostList = () => (
--   <List>
-+   <ListLive>
+    <List>
         <Datagrid>
             <TextField source="title" />
             <NumberField source="views" />
             <DateField source="published_at" />
         </Datagrid>
--   </List>
-+   </ListLive>
++       <ListLiveUpdate />
+    </List>
 );
 ```
 
@@ -1202,7 +1201,7 @@ This feature leverages the following hooks:
 
 And the following components:
 
-- [`<ListLive>`](./ListLive.md)
+- [`<ListLiveUpdate>`](./ListLiveUpdate.md)
 - [`<EditLive>`](./EditLive.md)
 - [`<ShowLive>`](./ShowLive.md)
 

List.md

@@ -1085,21 +1085,19 @@ const BookList = () => (
 
 ## Live Updates
 
-If you want to subscribe to live updates on the list of records (topic: `resource/[resource]`), use [the `<ListLive>` component](./ListLive.md) instead.
+If you want to subscribe to live updates on the list of records (topic: `resource/[resource]`), add [the `<ListLiveUpdate>` component](./ListLiveUpdate.md) in your `<List>` children.
 
 ```diff
--import { List, Datagrid, TextField } from 'react-admin';
-+import { Datagrid, TextField } from 'react-admin';
-+import { ListLive } from '@react-admin/ra-realtime';
+import { List, Datagrid, TextField } from 'react-admin';
++import { ListLiveUpdate } from '@react-admin/ra-realtime';
 
 const PostList = () => (
--   <List>
-+   <ListLive>
+    <List>
         <Datagrid>
             <TextField source="title" />
         </Datagrid>
--   </List>
-+   </ListLive>
++       <ListLiveUpdate />
+    </List>
 );
 ```
 

ListLiveUpdate.md

@@ -0,0 +1,91 @@
+---
+layout: default
+title: "ListLiveUpdate"
+---
+
+# `<ListLiveUpdate>`
+
+`<ListLiveUpdate>` is an [Enterprise Edition](https://react-admin-ee.marmelab.com)<img class="icon" src="./img/premium.svg" /> component that refreshes its parent `ListContext` (e.g in a [`<List>`](./List.md)) when a record is created, updated, or deleted.
+
+![ListLive](./img/ListLive.png)
+
+## Usage
+
+Add the `<ListLiveUpdate>` in your `<List>` children:
+
+```jsx
+import { Datagrid, List TextField } from 'react-admin';
+import { ListLiveUpdate } from '@react-admin/ra-realtime';
+
+const PostList = () => (
+    <List>
+        <Datagrid>
+            <TextField source="title" />
+        </Datagrid>
+        <ListLiveUpdate />
+    </List>
+);
+```
+
+To trigger refreshes of `<ListLiveUpdate>`, the API has to publish events containing at least the followings:
+
+```js
+{
+    topic : '/resource/{resource}',
+    event: {
+        type: '{deleted || created || updated}',
+        payload: { ids: [{listOfRecordIdentifiers}]},
+    }
+}
+```
+
+
+This also works with [`<ReferenceManyField>`](https://marmelab.com/react-admin/ReferenceManyField.html) or [`<ReferenceArrayField>`](https://marmelab.com/react-admin/ReferenceArrayField.html):
+```tsx
+import { Show, SimpleShowLayout, ReferenceManyField, Datagrid, TextField, DateField } from 'react-admin';
+import { ListLiveUpdate } from '@react-admin/ra-realtime';
+const AuthorShow = () => (
+    <Show>
+        <SimpleShowLayout>
+            <TextField source="first_name" />
+            <TextField source="last_name" />
+            <ReferenceManyField reference="books" target="author_id" label="Books">
+              <Datagrid>
+                <TextField source="title" />
+                <DateField source="published_at" />
+              </Datagrid>
+              <ListLiveUpdate />
+            </ReferenceManyField>
+        </SimpleShowLayout>
+    </Show>
+);
+```
+
+## `onEventReceived`
+
+The `<ListLiveUpdate>` allows you to customize the side effects triggered when it receives a new event, by passing a function to the `onEventReceived` prop:
+
+```jsx
+import { Datagrid, List, TextField, useNotify, useRefresh } from 'react-admin';
+import { ListLiveUpdate } from '@react-admin/ra-realtime';
+
+const PostList = () => {
+    const notify = useNotify();
+    const refresh = useRefresh();
+
+    const handleEventReceived = event => {
+        const count = get(event, 'payload.ids.length', 1);
+        notify(`${count} items updated by another user`);
+        refresh();
+    };
+
+    return (
+        <List>
+            <Datagrid>
+                <TextField source="title" />
+            </Datagrid>
+            <ListLiveUpdate onEventReceived={handleEventReceived} />
+        </List>
+    );
+};
+```