Skip to content

Commit 6d64b43

Browse files
djhidjhi
committed
[Doc] Update Soft Delete documentation
1 parent 25b8652 commit 6d64b43

17 files changed

+1697
-20
lines changed

‎docs/DeletedRecordsList.md‎

Lines changed: 76 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -36,24 +36,41 @@ That's enough to display the deleted records list, with functional simple filter
3636

3737
## Props
3838

39-
| Prop | Required | Type | Default | Description |
40-
|----------------------------|----------|---------------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------|
41-
| `debounce` | Optional | `number` | `500` | The debounce delay in milliseconds to apply when users change the sort or filter parameters. |
42-
| `children` | Optional | `Element` | `<Deleted Records Table>` | The component used to render the list of deleted records. |
43-
| `detail Components` | Optional | `Record<string, ComponentType>` | - | The custom show components for each resource in the deleted records list. |
44-
| `disable Authentication` | Optional | `boolean` | `false` | Set to `true` to disable the authentication check. |
45-
| `disable SyncWithLocation` | Optional | `boolean` | `false` | Set to `true` to disable the synchronization of the list parameters with the URL. |
46-
| `filter` | Optional | `object` | - | The permanent filter values. |
47-
| `filter DefaultValues` | Optional | `object` | - | The default filter values. |
48-
| `mutation Mode` | Optional | `string` | `'undoable'` | Mutation mode (`'undoable'`, `'pessimistic'` or `'optimistic'`). |
49-
| `pagination` | Optional | `ReactElement` | `<Pagination>` | The pagination component to use. |
50-
| `perPage` | Optional | `number` | `10` | The number of records to fetch per page. |
51-
| `queryOptions` | Optional | `object` | - | The options to pass to the `useQuery` hook. |
52-
| `resource` | Optional | `string` | - | The resource of deleted records to fetch and display |
53-
| `sort` | Optional | `object` | `{ field: 'deleted_at', order: 'DESC' }` | The initial sort parameters. |
54-
| `storeKey` | Optional | `string` or `false` | - | The key to use to store the current filter & sort. Pass `false` to disable store synchronization |
55-
| `title` | Optional | `string | ReactElement | false` | - | The title to display in the App Bar. |
56-
| `sx` | Optional | `object` | - | The CSS styles to apply to the component. |
39+
| Prop | Required | Type | Default | Description |
40+
|----------------------------|----------------|---------------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------|
41+
| `authLoading` | Optional | `ReactNode` | - | The component to render while checking for authentication and permissions. |
42+
| `debounce` | Optional | `number` | `500` | The debounce delay in milliseconds to apply when users change the sort or filter parameters. |
43+
| `children` | Optional | `Element` | `<DeletedRecordsTable>` | The component used to render the list of deleted records. |
44+
| `detailComponents` | Optional | `Record<string, ComponentType>` | - | The custom show components for each resource in the deleted records list. |
45+
| `disable Authentication` | Optional | `boolean` | `false` | Set to `true` to disable the authentication check. |
46+
| `disable SyncWithLocation` | Optional | `boolean` | `false` | Set to `true` to disable the synchronization of the list parameters with the URL. |
47+
| `empty` | Optional | `ReactNode` | - | The component to display when the list is empty. |
48+
| `error` | Optional | `ReactNode` | - | The component to render when failing to load the list of records. |
49+
| `filter` | Optional | `object` | - | The permanent filter values. |
50+
| `filter DefaultValues` | Optional | `object` | - | The default filter values. |
51+
| `loading` | Optional | `ReactNode` | - | The component to render while loading the list of records. |
52+
| `mutation Mode` | Optional | `string` | `'undoable'` | Mutation mode (`'undoable'`, `'pessimistic'` or `'optimistic'`). |
53+
| `offline` | Optional | `ReactNode` | `<Offline>` | The component to render when there is no connectivity and there is no data in the cache |
54+
| `pagination` | Optional | `ReactElement` | `<Pagination>` | The pagination component to use. |
55+
| `perPage` | Optional | `number` | `10` | The number of records to fetch per page. |
56+
| `queryOptions` | Optional | `object` | - | The options to pass to the `useQuery` hook. |
57+
| `resource` | Optional | `string` | - | The resource of deleted records to fetch and display |
58+
| `sort` | Optional | `object` | `{ field: 'deleted_at', order: 'DESC' }` | The initial sort parameters. |
59+
| `storeKey` | Optional | `string` or `false` | - | The key to use to store the current filter & sort. Pass `false` to disable store synchronization |
60+
| `title` | Optional | `string | ReactElement | false` | - | The title to display in the App Bar. |
61+
| `sx` | Optional | `object` | - | The CSS styles to apply to the component. |
62+
63+
## `authLoading`
64+
65+
By default, `<DeletedRecordsList>` renders `<Loading>` while checking for authentication and permissions. You can display a custom component via the `authLoading` prop:
66+
67+
```jsx
68+
import { DeletedRecordsList } from '@react-admin/ra-soft-delete';
69+
70+
export const CustomDeletedRecords = () => (
71+
<DeletedRecordsList authLoading={<p>Checking for permissions...</p>} />
72+
);
73+
```
5774

