Skip to content

Commit dea763c

Browse files
slax57slax57
committed
Update the documentation for version 5.11.1
1 parent 19afa64 commit dea763c

15 files changed

+565
-7
lines changed

‎LockOnMount.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
layout: default
3+
title: "LockOnMount"
4+
---
5+
6+
# `<LockOnMount>`
7+
8+
`<LockOnMount>` is the component version of the [`useLockOnMount`](./useLockOnMount.md) hook. It locks the current record on mount and unlocks it on unmount. It relies on `authProvider.getIdentity()` to get the identity of the current user. It guesses the current `resource` and `recordId` from the context (or the route) if not provided.
9+
10+
<video controls autoplay playsinline muted loop>
11+
<source src="https://registry.marmelab.com/assets/useLockOnMount.mp4" type="video/mp4"/>
12+
Your browser does not support the video tag.
13+
</video>
14+
15+
## Usage
16+
17+
Use this hook e.g. in an `<Edit>` component to lock the record so that it only accepts updates from the current user.
18+
19+
```tsx
20+
import { Edit, SimpleForm, TextInput } from 'react-admin';
21+
import { LockOnMount } from '@react-admin/ra-realtime';
22+
23+
const PostEdit = () => (
24+
<Edit>
25+
<SimpleForm>
26+
<TextInput source="title" fullWidth />
27+
<TextInput source="headline" fullWidth multiline />
28+
<TextInput source="author" fullWidth />
29+
<LockOnMount />
30+
</SimpleForm>
31+
</Edit>
32+
);
33+
```
34+
35+
**Note**: If users close their tab/browser when on a page with a locked record, `LockOnMount` will block the navigation and show a notification until the record is unlocked.
36+
37+
## Parameters
38+
39+
`<LockOnMount>` accepts the same props as the [`useLockOnMount`](./useLockOnMount.md) hook.
40+

