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
112 lines
7.3 KiB
Plaintext
112 lines
7.3 KiB
Plaintext
---
|
|
title: Global Configs
|
|
label: Globals
|
|
order: 30
|
|
desc: Set up your Global config for your needs by defining fields, adding slugs and labels, establishing access control, tying in hooks and more.
|
|
keywords: globals, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
Globals are in many ways similar to [Collections](../configuration/collections), except they correspond to only a single Document. You can define as many Globals as your application needs. Each Global Document is stored in the [Database](../database/overview) based on the [Fields](../fields/overview) that you define, and automatically generates a [Local API](../local-api/overview), [REST API](../rest-api/overview), and [GraphQL API](../graphql/overview) used to manage your Documents.
|
|
|
|
Globals are the primary way to structure singletons in Payload, such as a header navigation, site-wide banner alerts, or app-wide localized strings. Each Global can have its own unique [Access Control](../access-control/overview), [Hooks](../hooks/overview), [Admin Options](#admin-options), and more.
|
|
|
|
To define a Global Config, use the `globals` property in your [Payload Config](./overview):
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
globals: [ // highlight-line
|
|
// Your Globals go here
|
|
],
|
|
})
|
|
```
|
|
|
|
<Banner type="success">
|
|
<strong>Tip:</strong>
|
|
If you have more than one Global that share the same structure, consider using a [Collection](../configuration/collections) instead.
|
|
</Banner>
|
|
|
|
## Config Options
|
|
|
|
It's often best practice to write your Globals in separate files and then import them into the main [Payload Config](./overview).
|
|
|
|
Here is what a simple Global Config might look like:
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
export const Nav: GlobalConfig = {
|
|
slug: 'nav',
|
|
fields: [
|
|
{
|
|
name: 'items',
|
|
type: 'array',
|
|
required: true,
|
|
maxRows: 8,
|
|
fields: [
|
|
{
|
|
name: 'page',
|
|
type: 'relationship',
|
|
relationTo: 'pages', // "pages" is the slug of an existing collection
|
|
required: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
<Banner type="success">
|
|
<strong>Reminder:</strong>
|
|
For a more complex example, see the [Public Demo](https://github.com/payloadcms/public-demo) source code on GitHub, or the [Templates](https://github.com/payloadcms/payload/tree/main/templates) and [Examples](https://github.com/payloadcms/payload/tree/main/examples) directories in the Payload repository.
|
|
</Banner>
|
|
|
|
The following options are available:
|
|
|
|
| Option | Description |
|
|
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`access`** | Provide Access Control functions to define exactly who should be able to do what with this Global. [More details](../access-control/globals). |
|
|
| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/globals). |
|
|
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
|
|
| **`dbName`** | Custom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined. |
|
|
| **`description`** | Text or React component to display below the Global header to give editors more information. |
|
|
| **`endpoints`** | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints). |
|
|
| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](../fields/overview). |
|
|
| **`graphQL.name`** | Text used in schema generation. Auto-generated from slug if not defined. |
|
|
| **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#global-hooks). |
|
|
| **`label`** | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined. |
|
|
| **`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). |
|
|
| **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Global. |
|
|
| **`typescript`** | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined. |
|
|
| **`versions`** | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#globals-config). |
|
|
|
|
_\* An asterisk denotes that a property is required._
|
|
|
|
### Fields
|
|
|
|
Fields define the schema of the Global. To learn more, go to the [Fields](../fields/overview) documentation.
|
|
|
|
### Access Control
|
|
|
|
[Global Access Control](../access-control/globals) determines what a user can and cannot do with any given Global Document. To learn more, go to the [Access Control](../access-control/overview) documentation.
|
|
|
|
### Hooks
|
|
|
|
[Global Hooks](../hooks/globals) allow you to tie into the lifecycle of your Documents so you can execute your own logic during specific events. To learn more, go to the [Hooks](../hooks/overview) documentation.
|
|
|
|
### Admin Options
|
|
|
|
You can customize the way that the [Admin Panel](../admin/overview) behaves on a Global-by-Global basis. To learn more, go to the [Global Admin Options](../admin/globals) documentation.
|
|
|
|
## TypeScript
|
|
|
|
You can import types from Payload to help make writing your Global configs easier and type-safe. There are two main types that represent the Global Config, `GlobalConfig` and `SanitizeGlobalConfig`.
|
|
|
|
The `GlobalConfig` type represents a raw Global Config in its full form, where only the bare minimum properties are marked as required. The `SanitizedGlobalConfig` type represents a Global Config after it has been fully sanitized. Generally, this is only used internally by Payload.
|
|
|
|
```ts
|
|
import type { GlobalConfig, SanitizedGlobalConfig } from 'payload'
|
|
```
|