Merge pull request #10531 from marmelab/doc-list-live-update

[Doc] Promote composition with `<ListLiveUpdate>` instead of `<ListLive>`

docs/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)

docs/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)

docs/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)
 

docs/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>
 );
 ```
 

docs/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>
+    );
+};
+```

docs/Realtime.md

@@ -54,28 +54,27 @@ useSubscribe(topic, callback);
 
 Ra-realtime 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>
 );
 ```
 
@@ -85,15 +84,14 @@ const PostList = () => (
   Your browser does not support the video tag.
 </video>
 
-
 This feature leverages the following hooks:
 
 -   [`useGetListLive`](./useGetListLive.md)
 -   [`useGetOneLive`](./useGetOneLive.md)
 
 And the following components:
 
--   [`<ListLive>`](./ListLive.md)
+-   [`<ListLiveUpdate>`](./ListLiveUpdate.md)
 -   [`<EditLive>`](./EditLive.md)
 -   [`<ShowLive>`](./ShowLive.md)
 

docs/RealtimeDataProvider.md

@@ -39,8 +39,8 @@ This adapter subscribes to [Postgres Changes](https://supabase.com/docs/guides/r
 ```jsx
 import { createClient } from '@supabase/supabase-js';
 import { supabaseDataProvider } from 'ra-supabase';
-import { addRealTimeMethodsBasedOnSupabase, ListLive } from '@react-admin/ra-realtime';
-import { Admin, Resource, Datagrid, TextField, EmailField } from 'react-admin';
+import { addRealTimeMethodsBasedOnSupabase, ListLiveUpdate } from '@react-admin/ra-realtime';
+import { Admin, Resource, Datagrid, List, TextField, EmailField } from 'react-admin';
 
 const supabaseClient = createClient(
     process.env.SUPABASE_URL,
@@ -65,14 +65,15 @@ export const App = () => (
 );
 
 const SaleList = () => (
-    <ListLive>
+    <List>
         <Datagrid>
             <TextField source="id" />
             <TextField source="first_name" />
             <TextField source="last_name" />
             <EmailField source="email" />
         </Datagrid>
-    </ListLive>
+        <ListLiveUpdate />
+    </List>
 );
 ```
 
@@ -115,15 +116,15 @@ Have a look at the Supabase [Replication Setup](https://supabase.com/docs/guides
 The `ra-realtime` package contains a function augmenting a regular (API-based) `dataProvider` with real-time methods based on the capabilities of [API-Platform](https://api-platform.com/). Use it as follows:
 
 ```jsx
-import { Datagrid, EditButton, ListProps } from 'react-admin';
+import { Datagrid, EditButton, List, ListProps } from 'react-admin';
 import {
     HydraAdmin,
     ResourceGuesser,
     FieldGuesser,
     hydraDataProvider,
 } from '@api-platform/admin';
 import {
-    ListLive,
+    ListLiveUpdate,
     addRealTimeMethodsBasedOnApiPlatform,
 } from '@react-admin/ra-realtime';
 
@@ -151,12 +152,13 @@ const App = () => (
 
 // Example for connecting a list of greetings
 const GreetingsList = () => (
-    <ListLive>
+    <List>
         <Datagrid>
             <FieldGuesser source="name" />
             <EditButton />
         </Datagrid>
-    </ListLive>
+        <ListLiveUpdate />
+    </List>
 );
 ```
 

docs/Reference.md

@@ -116,7 +116,7 @@ title: "Index"
 * [`<ListBase>`](./ListBase.md#usage)
 * [`<ListButton>`](./Buttons.md#listbutton)
 * [`<ListGuesser>`](./ListGuesser.md#usage)
-* [`<ListLive>`](./ListLive.md)<img class="icon" src="./img/premium.svg" />
+* [`<ListLiveUpdate>`](./ListLiveUpdate.md)<img class="icon" src="./img/premium.svg" />
 * [`<LocalesMenuButton>`](./LocalesMenuButton.md)
 * [`<LongForm>`](./LongForm.md)<img class="icon" src="./img/premium.svg" />
 * [`<Login>`](./Authentication.md#customizing-the-login-component)

docs/navigation.html

@@ -300,7 +300,7 @@
     <li {% if page.path == 'useLockOnCall.md' %} class="active" {% endif %}><a class="nav-link" href="./useLockOnCall.html"><code>useLockOnCall</code><img class="premium" src="./img/premium.svg" /></a></li>
     <li {% if page.path == 'useGetListLive.md' %} class="active" {% endif %}><a class="nav-link" href="./useGetListLive.html"><code>useGetListLive</code><img class="premium" src="./img/premium.svg" /></a></li>
     <li {% if page.path == 'useGetOneLive.md' %} class="active" {% endif %}><a class="nav-link" href="./useGetOneLive.html"><code>useGetOneLive</code><img class="premium" src="./img/premium.svg" /></a></li>
-    <li {% if page.path == 'ListLive.md' %} class="active" {% endif %}><a class="nav-link" href="./ListLive.html"><code>&lt;ListLive&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
+    <li {% if page.path == 'ListLiveUpdate.md' %} class="active" {% endif %}><a class="nav-link" href="./ListLiveUpdate.html"><code>&lt;ListLiveUpdate&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
     <li {% if page.path == 'EditLive.md' %} class="active" {% endif %}><a class="nav-link" href="./EditLive.html"><code>&lt;EditLive&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
     <li {% if page.path == 'ShowLive.md' %} class="active" {% endif %}><a class="nav-link" href="./ShowLive.html"><code>&lt;ShowLive&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
     <li {% if page.path == 'MenuLive.md' %} class="active" {% endif %}><a class="nav-link" href="./MenuLive.html"><code>&lt;MenuLive&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>