5875
## `children`
5976

@@ -152,9 +169,21 @@ const DeletedRecordsWithoutSyncWithLocation = () => <DeletedRecordsList disableS
152169
const DeletedRecordsSyncWithStore = () => <DeletedRecordsList disableSyncWithLocation storeKey="deletedRecordsListParams" />;
153170
```
154171

172+
## `error`
173+
174+
By default, `<DeletedRecordsList>` renders the children when an error happens while loading the list of deleted records. You can render an error component via the `error` prop:
175+
176+
```jsx
177+
import { DeletedRecordsList } from '@react-admin/ra-soft-delete';
178+
179+
export const CustomDeletedRecords = () => (
180+
<DeletedRecordsList error={<p>Something went wrong while loading your posts!</p>} />
181+
);
182+
```
183+
155184
## `filter`: Permanent Filter
156185

157-
You can choose to always filter the list, without letting the user disable this filter - for instance to display only published posts. Write the filter to be passed to the data provider in the `filter` props:
186+
You can choose to always filter the list, without letting the user disable this filter - for instance to display only published posts. Write the filter to be passed to the data provider in the `filter` prop:
158187

159188
{% raw %}
160189
```tsx
@@ -184,6 +213,19 @@ const filterSentToDataProvider = { ...filterDefaultValues, ...filterChosenByUser
184213
```
185214
{% endraw %}
186215

216+
## `loading`
217+
218+
By default, `<DeletedRecordsList>` renders the children while loading the list of deleted records. You can display a component during this time via the `loading` prop:
219+
220+
```jsx
221+
import { Loading } from 'react-admin';
222+
import { DeletedRecordsList } from '@react-admin/ra-soft-delete';
223+
224+
export const CustomDeletedRecords = () => (
225+
<DeletedRecordsList loading={<Loading />} />
226+
);
227+
```
228+
187229
## `mutationMode`
188230

189231
The `<DeletedRecordsList>` list exposes restore and delete permanently buttons, which perform "mutations" (i.e. they alter the data). React-admin offers three modes for mutations. The mode determines when the side effects (redirection, notifications, etc.) are executed:
@@ -212,6 +254,21 @@ const PessimisticDeletedRecords = () => (
212254

213255
**Tip**: When using any other mode than `undoable`, the `<DeletePermanentlyButton>` and `<RestoreButton>` display a confirmation dialog before calling the dataProvider.
214256

257+
## `offline`
258+
259+
By default, `<DeletedRecordsList>` renders the `<Offline>` component when there is no connectivity and there are no records in the cache yet for the current parameters (page, sort, etc.). You can provide your own component via the `offline` prop:
260+
261+
```jsx
262+
import { DeletedRecordsList } from '@react-admin/ra-soft-delete';
263+
import { Alert } from '@mui/material';
264+
265+
const offline = <Alert severity="warning">No network. Could not load the posts.</Alert>;
266+
267+
export const CustomDeletedRecords = () => (
268+
<DeletedRecordsList offline={offline} />
269+
);
270+
```
271+
215272
## `pagination`
216273

217274
By default, the `<DeletedRecordsList>` view displays a set of pagination controls at the bottom of the list.

‎docs/SoftDeleteDataProvider.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ export const dataProvider = addSoftDeleteInPlace(
185185

186186
**Note:** When using `addSoftDeleteInPlace`, avoid calling `getListDeleted` without a `resource` filter, as it uses a naive implementation combining multiple `getList` calls, which can lead to bad performance. It is recommended to use one list per resource in this case (see [`<DeletedRecordsList resource>` property](./DeletedRecordsList.md#resource)).
187187

188-
You can also write your own implementation. Feel free to look at these builders source code for inspiration. You can find it under your `node_modules` folder, e.g. at `node_modules/@react-admin/ra-soft-delete/src/dataProvider/addSoftDeleteBasedOnResource.ts`.
188+
You can also write your own implementation. Feel free to look at these builders source code for inspiration. You can find it under your `node_modules` folder, e.g. at `node_modules/@react-admin/ra-core-ee/src/soft-delete/dataProvider/addSoftDeleteBasedOnResource.ts`.
189189

190190
### Query and Mutation Hooks
191191

‎docs_headless/astro.config.mjs‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,25 @@ export default defineConfig({
237237
enterpriseEntry('<LockStatusBase>'),
238238
],
239239
},
240+
{
241+
label: 'Soft Delete',
242+
items: [
243+
enterpriseEntry('addSoftDeleteBasedOnResource'),
244+
enterpriseEntry('addSoftDeleteInPlace'),
245+
enterpriseEntry('useSoftDelete'),
246+
enterpriseEntry('useSoftDeleteMany'),
247+
enterpriseEntry('useGetListDeleted'),
248+
enterpriseEntry('useGetOneDeleted'),
249+
enterpriseEntry('useRestoreOne'),
250+
enterpriseEntry('useRestoreMany'),
251+
enterpriseEntry('useHardDelete'),
252+
enterpriseEntry('useHardDeleteMany'),
253+
enterpriseEntry('useDeletedRecordsListController'),
254+
enterpriseEntry('DeletedRecordsListBase'),
255+
enterpriseEntry('ShowDeletedBase'),
256+
enterpriseEntry('DeletedRecordRepresentation'),
257+
],
258+
},
240259
{
241260
label: 'Recipes',
242261
items: ['caching', 'unittesting'],

‎docs_headless/src/content/docs/DeletedRecordRepresentation.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: "<DeletedRecordRepresentation>"
3+
---
4+
5+
A component that renders the record representation of a deleted record.
6+
7+
This feature requires a valid [Enterprise Edition](https://marmelab.com/ra-enterprise/) subscription.
8+
9+
## Installation
10+
11+
```bash
12+
npm install --save @react-admin/ra-core-ee
13+
# or
14+
yarn add @react-admin/ra-core-ee
15+
```
16+
17+
## Usage
18+
19+
```tsx
20+
import { CoreAdmin, CustomRoutes, WithRecord } from 'react-admin';
21+
import { Route } from 'react-router-dom';
22+
import { DeletedRecordsListBase, ShowDeletedBase, type DeletedRecordType } from '@react-admin/ra-core-ee';
23+
24+
export const App = () => (
25+
<CoreAdmin>
26+
...
27+
<CustomRoutes>
28+
<Route
29+
path="/deleted"
30+
element={
31+
<DeletedRecordsListBase>
32+
<WithListContext
33+
render={({ isPending, data }) => isPending ? null : (
34+
<ul>
35+
{data.map(record => (
36+
<li key={record.id}>
37+
<div><strong>{record.resource}</strong></div>
38+
<DeletedRecordRepresentation record={record} />
39+
</li>
40+
))}
41+
</ul>
42+
)}
43+
/>
44+
</DeletedRecordsListBase>
45+
}
46+
/>
47+
</CustomRoutes>
48+
</CoreAdmin>
49+
);
50+
```
51+
52+
## Props
53+
54+
| Prop | Required | Type | Default | Description |
55+
|------------|----------|------------|---------|---------------------------------------------------------------------------------------|
56+
| `record` | Optional | `RaRecord` | | The deleted record. If not provided, the record from closest `RecordContext` is used. |

0 commit comments

Comments
 (0)