useLockCallbacks
This Enterprise Edition hook returns callbacks to lock and unlock a record, as well as the current lock status.
Usage
Use this hook e.g. to build a lock button:
import LockIcon from '@mui/icons-material/Lock';
import LockOpenIcon from '@mui/icons-material/LockOpen';
import { CircularProgress, IconButton, Tooltip } from '@mui/material';
import { useLockCallbacks } from '@react-admin/ra-realtime';
export const LockButton = () => {
const {
lock,
isLocked,
isLockedByCurrentUser,
isPending,
isLocking,
isUnlocking,
doLock,
doUnlock,
} = useLockCallbacks();
if (isPending) {
return null;
}
return isLocked ? (
isLockedByCurrentUser ? (
<Tooltip title="Locked by you, click to unlock">
<IconButton
disabled={isUnlocking}
onClick={(e: React.MouseEvent<HTMLButtonElement>) => {
e.stopPropagation();
doUnlock();
}}
>
{isUnlocking ? (
<CircularProgress size={24} />
) : (
<LockIcon />
)}
</IconButton>
</Tooltip>
) : (
<Tooltip title={`Locked by another user: ${lock?.identity}`}>
<LockIcon color="error" sx={{ mx: 1 }} />
</Tooltip>
)
) : (
<Tooltip title="Record is unlocked, click to lock">
<IconButton
disabled={isLocking}
onClick={(e: React.MouseEvent<HTMLButtonElement>) => {
e.stopPropagation();
doLock();
}}
color="warning"
>
{isLocking ? <CircularProgress size={24} /> : <LockOpenIcon />}
</IconButton>
</Tooltip>
);
};
You can also leverage this hook as a quick way to access the lock status of the current record:
import { useLockCallbacks } from '@react-admin/ra-realtime';
import { SaveButton, Toolbar } from 'react-admin';
export const MyToolbar = () => {
const { isLockedByCurrentUser } = useLockCallbacks();
return (
<Toolbar>
<SaveButton disabled={!isLockedByCurrentUser} />
</Toolbar>
);
};
Parameters
useLockCallbacks
accepts a single options parameter, with the following properties:
Name | Required | Type | Default Value | Description |
---|---|---|---|---|
identity |
No | Identifier |
From AuthProvider.getIdentity() |
An identifier for the user who owns the lock. |
resource |
No | string |
From ResourceContext |
The resource name (e.g. 'posts' ). |
id |
No | Identifier |
From RecordContext |
The record id (e.g. 123 ). |
meta |
No | object |
- | Additional metadata forwarded to the dataProvider lock() , unlock() and getLock() calls. |
lockMutationOptions |
No | object |
- | react-query mutation options, used to customize the lock side-effects. |
unlockMutationOptions |
No | object |
- | react-query mutation options, used to customize the unlock side-effects. |
queryOptions |
No | object |
- | react-query query options, used to customize the lock query side-effects. |
You can call useLockCallbacks
with no parameter, and it will guess the resource and record id from the context (or the route):
const { isLocked, error, isLocking } = useLockCallbacks();
Or you can provide them explicitly:
const { isLocked, error, isLocking } = useLockCallbacks({
resource: 'venues',
id: 123,
identity: 'John Doe',
});
Return value
useLockCallbacks
returns an object with the following properties:
Name | Type | Description |
---|---|---|
isLocked |
boolean |
Whether the record is currently locked (possibly by another user) or not. |
isLockedByCurrentUser |
boolean |
Whether the record is locked by the current user or not. |
lock |
object |
The lock data. |
error |
object |
The error object if any of the mutations or the query fails. |
isPending |
boolean |
Whether the lock query is in progress. |
isLocking |
boolean |
Whether the lock mutation is in progress. |
isUnlocking |
boolean |
Whether the unlock mutation is in progress. |
doLock |
function |
A callback to manually lock the record. |
doUnlock |
function |
A callback to manually unlock the record. |
doLockAsync |
function |
A callback to manually lock the record asynchronously. |
doUnlockAsync |
function |
A callback to manually unlock the record asynchronously. |
lockQuery |
object |
The react-query query object for the lock status. |
lockMutation |
object |
The react-query mutation object for the lock mutation. |
unlockMutation |
object |
The react-query mutation object for the unlock mutation. |