Skip to content

Commit f98d032

Browse files
PatrikKozakPatrikKozak
authored
feat: lock documents while being edited (#7970)
## 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
1 parent 05a3cc4 commit f98d032

File tree

119 files changed

+10685
-6363
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

119 files changed

+10685
-6363
lines changed

‎.github/workflows/main.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,7 @@ jobs:
310310
- fields__collections__Upload
311311
- live-preview
312312
- localization
313+
- locked-documents
313314
- i18n
314315
- plugin-cloud-storage
315316
- plugin-form-builder

‎.vscode/launch.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,13 @@
118118
"request": "launch",
119119
"type": "node-terminal"
120120
},
121+
{
122+
"command": "node --no-deprecation test/dev.js locked-documents",
123+
"cwd": "${workspaceFolder}",
124+
"name": "Run Dev Locked Documents",
125+
"request": "launch",
126+
"type": "node-terminal"
127+
},
121128
{
122129
"command": "node --no-deprecation test/dev.js uploads",
123130
"cwd": "${workspaceFolder}",

‎docs/admin/locked-documents.mdx

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: Document Locking
3+
label: Document Locking
4+
order: 90
5+
desc: Ensure your documents are locked while being edited, preventing concurrent edits from multiple users and preserving data integrity.
6+
keywords: locking, document locking, edit locking, document, concurrency, Payload, headless, Content Management System, cms, javascript, react, node, nextjs
7+
---
8+
9+
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.
10+
11+
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.
12+
13+
## How it works
14+
15+
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:
16+
17+
- View in Read-Only Mode: View the document without making any changes.
18+
- Take Over Editing: Take over editing from the current user, which locks the document for the new editor and notifies the original user.
19+
- Return to Dashboard: Navigate away from the locked document and continue with other tasks.
20+
21+
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.
22+
23+
<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>
24+
25+
### Config Options
26+
27+
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.
28+
29+
Here’s an example configuration for document locking:
30+
31+
```ts
32+
import { CollectionConfig } from 'payload'
33+
34+
export const Posts: CollectionConfig = {
35+
slug: 'posts',
36+
fields: [
37+
{
38+
name: 'title',
39+
type: 'text',
40+
},
41+
// other fields...
42+
],
43+
lockDocuments: {
44+
duration: 600, // Duration in seconds
45+
},
46+
}
47+
```
48+
49+
#### Locking Options
50+
51+
| Option | Description |
52+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
53+
| **`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. |
54+
| **`duration`** | Specifies the duration (in seconds) for how long a document remains locked without user interaction. The default is 300 seconds (5 minutes). |
55+
56+
### Impact on APIs
57+
58+
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.
59+
60+
Once the document is unlocked or the lock duration has expired, other users can proceed with updates or deletes as normal.

‎docs/configuration/collections.mdx

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -57,25 +57,26 @@ export const Posts: CollectionConfig = {
5757

5858
The following options are available:
5959

60-
| Option | Description |
61-
|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
62-
| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/collections). |
63-
| **`access`** | Provide Access Control functions to define exactly who should be able to do what with Documents in this Collection. [More details](../access-control/collections). |
64-
| **`auth`** | Specify options if you would like this Collection to feature authentication. [More details](../authentication/overview). |
65-
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
66-
| **`disableDuplicate`** | When true, do not show the "Duplicate" button while editing documents within this Collection and prevent `duplicate` from all APIs. |
67-
| **`defaultSort`** | Pass a top-level field to sort by default in the Collection List View. Prefix the name of the field with a minus symbol ("-") to sort in descending order. |
68-
| **`dbName`** | Custom table or Collection name depending on the Database Adapter. Auto-generated from slug if not defined. |
69-
| **`endpoints`** | Add custom routes to the REST API. Set to `false` to disable routes. [More details](../rest-api/overview#custom-endpoints). |
70-
| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Collection. [More details](../fields/overview). |
71-
| **`graphQL`** | An object with `singularName` and `pluralName` strings used in schema generation. Auto-generated from slug if not defined. Set to `false` to disable GraphQL. |
72-
| **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#collection-hooks). |
73-
| **`labels`** | Singular and plural labels for use in identifying this Collection throughout Payload. Auto-generated from slug if not defined. |
74-
| **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Collection. |
75-
| **`timestamps`** | Set to false to disable documents' automatically generated `createdAt` and `updatedAt` timestamps. |
76-
| **`typescript`** | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined. |
77-
| **`upload`** | Specify options if you would like this Collection to support file uploads. For more, consult the [Uploads](../upload/overview) documentation. |
78-
| **`versions`** | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#collection-config). |
60+
| Option | Description |
61+
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62+
| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/collections). |
63+
| **`access`** | Provide Access Control functions to define exactly who should be able to do what with Documents in this Collection. [More details](../access-control/collections). |
64+
| **`auth`** | Specify options if you would like this Collection to feature authentication. [More details](../authentication/overview). |
65+
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
66+
| **`disableDuplicate`** | When true, do not show the "Duplicate" button while editing documents within this Collection and prevent `duplicate` from all APIs. |
67+
| **`defaultSort`** | Pass a top-level field to sort by default in the Collection List View. Prefix the name of the field with a minus symbol ("-") to sort in descending order. |
68+
| **`dbName`** | Custom table or Collection name depending on the Database Adapter. Auto-generated from slug if not defined. |
69+
| **`endpoints`** | Add custom routes to the REST API. Set to `false` to disable routes. [More details](../rest-api/overview#custom-endpoints). |
70+
| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Collection. [More details](../fields/overview). |
71+
| **`graphQL`** | An object with `singularName` and `pluralName` strings used in schema generation. Auto-generated from slug if not defined. Set to `false` to disable GraphQL. |
72+
| **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#collection-hooks). |
73+
| **`labels`** | Singular and plural labels for use in identifying this Collection throughout Payload. Auto-generated from slug if not defined. |
74+
| **`lockDocuments`** | Enables or disables document locking. By default, document locking is enabled. Set to an object to configure, or set to `false` to disable locking. [More details](../admin/locked-documents). |
75+
| **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Collection. |
76+
| **`timestamps`** | Set to false to disable documents' automatically generated `createdAt` and `updatedAt` timestamps. |
77+
| **`typescript`** | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined. |
78+
| **`upload`** | Specify options if you would like this Collection to support file uploads. For more, consult the [Uploads](../upload/overview) documentation. |
79+
| **`versions`** | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#collection-config). |
7980

8081
_\* An asterisk denotes that a property is required._
8182

‎docs/configuration/globals.mdx

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -65,21 +65,22 @@ export const Nav: GlobalConfig = {
6565

6666
The following options are available:
6767

68-
| Option | Description |
69-
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70-
| **`access`** | Provide Access Control functions to define exactly who should be able to do what with this Global. [More details](../access-control/globals). |
71-
| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/globals). |
72-
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
73-
| **`dbName`** | Custom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined. |
74-
| **`description`** | Text or React component to display below the Global header to give editors more information. |
75-
| **`endpoints`** | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints). |
76-
| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](../fields/overview). |
77-
| **`graphQL.name`** | Text used in schema generation. Auto-generated from slug if not defined. |
78-
| **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#global-hooks). |
79-
| **`label`** | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined. |
80-
| **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Global. |
81-
| **`typescript`** | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined. |
82-
| **`versions`** | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#globals-config). |
68+
| Option | Description |
69+
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70+
| **`access`** | Provide Access Control functions to define exactly who should be able to do what with this Global. [More details](../access-control/globals). |
71+
| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/globals). |
72+
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
73+
| **`dbName`** | Custom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined. |
74+
| **`description`** | Text or React component to display below the Global header to give editors more information. |
75+
| **`endpoints`** | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints). |
76+
| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](../fields/overview). |
77+
| **`graphQL.name`** | Text used in schema generation. Auto-generated from slug if not defined. |
78+
| **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#global-hooks). |
79+
| **`label`** | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined. |
80+
| **`lockDocuments`** | Enables or disables document locking. By default, document locking is enabled. Set to an object to configure, or set to `false` to disable locking. [More details](../admin/locked-documents). |
81+
| **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Global. |
82+
| **`typescript`** | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined. |
83+
| **`versions`** | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#globals-config). |
8384

8485
_\* An asterisk denotes that a property is required._
8586

0 commit comments

Comments
 (0)