‎LockStatus.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
layout: default
3+
title: "LockStatus"
4+
---
5+
6+
# `<LockStatus>`
7+
8+
`<LockStatus>` is an [Enterprise Edition](https://react-admin-ee.marmelab.com)<img class="icon" src="./img/premium.svg" alt="React Admin Enterprise Edition icon" /> component that displays the lock status of the current record. It allows to visually indicate whether the record is locked or not, by the current user or not, and provides an easy way to lock or unlock the record.
9+
10+
<video controls autoplay playsinline muted loop>
11+
<source src="https://registry.marmelab.com/assets/LockStatus.mp4" type="video/mp4"/>
12+
Your browser does not support the video tag.
13+
</video>
14+
15+
## Usage
16+
17+
Use `<LockStatus>` e.g. in a toolbar, to let the user know the lock status of the current record:
18+
19+
{% raw %}
20+
```tsx
21+
import { Toolbar, SaveButton } from 'react-admin';
22+
import { LockStatus } from '@react-admin/ra-realtime';
23+
24+
const CustomToolbar = () => {
25+
return (
26+
<Toolbar>
27+
<SaveButton sx={{ mr: 1 }} />
28+
<LockStatus />
29+
</Toolbar>
30+
);
31+
};
32+
```
33+
{% endraw %}
34+
35+
You can also use it in a DataTable to show the lock status of each record:
36+
37+
```tsx
38+
import { List, DataTable } from 'react-admin';
39+
import { LockStatus } from '@react-admin/ra-realtime';
40+
41+
const PostList = () => {
42+
return (
43+
<List>
44+
<DataTable>
45+
<DataTable.Col source="id" />
46+
<DataTable.Col source="title" />
47+
<DataTable.Col source="headline" />
48+
<DataTable.Col source="author" />
49+
<DataTable.Col label="Lock">
50+
<LockStatus hideWhenUnlocked />
51+
</DataTable.Col>
52+
</DataTable>
53+
</List>
54+
);
55+
};
56+
```
57+
58+
**Tip:** You can use the `hideWhenUnlocked` prop to hide the lock status when the record is not locked. This is useful to avoid showing too many lock icons in the DataTable when most records are not locked.
59+
60+
## Props
61+
62+
| Name | Required | Type | Default Value | Description |
63+
| ----------------------- | -------- | ------------ | --------------------------------- | --------------------------------------------------------------------------------------------- |
64+
| `hideWhenUnlocked` | No | `boolean` | - | Set to true to hide the lock status when the record is not locked. |
65+
| `identity` | No | `Identifier` | From `AuthProvider.getIdentity()` | An identifier for the user who owns the lock. |
66+
| `resource` | No | `string` | From `ResourceContext` | The resource name (e.g. `'posts'`). |
67+
| `id` | No | `Identifier` | From `RecordContext` | The record id (e.g. `123`). |
68+
| `meta` | No | `object` | - | Additional metadata forwarded to the dataProvider `lock()`, `unlock()` and `getLock()` calls. |
69+
| `lockMutationOptions` | No | `object` | - | `react-query` mutation options, used to customize the lock side-effects. |
70+
| `unlockMutationOptions` | No | `object` | - | `react-query` mutation options, used to customize the unlock side-effects. |
71+
| `queryOptions` | No | `object` | - | `react-query` query options, used to customize the lock query side-effects. |
72+
73+
## Customizing the Tooltip Messages
74+
75+
You can customize the tooltip messages displayed by `<LockStatus>` by overriding the following i18n keys in your translations:
76+
- `ra-realtime.locks.status.locked_by_you`: The tooltip message when the record is locked by the current user.
77+
- `ra-realtime.locks.status.locked_by_another_user`: The tooltip message when the record is locked by another user.
78+
- `ra-realtime.locks.status.unlocked`: The tooltip message when the record is unlocked.

‎ReferenceFieldBase.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ It uses `dataProvider.getMany()` instead of `dataProvider.getOne()` [for perform
7070
| `empty` | Optional | `ReactNode` | - | What to render when the field has no value or when the reference is missing |
7171
| `offline` | Optional | `ReactNode` | - | What to render when there is no network connectivity when loading the record |
7272
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` client options |
73+
| `record` | Optional | `RaRecord` | - | The current record |
7374
| `sortBy` | Optional | `string | Function` | `source` | Name of the field to use for sorting when used in a Datagrid |
7475

7576
## `children`

‎_data/versions.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
- latest (5.11.0)
1+
- latest (5.11.1)
22
- "5.10"
33
- "5.9"
44
- "5.8"

‎doc/5.11/LockOnMount.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
layout: default
3+
title: "LockOnMount"
4+
---
5+
6+
# `<LockOnMount>`
7+
8+
`<LockOnMount>` is the component version of the [`useLockOnMount`](./useLockOnMount.md) hook. It locks the current record on mount and unlocks it on unmount. It relies on `authProvider.getIdentity()` to get the identity of the current user. It guesses the current `resource` and `recordId` from the context (or the route) if not provided.
9+
10+
<video controls autoplay playsinline muted loop>
11+
<source src="https://registry.marmelab.com/assets/useLockOnMount.mp4" type="video/mp4"/>
12+
Your browser does not support the video tag.
13+
</video>
14+
15+
## Usage
16+
17+
Use this hook e.g. in an `<Edit>` component to lock the record so that it only accepts updates from the current user.
18+
19+
```tsx
20+
import { Edit, SimpleForm, TextInput } from 'react-admin';
21+
import { LockOnMount } from '@react-admin/ra-realtime';
22+
23+
const PostEdit = () => (
24+
<Edit>
25+
<SimpleForm>
26+
<TextInput source="title" fullWidth />
27+
<TextInput source="headline" fullWidth multiline />
28+
<TextInput source="author" fullWidth />
29+
<LockOnMount />
30+
</SimpleForm>
31+
</Edit>
32+
);
33+
```
34+
35+
**Note**: If users close their tab/browser when on a page with a locked record, `LockOnMount` will block the navigation and show a notification until the record is unlocked.
36+
37+
## Parameters
38+
39+
`<LockOnMount>` accepts the same props as the [`useLockOnMount`](./useLockOnMount.md) hook.
40+

‎doc/5.11/LockStatus.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
layout: default
3+
title: "LockStatus"
4+
---
5+
6+
# `<LockStatus>`
7+
8+
`<LockStatus>` is an [Enterprise Edition](https://react-admin-ee.marmelab.com)<img class="icon" src="./img/premium.svg" alt="React Admin Enterprise Edition icon" /> component that displays the lock status of the current record. It allows to visually indicate whether the record is locked or not, by the current user or not, and provides an easy way to lock or unlock the record.
9+
10+
<video controls autoplay playsinline muted loop>
11+
<source src="https://registry.marmelab.com/assets/LockStatus.mp4" type="video/mp4"/>
12+
Your browser does not support the video tag.
13+
</video>
14+
15+
## Usage
16+
17+
Use `<LockStatus>` e.g. in a toolbar, to let the user know the lock status of the current record:
18+
19+
{% raw %}
20+
```tsx
21+
import { Toolbar, SaveButton } from 'react-admin';
22+
import { LockStatus } from '@react-admin/ra-realtime';
23+
24+
const CustomToolbar = () => {
25+
return (
26+
<Toolbar>
27+
<SaveButton sx={{ mr: 1 }} />
28+
<LockStatus />
29+
</Toolbar>
30+
);
31+
};
32+
```
33+
{% endraw %}
34+
35+
You can also use it in a DataTable to show the lock status of each record:
36+
37+
```tsx
38+
import { List, DataTable } from 'react-admin';
39+
import { LockStatus } from '@react-admin/ra-realtime';
40+
41+
const PostList = () => {
42+
return (
43+
<List>
44+
<DataTable>
45+
<DataTable.Col source="id" />
46+
<DataTable.Col source="title" />
47+
<DataTable.Col source="headline" />
48+
<DataTable.Col source="author" />
49+
<DataTable.Col label="Lock">
50+
<LockStatus hideWhenUnlocked />
51+
</DataTable.Col>
52+
</DataTable>
53+
</List>
54+
);
55+
};
56+
```
57+
58+
**Tip:** You can use the `hideWhenUnlocked` prop to hide the lock status when the record is not locked. This is useful to avoid showing too many lock icons in the DataTable when most records are not locked.
59+
60+
## Props
61+
62+
| Name | Required | Type | Default Value | Description |
63+
| ----------------------- | -------- | ------------ | --------------------------------- | --------------------------------------------------------------------------------------------- |
64+
| `hideWhenUnlocked` | No | `boolean` | - | Set to true to hide the lock status when the record is not locked. |
65+
| `identity` | No | `Identifier` | From `AuthProvider.getIdentity()` | An identifier for the user who owns the lock. |
66+
| `resource` | No | `string` | From `ResourceContext` | The resource name (e.g. `'posts'`). |
67+
| `id` | No | `Identifier` | From `RecordContext` | The record id (e.g. `123`). |
68+
| `meta` | No | `object` | - | Additional metadata forwarded to the dataProvider `lock()`, `unlock()` and `getLock()` calls. |
69+
| `lockMutationOptions` | No | `object` | - | `react-query` mutation options, used to customize the lock side-effects. |
70+
| `unlockMutationOptions` | No | `object` | - | `react-query` mutation options, used to customize the unlock side-effects. |
71+
| `queryOptions` | No | `object` | - | `react-query` query options, used to customize the lock query side-effects. |
72+
73+
## Customizing the Tooltip Messages
74+
75+
You can customize the tooltip messages displayed by `<LockStatus>` by overriding the following i18n keys in your translations:
76+
- `ra-realtime.locks.status.locked_by_you`: The tooltip message when the record is locked by the current user.
77+
- `ra-realtime.locks.status.locked_by_another_user`: The tooltip message when the record is locked by another user.
78+
- `ra-realtime.locks.status.unlocked`: The tooltip message when the record is unlocked.

‎doc/5.11/ReferenceFieldBase.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ It uses `dataProvider.getMany()` instead of `dataProvider.getOne()` [for perform
7070
| `empty` | Optional | `ReactNode` | - | What to render when the field has no value or when the reference is missing |
7171
| `offline` | Optional | `ReactNode` | - | What to render when there is no network connectivity when loading the record |
7272
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` client options |
73+
| `record` | Optional | `RaRecord` | - | The current record |
7374
| `sortBy` | Optional | `string | Function` | `source` | Name of the field to use for sorting when used in a Datagrid |
7475

7576
## `children`

‎doc/5.11/navigation.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -305,11 +305,14 @@
305305
<li {% if page.path == 'useGetLockLive.md' %} class="active" {% endif %}><a class="nav-link" href="./useGetLockLive.html"><code>useGetLockLive</code><img class="premium" src="./img/premium.svg" /></a></li>
306306
<li {% if page.path == 'useGetLocks.md' %} class="active" {% endif %}><a class="nav-link" href="./useGetLocks.html"><code>useGetLocks</code><img class="premium" src="./img/premium.svg" /></a></li>
307307
<li {% if page.path == 'useGetLocksLive.md' %} class="active" {% endif %}><a class="nav-link" href="./useGetLocksLive.html"><code>useGetLocksLive</code><img class="premium" src="./img/premium.svg" /></a></li>
308+
<li {% if page.path == 'useLockCallbacks.md' %} class="active" {% endif %}><a class="nav-link" href="./useLockCallbacks.html"><code>useLockCallbacks</code><img class="premium" src="./img/premium.svg" /></a></li>
308309
<li {% if page.path == 'useLockOnMount.md' %} class="active" {% endif %}><a class="nav-link" href="./useLockOnMount.html"><code>useLockOnMount</code><img class="premium" src="./img/premium.svg" /></a></li>
309310
<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>
310311
<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>
311312
<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>
312313
<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>
314+
<li {% if page.path == 'LockOnMount.md' %} class="active" {% endif %}><a class="nav-link" href="./LockOnMount.html"><code>&lt;LockOnMount&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
315+
<li {% if page.path == 'LockStatus.md' %} class="active" {% endif %}><a class="nav-link" href="./LockStatus.html"><code>&lt;LockStatus&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
313316
<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>
314317
<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>
315318
<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>

0 commit comments

Comments
 (0)