f98d032617
## Description
Adds a new property to `collection` / `global` configs called
`lockDocuments`.
Set to `true` by default - the lock is automatically triggered when a
user begins editing a document within the Admin Panel and remains in
place until the user exits the editing view or the lock expires due to
inactivity.
Set to `false` to disable document locking entirely - i.e.
`lockDocuments: false`
You can pass an object to this property to configure the `duration` in
seconds, which defines how long the document remains locked without user
interaction. If no edits are made within the specified time (default:
300 seconds), the lock expires, allowing other users to edit / update or
delete the document.
```
lockDocuments: {
duration: 180, // 180 seconds or 3 minutes
}
```
- [x] I have read and understand the
[CONTRIBUTING.md](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md)
document in this repository.
## Type of change
- [x] New feature (non-breaking change which adds functionality)
## Checklist:
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] Existing test suite passes locally with my changes
- [x] I have made corresponding changes to the documentation
61 lines
3.6 KiB
Plaintext
61 lines
3.6 KiB
Plaintext
---
|
||
title: Document Locking
|
||
label: Document Locking
|
||
order: 90
|
||
desc: Ensure your documents are locked while being edited, preventing concurrent edits from multiple users and preserving data integrity.
|
||
keywords: locking, document locking, edit locking, document, concurrency, Payload, headless, Content Management System, cms, javascript, react, node, nextjs
|
||
---
|
||
|
||
Document locking in Payload ensures that only one user at a time can edit a document, preventing data conflicts and accidental overwrites. When a document is locked, other users are prevented from making changes until the lock is released, ensuring data integrity in collaborative environments.
|
||
|
||
The lock is automatically triggered when a user begins editing a document within the Admin Panel and remains in place until the user exits the editing view or the lock expires due to inactivity.
|
||
|
||
## How it works
|
||
|
||
When a user starts editing a document, Payload locks the document for that user. If another user tries to access the same document, they will be notified that it is currently being edited and can choose one of the following options:
|
||
|
||
- View in Read-Only Mode: View the document without making any changes.
|
||
- Take Over Editing: Take over editing from the current user, which locks the document for the new editor and notifies the original user.
|
||
- Return to Dashboard: Navigate away from the locked document and continue with other tasks.
|
||
|
||
The lock will automatically expire after a set period of inactivity, configurable using the duration property in the lockDocuments configuration, after which others can resume editing.
|
||
|
||
<Banner type="info"> <strong>Note:</strong> If your application does not require document locking, you can disable this feature for any collection by setting the <code>lockDocuments</code> property to <code>false</code>. </Banner>
|
||
|
||
### Config Options
|
||
|
||
The lockDocuments property exists on both the Collection Config and the Global Config. By default, document locking is enabled for all collections and globals, but you can customize the lock duration or disable the feature entirely.
|
||
|
||
Here’s an example configuration for document locking:
|
||
|
||
```ts
|
||
import { CollectionConfig } from 'payload'
|
||
|
||
export const Posts: CollectionConfig = {
|
||
slug: 'posts',
|
||
fields: [
|
||
{
|
||
name: 'title',
|
||
type: 'text',
|
||
},
|
||
// other fields...
|
||
],
|
||
lockDocuments: {
|
||
duration: 600, // Duration in seconds
|
||
},
|
||
}
|
||
```
|
||
|
||
#### Locking Options
|
||
|
||
| Option | Description |
|
||
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| **`lockDocuments`** | Enables or disables document locking for the collection or global. By default, document locking is enabled. Set to an object to configure, or set to false to disable locking. |
|
||
| **`duration`** | Specifies the duration (in seconds) for how long a document remains locked without user interaction. The default is 300 seconds (5 minutes). |
|
||
|
||
### Impact on APIs
|
||
|
||
Document locking affects both the Local API and the REST API, ensuring that if a document is locked, concurrent users will not be able to perform updates or deletes on that document (including globals). If a user attempts to update or delete a locked document, they will receive an error.
|
||
|
||
Once the document is unlocked or the lock duration has expired, other users can proceed with updates or deletes as normal.
|