171 lines
8.9 KiB
Plaintext
171 lines
8.9 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
|
|
---
|
|
|
|
Payload Globals are in many ways similar to [Collections](../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.
|
|
|
|
## Config Options
|
|
|
|
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 Global Configs go here
|
|
],
|
|
})
|
|
```
|
|
|
|
It's often best practice to write your Globals in separate files and then import them into the main Payload Config.
|
|
|
|
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.
|
|
</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 points to "tie in" to collection actions at specific points. [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._
|
|
|
|
|
|
### 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](../access-control/overview) docs.
|
|
|
|
### Hooks
|
|
|
|
Globals also fully support a smaller subset of Hooks. 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 Collection Admin Options, 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/types'
|
|
|
|
// This is the type used after an incoming Global config is fully sanitized.
|
|
// Generally, this is only used internally by Payload.
|
|
```
|