9f9db3ff81
## Introducing Prettier for docs
Prettier [was originally disabled for our docs as it didn't support MDX
2.0](1fa636417f),
outputting invalid MDX syntax.
This has since been fixed - prettier now supports MDX 2.0.
## Reducing print width
This also reduces the print width for the docs folder from 100 to 70.
Our docs code field are very narrow - this should help make code more
readable.
**Before**
**After**
**Before**
**After**
215 lines
13 KiB
Plaintext
215 lines
13 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](./collections), except that 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">
|
|
**Tip:** If you have more than one Global that share the same structure,
|
|
consider using a [Collection](./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">
|
|
**Reminder:** For more complex examples, see 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-options). |
|
|
| `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` | Manage GraphQL-related properties related to this global. [More details](#graphql) |
|
|
| `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#global-config). |
|
|
| `forceSelect` | Specify which fields should be selected always, regardless of the `select` query which can be useful that the field exists for access control / hooks |
|
|
|
|
_\* 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
|
|
|
|
The behavior of Globals within the [Admin Panel](../admin/overview) can be fully customized to fit the needs of your application. This includes grouping or hiding their navigation links, adding [Custom Components](../custom-components/overview), setting page metadata, and more.
|
|
|
|
To configure Admin Options for Globals, use the `admin` property in your Global Config:
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
export const MyGlobal: GlobalConfig = {
|
|
// ...
|
|
admin: {
|
|
// highlight-line
|
|
// ...
|
|
},
|
|
}
|
|
```
|
|
|
|
The following options are available:
|
|
|
|
| Option | Description |
|
|
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `group` | Text or localization object used to group Collection and Global links in the admin navigation. Set to `false` to hide the link from the navigation while keeping its routes accessible. |
|
|
| `hidden` | Set to true or a function, called with the current user, returning true to exclude this Global from navigation and admin routing. |
|
|
| `components` | Swap in your own React components to be used within this Global. [More details](#custom-components). |
|
|
| `preview` | Function to generate a preview URL within the Admin Panel for this Global that can point to your app. [More details](../admin/preview). |
|
|
| `livePreview` | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview). |
|
|
| `hideAPIURL` | Hides the "API URL" meta field while editing documents within this collection. |
|
|
| `meta` | Page metadata overrides to apply to this Global within the Admin Panel. [More details](../admin/metadata). |
|
|
|
|
### Custom Components
|
|
|
|
Globals can set their own [Custom Components](../custom-components/overview) which only apply to Global-specific UI within the [Admin Panel](../admin/overview). This includes elements such as the Save Button, or entire layouts such as the Edit View.
|
|
|
|
To override Global Components, use the `admin.components` property in your Global Config:
|
|
|
|
```ts
|
|
import type { SanitizedGlobalConfig } from 'payload'
|
|
|
|
export const MyGlobal: SanitizedGlobalConfig = {
|
|
// ...
|
|
admin: {
|
|
components: {
|
|
// highlight-line
|
|
// ...
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
The following options are available:
|
|
|
|
#### General
|
|
|
|
| Option | Description |
|
|
| ---------- | ------------------------------------------------------------------------------------------------------- |
|
|
| `elements` | Override or create new elements within the Edit View. [More details](#edit-view-options). |
|
|
| `views` | Override or create new views within the Admin Panel. [More details](../custom-components/custom-views). |
|
|
|
|
#### Edit View Options
|
|
|
|
```ts
|
|
import type { SanitizedGlobalConfig } from 'payload'
|
|
|
|
export const MyGlobal: SanitizedGlobalConfig = {
|
|
// ...
|
|
admin: {
|
|
components: {
|
|
elements: {
|
|
// highlight-line
|
|
// ...
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
The following options are available:
|
|
|
|
| Option | Description |
|
|
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `SaveButton` | Replace the default Save Button with a Custom Component. [Drafts](../versions/drafts) must be disabled. [More details](../custom-components/edit-view#save-button). |
|
|
| `SaveDraftButton` | Replace the default Save Draft Button with a Custom Component. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. [More details](../custom-components/edit-view#save-draft-button). |
|
|
| `PublishButton` | Replace the default Publish Button with a Custom Component. [Drafts](../versions/drafts) must be enabled. [More details](../custom-components/edit-view#publish-button). |
|
|
| `PreviewButton` | Replace the default Preview Button with a Custom Component. [Preview](../admin/preview) must be enabled. [More details](../custom-components/edit-view#preview-button). |
|
|
|
|
<Banner type="success">
|
|
**Note:** For details on how to build Custom Components, see [Building Custom
|
|
Components](../custom-components/overview#building-custom-components).
|
|
</Banner>
|
|
|
|
## GraphQL
|
|
|
|
You can completely disable GraphQL for this global by passing `graphQL: false` to your global config. This will completely disable all queries, mutations, and types from appearing in your GraphQL schema.
|
|
|
|
You can also pass an object to the global's `graphQL` property, which allows you to define the following properties:
|
|
|
|
| Option | Description |
|
|
| ------------------ | ------------------------------------------------------------------------------- |
|
|
| `name` | Override the name that will be used in GraphQL schema generation. |
|
|
| `disableQueries` | Disable all GraphQL queries that correspond to this global by passing `true`. |
|
|
| `disableMutations` | Disable all GraphQL mutations that correspond to this global by passing `true`. |
|
|
|
|
## 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'
|
|
```
|