3af546eeee
Adds support for the `beforeOperation` hook on globals. Runs before all
other hooks to either modify the arguments that operations receive, or
perform side-effects before an operation begins.
```ts
import type { GlobalConfig } from 'payload'
const MyGlobal: GlobalConfig = {
// ...
hooks: {
beforeOperation: []
}
}
```
---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
- https://app.asana.com/0/0/1211317005907890
222 lines
12 KiB
Plaintext
222 lines
12 KiB
Plaintext
---
|
|
title: Global Hooks
|
|
label: Globals
|
|
order: 30
|
|
desc: Hooks can be added to any Global and allow you to validate data, flatten locales, hide protected fields, remove fields and more.
|
|
keywords: hooks, globals, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
Global Hooks are [Hooks](./overview) that run on [Global](../configuration/globals) Documents. They allow you to execute your own logic during specific events of the Document lifecycle.
|
|
|
|
To add Hooks to a Global, use the `hooks` property in your [Global Config](../configuration/globals):
|
|
|
|
```ts
|
|
import type { GlobalConfig } from 'payload'
|
|
|
|
export const GlobalWithHooks: GlobalConfig = {
|
|
// ...
|
|
hooks: {
|
|
// highlight-line
|
|
// ...
|
|
},
|
|
}
|
|
```
|
|
|
|
<Banner type="info">
|
|
**Tip:** You can also set hooks on the field-level to isolate hook logic to
|
|
specific fields. [More details](./fields).
|
|
</Banner>
|
|
|
|
## Config Options
|
|
|
|
All Global Hooks accept an array of [synchronous or asynchronous functions](./overview#async-vs-synchronous). Each Global Hook receives specific arguments based on its own type, and has the ability to modify specific outputs.
|
|
|
|
```ts
|
|
import type { GlobalConfig } from 'payload';
|
|
|
|
const GlobalWithHooks: GlobalConfig = {
|
|
// ...
|
|
// highlight-start
|
|
hooks: {
|
|
beforeOperation: [(args) => {...}],
|
|
beforeValidate: [(args) => {...}],
|
|
beforeChange: [(args) => {...}],
|
|
beforeRead: [(args) => {...}],
|
|
afterChange: [(args) => {...}],
|
|
afterRead: [(args) => {...}],
|
|
}
|
|
// highlight-end
|
|
}
|
|
```
|
|
|
|
### beforeOperation
|
|
|
|
The `beforeOperation` hook can be used to modify the arguments that operations accept or execute side-effects that run before an operation begins.
|
|
|
|
```ts
|
|
import type { GlobalBeforeOperationHook } from 'payload'
|
|
|
|
const beforeOperationHook: GlobalBeforeOperationHook = async ({
|
|
args,
|
|
operation,
|
|
req,
|
|
}) => {
|
|
return args // return modified operation arguments as necessary
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `beforeOperation` hook:
|
|
|
|
| Option | Description |
|
|
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`global`** | The [Global](../configuration/globals) in which this Hook is running against. Available operation include: `countVersions`, `read`, `restoreVersion`, and `update`. |
|
|
| **`context`** | Custom context passed between Hooks. [More details](./context). |
|
|
| **`operation`** | The name of the operation that this hook is running within. |
|
|
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |
|
|
|
|
### beforeValidate
|
|
|
|
Runs during the `update` operation. This hook allows you to add or format data before the incoming data is validated server-side.
|
|
|
|
Please do note that this does not run before client-side validation. If you render a custom field component in your front-end and provide it with a `validate` function, the order that validations will run in is:
|
|
|
|
1. `validate` runs on the client
|
|
2. if successful, `beforeValidate` runs on the server
|
|
3. `validate` runs on the server
|
|
|
|
```ts
|
|
import type { GlobalBeforeValidateHook } from 'payload'
|
|
|
|
const beforeValidateHook: GlobalBeforeValidateHook = async ({
|
|
data,
|
|
req,
|
|
originalDoc,
|
|
}) => {
|
|
return data
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `beforeValidate` hook:
|
|
|
|
| Option | Description |
|
|
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`global`** | The [Global](../configuration/globals) in which this Hook is running against. |
|
|
| **`context`** | Custom context passed between Hooks. [More details](./context). |
|
|
| **`data`** | The incoming data passed through the operation. |
|
|
| **`originalDoc`** | The Document before changes are applied. |
|
|
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |
|
|
|
|
### beforeChange
|
|
|
|
Immediately following validation, `beforeChange` hooks will run within the `update` operation. At this stage, you can be confident that the data that will be saved to the document is valid in accordance to your field validations. You can optionally modify the shape of data to be saved.
|
|
|
|
```ts
|
|
import type { GlobalBeforeChangeHook } from 'payload'
|
|
|
|
const beforeChangeHook: GlobalBeforeChangeHook = async ({
|
|
data,
|
|
req,
|
|
originalDoc,
|
|
}) => {
|
|
return data
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `beforeChange` hook:
|
|
|
|
| Option | Description |
|
|
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`global`** | The [Global](../configuration/globals) in which this Hook is running against. |
|
|
| **`context`** | Custom context passed between hooks. [More details](./context). |
|
|
| **`data`** | The incoming data passed through the operation. |
|
|
| **`originalDoc`** | The Document before changes are applied. |
|
|
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |
|
|
|
|
### afterChange
|
|
|
|
After a global is updated, the `afterChange` hook runs. Use this hook to purge caches of your applications, sync site data to CRMs, and more.
|
|
|
|
```ts
|
|
import type { GlobalAfterChangeHook } from 'payload'
|
|
|
|
const afterChangeHook: GlobalAfterChangeHook = async ({
|
|
doc,
|
|
previousDoc,
|
|
req,
|
|
}) => {
|
|
return data
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `afterChange` hook:
|
|
|
|
| Option | Description |
|
|
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`global`** | The [Global](../configuration/globals) in which this Hook is running against. |
|
|
| **`context`** | Custom context passed between hooks. [More details](./context). |
|
|
| **`data`** | The incoming data passed through the operation. |
|
|
| **`doc`** | The resulting Document after changes are applied. |
|
|
| **`previousDoc`** | The Document before changes were applied. |
|
|
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |
|
|
|
|
### beforeRead
|
|
|
|
Runs before `findOne` global operation is transformed for output by `afterRead`. This hook fires before hidden fields are removed and before localized fields are flattened into the requested locale. Using this Hook will provide you with all locales and all hidden fields via the `doc` argument.
|
|
|
|
```ts
|
|
import type { GlobalBeforeReadHook } from 'payload'
|
|
|
|
const beforeReadHook: GlobalBeforeReadHook = async ({
|
|
doc,
|
|
req,
|
|
}) => {...}
|
|
```
|
|
|
|
The following arguments are provided to the `beforeRead` hook:
|
|
|
|
| Option | Description |
|
|
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`global`** | The [Global](../configuration/globals) in which this Hook is running against. |
|
|
| **`context`** | Custom context passed between hooks. [More details](./context). |
|
|
| **`doc`** | The resulting Document after changes are applied. |
|
|
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |
|
|
|
|
### afterRead
|
|
|
|
Runs as the last step before a global is returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.
|
|
|
|
```ts
|
|
import type { GlobalAfterReadHook } from 'payload'
|
|
|
|
const afterReadHook: GlobalAfterReadHook = async ({
|
|
doc,
|
|
req,
|
|
findMany,
|
|
}) => {...}
|
|
```
|
|
|
|
The following arguments are provided to the `beforeRead` hook:
|
|
|
|
| Option | Description |
|
|
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`global`** | The [Global](../configuration/globals) in which this Hook is running against. |
|
|
| **`context`** | Custom context passed between hooks. [More details](./context). |
|
|
| **`findMany`** | Boolean to denote if this hook is running against finding one, or finding many (useful in versions). |
|
|
| **`doc`** | The resulting Document after changes are applied. |
|
|
| **`query`** | The [Query](../queries/overview) of the request. |
|
|
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |
|
|
|
|
## TypeScript
|
|
|
|
Payload exports a type for each Global hook which can be accessed as follows:
|
|
|
|
```ts
|
|
import type {
|
|
GlobalBeforeValidateHook,
|
|
GlobalBeforeChangeHook,
|
|
GlobalAfterChangeHook,
|
|
GlobalBeforeReadHook,
|
|
GlobalAfterReadHook,
|
|
} from 'payload'
|
|
```
|