181 lines
9.7 KiB
Plaintext
181 lines
9.7 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 saves to the [Database](../database/overview) based on the [Fields](../fields/overview) that you define, and automatically generates the [Local API](../local-api/overview), [REST API](../rest-api/overview), and [GraphQL API](../graphql/overview) 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/overview/#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. [Click here](../fields/overview) for a full list of field types as well as how to configure them. |
|
|
| **`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. |
|
|
| **`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
|
|
|
|
Access Control determines what a user can and cannot do with any given Document. To learn more, go to the [Access Control](../access-control/overview) docs.
|
|
|
|
### Hooks
|
|
|
|
Hooks 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 configure Admin Options for Globals, use the `admin` property in your Global Config:
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
const MyGlobal: GlobalConfig = {
|
|
// ...
|
|
admin: { // highlight-line
|
|
// ...
|
|
},
|
|
}
|
|
```
|
|
|
|
The following options are available:
|
|
|
|
| Option | Description |
|
|
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`group`** | Text used as a label for grouping Collection and Global links together in the navigation. |
|
|
| **`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](../admin/components#globals). |
|
|
| **`preview`** | Function to generate a preview URL within the [Admin Panel](../admin/overview) for this Global that can point to your app. [More details](#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`** | Metadata overrides to apply to the [Admin Panel](../admin/overview). Included properties are `description` and `openGraph`. |
|
|
|
|
#### Preview
|
|
|
|
It is possible to display a Preview Button in the Admin Panel within the Edit View. This will allow editors to visit the frontend of your app the corresponds to the document they are actively editing. This way they can preview the latest, potentially unpublished changes.
|
|
|
|
To configure the Preview Button, set the `admin.preview` property to a function in your Global Config:
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
export const MainMenu: GlobalConfig = {
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
preview: (doc, { locale }) => {
|
|
if (doc?.slug) {
|
|
return `/${doc.slug}?locale=${locale}`
|
|
}
|
|
|
|
return null
|
|
},
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
The preview function receives two arguments:
|
|
|
|
| Argument | Description |
|
|
| --- | --- |
|
|
| **`doc`** | The document being edited |
|
|
| **`ctx`** | An object containing `locale` and `token` properties. The `token` is the currently logged-in user's JWT. |
|
|
|
|
<Banner type="success">
|
|
<strong>Reminder:</strong>
|
|
For fully working example of this, check of the official [Draft Preview Example](https://github.com/payloadcms/payload/tree/main/examples/draft-preview) in the [Examples Directory](https://github.com/payloadcms/payload/tree/main/examples).
|
|
</Banner>
|
|
|
|
## TypeScript
|
|
|
|
You can import Global types as follows:
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
// This is the type used for incoming Global configs.
|
|
// Only the bare minimum properties are marked as required.
|
|
```
|
|
|
|
```ts
|
|
import { SanitizedGlobalConfig } from 'payload'
|
|
|
|
// This is the type used after an incoming Global config is fully sanitized.
|
|
// Generally, this is only used internally by Payload.
|
|
```
|