95 lines
4.1 KiB
Plaintext
95 lines
4.1 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, express
|
|
---
|
|
|
|
Global configs are in many ways similar to [Collections](/docs/configuration/collections). The big difference is that Collections will potentially contain *many* documents, while a Global is a "one-off". Globals are perfect for things like header nav, site-wide banner alerts, app-wide localized strings, and other "global" data that your site or app might rely on.
|
|
|
|
As with Collection configs, it's often best practice to write your Globals in separate files and then import them into the main Payload config.
|
|
|
|
## Options
|
|
|
|
| Option | Description |
|
|
| ---------------- | -------------|
|
|
| **`slug`** * | Unique, URL-friendly string that will act as an identifier for this Global. |
|
|
| **`fields`** * | Array of field types that will determine the structure and functionality of the data stored within this Global. [Click here](/docs/fields/overview) for a full list of field types as well as how to configure them. |
|
|
| **`label`** | Singular label for use in identifying this Global throughout Payload. Auto-generated from slug if not defined. |
|
|
| **`description`**| Text or React component to display below the Global header to give editors more information. |
|
|
| **`admin`** | Admin-specific configuration. See below for [more detail](/docs/configuration/globals#admin-options). |
|
|
| **`hooks`** | Entry points to "tie in" to collection actions at specific points. [More](/docs/hooks/overview#global-hooks) |
|
|
| **`access`** | Provide access control functions to define exactly who should be able to do what with this Global. [More](/docs/access-control/overview/#globals) |
|
|
|
|
*\* An asterisk denotes that a property is required.*
|
|
|
|
#### Simple Global example
|
|
|
|
```js
|
|
const Nav = {
|
|
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,
|
|
}
|
|
]
|
|
},
|
|
]
|
|
}
|
|
```
|
|
|
|
#### More Global config examples
|
|
|
|
You can find an assortment of [example Global configs](https://github.com/payloadcms/payload/blob/master/demo/globals) in the Payload source code on GitHub.
|
|
|
|
### Admin options
|
|
|
|
You can customize the way that the Admin panel behaves on a Global-by-Global basis by defining the `admin` property on a Global's config.
|
|
|
|
| Option | Description |
|
|
| ---------------------------- | -------------|
|
|
| `components` | Swap in your own React components to be used within this Global. [More](/docs/admin/components#globals) |
|
|
|
|
### Access control
|
|
|
|
As with Collections, you can specify extremely granular access control (what users can do with this Global) on a Global-by-Global basis. However, Globals only have `update` and `read` access control due to their nature of only having one document. To learn more, go to the [Access Control](/docs/access-control/overview) docs.
|
|
|
|
### Hooks
|
|
|
|
Globals also fully support a smaller subset of Hooks. To learn more, go to the [Hooks](/docs/hooks/overview) documentation.
|
|
|
|
### Field types
|
|
|
|
Globals support all field types that Payload has to offer—including simple fields like text and checkboxes all the way to more complicated layout-building field groups like Blocks. [Click here](/docs/fields/overview) to learn more about field types.
|
|
|
|
### TypeScript
|
|
|
|
You can import global types as follows:
|
|
|
|
```js
|
|
import { GlobalConfig } from 'payload/types';
|
|
|
|
// This is the type used for incoming global configs.
|
|
// Only the bare minimum properties are marked as required.
|
|
```
|
|
|
|
```js
|
|
import { SanitizedGlobalConfig } from 'payload/types';
|
|
|
|
// This is the type used after an incoming global config is fully sanitized.
|
|
|
|
// If you are building a plugin, you might benefit from this type,
|
|
// as plugins interact will fully defaulted, sanitized, and validated
|
|
// global configs.
|
|
```
|